510-mcp-servers

MCP Server Engineering Ruleset

Goal: Build MCP servers with rich, AI-agent-friendly documentation that enables effective tool selection and usage.

About MCP

The Model Context Protocol (MCP) is a vendor-neutral, open standard managed by the Linux Foundation's Agentic AI Foundation. MCP enables consistent AI agent integration across platforms (Claude Code, Cursor, GitHub Copilot, and others), solving the n×m integration problem where every AI client had to integrate separately with every tool.

Key Capabilities:

• Multi-vendor: GitHub, Microsoft, OpenAI, Anthropic, community-supported
• Enterprise-ready: OAuth for remote servers, no proprietary tokens
• Long-running tasks: Support for builds, deployments, multi-minute operations
• Discoverable: MCP Registry for governance and discoverability
• Production-grade: Industry-standard maturity (like Kubernetes, GraphQL)

Core Principle

Exception to lean comment rules: MCP tools require detailed docstrings because AI agents rely on them for tool selection and usage. Unlike human-facing code, agents need rich descriptions to understand capabilities and constraints. This is critical for vendor-neutral AI agent ecosystems.

Tool Documentation Standards

Docstring Structure

MCP tool docstrings serve as API documentation for AI agents. They must be comprehensive:

@mcp.tool
async def kubectl(args: str) -> str:
    """Execute kubectl commands for Kubernetes cluster management.

    Use this tool for all kubectl operations. Provide the kubectl
    arguments as a single string (e.g., "get pods -n default").

    **Important:** This tool requires kubectl to be installed and
    configured with cluster access. Commands are executed with the
    current user's kubeconfig context.

    Args:
        args: kubectl command arguments as a single string.
              Examples:
              - "get pods -n default"
              - "apply -f deployment.yaml"
              - "logs pod-name -n namespace --tail=100"

    Returns:
        JSON string with structure:
        {
            "stdout": "command output",
            "stderr": "error output (empty if success)",
            "statusCode": 0
        }

        Status codes:
        - 0: Success
        - 1: General error
        - 2: Misuse of command

    Raises:
        RuntimeError: If kubectl is not installed or not in PATH

    Example:
        >>> result = await kubectl("get pods -n default")
        >>> data = json.loads(result)
        >>> print(data["stdout"])
        NAME                    READY   STATUS    RESTARTS   AGE
        pod-123                 1/1     Running   0          5m
    """