mcp-builder

Files (9)

• SKILL.md
• evaluation.md · reference/
• mcp_best_practices.md · reference/
• node_mcp_server.md · reference/
• python_mcp_server.md · reference/
• connections.py · scripts/
• evaluation.py · scripts/
• example_evaluation.xml · scripts/
• requirements.txt · scripts/

SKILL.md (first lines)

# MCP Server Development Guide

## Overview

Build MCP (Model Context Protocol) servers that let LLMs interact with external services through well-designed tools. The quality of an MCP server is measured by how well it lets an LLM solve real tasks.

---

# Process

## High-level workflow

Building a high-quality MCP server has four main phases:

### Phase 1: Deep research and planning

#### 1.1 Understand modern MCP design

**API coverage vs. workflow tools:**
Balance full API endpoint coverage against specialized workflow tools. Workflow tools may be more convenient for specific tasks, while full coverage gives agents flexibility to combine operations. Performance depends on the client — some clients benefit from code execution that composes primitive tools, while others work better with higher-level tools. When in doubt, prioritize full API coverage.

**Tool naming and discoverability:**
Clear, descriptive tool names help agents quickly locate the tool they need. Use consistent prefixes (e.g. `github_create_issue`, `github_list_repos`) and action-oriented naming.

**Context management:**
Agents benefit from concise tool descriptions and the ability to filter or paginate results. Design tools to return focused, relevant data. Some clients support code execution, which helps agents filter and process data more efficiently.

**Actionable error messages:**
Error messages should guide the agent to a solution with concrete hints and next steps.

#### 1.2 Study the MCP protocol documentation

**Navigate the MCP specification:**

Start with the sitemap to find relevant pages: `https://modelcontextprotocol.io/sitemap.xml`

Then fetch specific pages with the `.md` suffix for markdown format (e.g. `https://modelcontextprotocol.io/specification/draft.md`).

Key pages to review:
- Specification overview and architecture
- Transport mechanisms (streamable HTTP, stdio)
- Tool, resource, and prompt definitions

#### 1.3 Study the framework documentation

**Recommended stack:**
- **Language**: TypeScript (high-quality SDK support and good compatibility across many runtimes such as MCPB. AI models also generate TypeScript code well, benefiting from its wide adoption, static typing, and strong linters)
- **Transport**: Streamable HTTP for remote servers using stateless JSON (easier to scale and operate than stateful sessions and streaming responses). stdio for local servers.

**Load the framework documentation:**

- **MCP Best Practices**: [Best practices](./reference/mcp_best_practices.md) — core recommendations

**For TypeScript (recommended):**
- **TypeScript SDK**: use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
- [TypeScript guide](./reference/node_mcp_server.md) — TypeScript patterns and examples

**For Python:**
- **Python SDK**: use WebFetch to load `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
- [Python guide](./reference/python_mcp_server.md) — Python patterns and examples

#### 1.4 Plan the implementation

**Understand the API:**
Study the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.

**Tool selection:**
Prioritize full API coverage. List the endpoints to implement, starting with the most common operations.

---

### Phase 2: Implementation

#### 2.1 Set up the project structure

See language-specific guides for project setup:
- [TypeScript guide](./reference/node_mcp_server.md) — project structure, package.json, tsconfig.json
- [Python guide](./reference/python_mcp_server.md) — module organization, dependencies

#### 2.2 Implement the base infrastructure

Create shared utilities:
- API client with authentication
- Error-handling helpers
- Response formatting (JSON/Markdown)
- Pagination support

#### 2.3 Implement the tools

For each tool:

**Input schema:**
- Use Zod (TypeScript) or Pydantic (Python)
- Include constraints and clear descriptions
- Add examples in field descriptions

**Output schema:**
- Where possible, define `outputSchema` for structured data
- Use `structuredContent` in tool responses (a TypeScript SDK capability)
- Helps clients understand and process tool output

**Tool description:**
- Brief summary of functionality
- Parameter descriptions
- Return type schema

**Implementation:**
- Async/await for I/O operations
- Proper error handling with actionable messages
- Pagination support where applicable
- Return both text content and structured data when using modern SDKs

**Annotations:**
- `readOnlyHint`: true/false
- `destructiveHint`: true/false
- `idempotentHint`: true/false
- `openWorldHint`: true/false

---

From wachawo/claude-skills, MIT.

More from wachawo/claude-skills