mcp-builder

Build MCP servers that enable LLMs to interact with external services through thoughtfully designed tools.

Key Principle: Don't simply wrap API endpoints—build thoughtful, high-impact workflow tools.

Phase 1: Research & Planning

• Study agent-centric design principles
• Review MCP protocol documentation
• Study target API documentation exhaustively
• Create detailed implementation plan

Phase 2: Implementation

• Set up project structure
• Build core infrastructure (auth, request helpers, formatters)
• Implement tools with JSON Schema validation
• Follow language-specific best practices

Phase 3: Review & Refine

• Code quality review (DRY, consistency, error handling)
• Test safely using evaluation harness
• Verify against quality checklist

Phase 4: Create Evaluations

• Design 10 complex, realistic test questions
• Create XML-formatted evaluation files
• Verify answers independently

| Type | Transport | Use Case |

|------|-----------|----------|

| stdio | Process pipes | Local custom servers |

| HTTP | REST | Cloud-hosted servers |

| SSE | Server-Sent Events | Real-time updates |

| WebSocket | Bidirectional | Real-time communication |

```typescript

// Good: Workflow-oriented

async function analyzeAndSummarize(url: string) {

// Fetches, parses, and summarizes in one call

}

// Avoid: Simple API wrapper

async function fetchPage(url: string) {

// Just wraps fetch()

}

```

TypeScript

```typescript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({

name: "my-server",

version: "1.0.0"

}, {

capabilities: { tools: {} }

});

```

Python (FastMCP)

```python

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()

def my_tool(param: str) -> str:

"""Tool description."""

return result

```

1. JSON Schema validation on all inputs/outputs
2. Comprehensive error handling with meaningful messages
3. Logging to stderr (stdout reserved for protocol)
4. Security-first - validate inputs, manage sessions
5. Configurable detail levels for context efficiency
6. Tool annotations - mark read-only, destructive, idempotent