Back to Details

protocol-implementation-framework

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MCP Server Development Guide

MCP 服务器开发指南

Overview

概述

Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.
创建MCP（Model Context Protocol，模型上下文协议）服务器，使大语言模型（LLMs）能够通过设计精良的工具与外部服务进行交互。MCP服务器的质量衡量标准是其能否有效帮助大语言模型完成实际任务。

Process

开发流程

🚀 High-Level Workflow

🚀 整体工作流

Creating a high-quality MCP server involves four main phases:
创建高质量的MCP服务器包含四个主要阶段：

Phase 1: Deep Research and Planning

阶段1：深度调研与规划

1.1 Understand Modern MCP Design

1.1 理解现代MCP设计理念

API Coverage vs. Workflow Tools: Balance comprehensive API endpoint coverage with specialized workflow tools. Workflow tools can be more convenient for specific tasks, while comprehensive coverage gives agents flexibility to compose operations. Performance varies by client—some clients benefit from code execution that combines basic tools, while others work better with higher-level workflows. When uncertain, prioritize comprehensive API coverage.
Tool Naming and Discoverability: Clear, descriptive tool names help agents find the right tools quickly. 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/paginate results. Design tools that return focused, relevant data. Some clients support code execution which can help agents filter and process data efficiently.
Actionable Error Messages: Error messages should guide agents toward solutions with specific suggestions and next steps.
Evaluation-Driven Iteration: Draft a few realistic evaluation questions early, then refine tool design based on where agents struggle.
API覆盖范围 vs 工作流工具： 在全面覆盖API端点与提供专用工作流工具之间取得平衡。工作流工具针对特定任务更便捷，而全面的API覆盖则能让Agent灵活组合操作。不同客户端的性能表现有所差异——部分客户端受益于结合基础工具的代码执行，而其他客户端则更适配高层级工作流。若不确定优先级，优先选择全面覆盖API。
工具命名与可发现性： 清晰、具有描述性的工具名称能帮助Agent快速找到合适的工具。使用一致的前缀（例如
github_create_issue
、
github_list_repos
）和面向动作的命名方式。
上下文管理： Agent会受益于简洁的工具描述，以及对结果进行筛选/分页的能力。设计返回聚焦、相关数据的工具。部分客户端支持代码执行，可帮助Agent高效筛选和处理数据。
可操作的错误信息： 错误信息应通过具体建议和下一步操作指引Agent找到解决方案。
基于评估的迭代： 尽早拟定几个真实的评估问题，然后根据Agent的薄弱环节优化工具设计。

1.2 Study MCP Protocol Documentation

1.2 研读MCP协议文档

Navigate the MCP specification:
Prefer the full spec text at 
https://modelcontextprotocol.io/llms-full.txt
. If you need targeted pages, start with the sitemap: 
https://modelcontextprotocol.io/sitemap.xml
Then fetch specific pages with 
.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
查阅MCP规范：
优先查看完整规范文本：
https://modelcontextprotocol.io/llms-full.txt
。 若需要针对性页面，可先查看站点地图：
https://modelcontextprotocol.io/sitemap.xml
随后可通过添加
.md
后缀获取Markdown格式的特定页面（例如
https://modelcontextprotocol.io/specification/draft.md
）。
需要重点查看的页面：
  • 规范概述与架构
  • 传输机制（可流式HTTP、标准输入输出stdio）
  • 工具、资源与提示词定义

1.3 Study Framework Documentation

1.3 研读框架文档

Recommended stack:
  • Language: TypeScript (high-quality SDK support and good compatibility in many execution environments e.g. MCPB. Plus AI models are good at generating TypeScript code, benefiting from its broad usage, static typing and good linting tools)
  • Transport: Streamable HTTP for remote servers, using stateless JSON (simpler to scale and maintain, as opposed to stateful sessions and streaming responses). stdio for local servers.
Load framework documentation:
  • MCP Best Practices: 📋 View Best Practices - Core guidelines
For TypeScript (recommended):
  • TypeScript SDK: Use WebFetch to load 
    https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • ⚡ TypeScript Guide - TypeScript patterns and examples
For Python:
  • Python SDK: Use WebFetch to load 
    https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Python Guide - Python patterns and examples
推荐技术栈：
  • 编程语言：TypeScript（拥有高质量SDK支持，在多种执行环境如MCPB中兼容性良好。此外，AI模型擅长生成TypeScript代码，得益于其广泛的使用度、静态类型系统和优秀的代码检查工具）
  • 传输方式：远程服务器使用可流式HTTP，采用无状态JSON（相较于有状态会话和流式响应，更易于扩展和维护）；本地服务器使用标准输入输出stdio。
加载框架文档：
  • MCP最佳实践：📋 查看最佳实践 - 核心指导原则
TypeScript（推荐）：
  • TypeScript SDK：使用WebFetch加载
    https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • ⚡ TypeScript指南 - TypeScript模式与示例
Python：
  • Python SDK：使用WebFetch加载
    https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • 🐍 Python指南 - Python模式与示例

1.4 Plan Your Implementation

1.4 规划实现方案

Understand the API: Review the service's API documentation to identify key endpoints, authentication requirements, and data models. Use web search and WebFetch as needed.
Tool Selection: Prioritize comprehensive API coverage. List endpoints to implement, starting with the most common operations.
理解目标API： 查阅服务的API文档，确定关键端点、认证要求和数据模型。必要时可使用网络搜索和WebFetch工具。
工具选择： 优先考虑全面覆盖API。列出需要实现的端点，从最常用的操作开始。

Phase 2: Implementation

阶段2：实现开发

2.1 Set Up Project Structure

2.1 搭建项目结构

See language-specific guides for project setup:
  • ⚡ TypeScript Guide - Project structure, package.json, tsconfig.json
  • 🐍 Python Guide - Module organization, dependencies
可参考各语言专属指南进行项目搭建：
  • ⚡ TypeScript指南 - 项目结构、package.json、tsconfig.json配置
  • 🐍 Python指南 - 模块组织、依赖管理

2.2 Implement Core Infrastructure

2.2 实现核心基础设施

Create shared utilities:
  • API client with authentication
  • Error handling helpers
  • Response formatting (JSON/Markdown)
  • Pagination support
创建共享工具类：
  • 带认证功能的API客户端
  • 错误处理助手
  • 响应格式化（JSON/Markdown）
  • 分页支持

2.3 Implement Tools

2.3 实现工具功能

For each tool:
Input Schema:
  • Use Zod (TypeScript) or Pydantic (Python)
  • Include constraints and clear descriptions
  • Add examples in field descriptions
Output Schema:
  • Define 
    outputSchema
    where possible for structured data
  • Use 
    structuredContent
    in tool responses (TypeScript SDK feature)
  • Helps clients understand and process tool outputs
Tool Description:
  • Concise summary of functionality
  • Parameter descriptions
  • Return type schema
Implementation:
  • Async/await for I/O operations
  • Proper error handling with actionable messages
  • Support pagination 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
针对每个工具：
输入Schema：
  • 使用Zod（TypeScript）或Pydantic（Python）
  • 包含约束条件和清晰的描述
  • 在字段描述中添加示例
输出Schema：
  • 尽可能定义
    outputSchema
    以返回结构化数据
  • 在工具响应中使用
    structuredContent
    （TypeScript SDK特性）
  • 帮助客户端理解和处理工具输出
工具描述：
  • 简洁的功能概述
  • 参数说明
  • 返回类型Schema
实现细节：
  • 使用Async/await处理I/O操作
  • 带有可操作提示的完善错误处理
  • 支持分页（如适用）
  • 使用现代SDK时，同时返回文本内容和结构化数据
注解：
  • readOnlyHint
    : true/false
  • destructiveHint
    : true/false
  • idempotentHint
    : true/false
  • openWorldHint
    : true/false

Phase 3: Review and Test

阶段3：审查与测试

3.1 Code Quality

3.1 代码质量

Review for:
  • No duplicated code (DRY principle)
  • Consistent error handling
  • Full type coverage
  • Clear tool descriptions
审查要点：
  • 无重复代码（遵循DRY原则）
  • 一致的错误处理
  • 完整的类型覆盖
  • 清晰的工具描述

3.2 Build and Test

3.2 构建与测试

Note: MCP servers are long-running processes. If you run them directly, your process will block waiting for requests. Prefer the evaluation harness, or run the server in a separate session (tmux) or with a timeout.
TypeScript:
  • Run 
    npm run build
    to verify compilation
  • Test with MCP Inspector: 
    npx @modelcontextprotocol/inspector
Python:
  • Verify syntax: 
    python -m py_compile your_server.py
  • Test with MCP Inspector
See language-specific guides for detailed testing approaches and quality checklists.
**注意：**MCP服务器是长运行进程。如果直接运行，进程会阻塞等待请求。建议使用评估测试框架，或在独立会话（如tmux）中运行服务器，或设置超时时间。
TypeScript：
  • 运行
    npm run build
    验证编译是否通过
  • 使用MCP Inspector测试：
    npx @modelcontextprotocol/inspector
Python：
  • 验证语法：
    python -m py_compile your_server.py
  • 使用MCP Inspector测试
详细的测试方法和质量检查清单可参考各语言专属指南。

Phase 4: Create Evaluations

阶段4：创建评估用例

After implementing your MCP server, create comprehensive evaluations to test its effectiveness.
Load ✅ Evaluation Guide for complete evaluation guidelines.
完成MCP服务器实现后，创建全面的评估用例以测试其有效性。
加载✅ 评估指南获取完整的评估指导。

4.1 Understand Evaluation Purpose

4.1 理解评估目的

Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.
通过评估测试大语言模型能否有效使用你的MCP服务器来回答真实、复杂的问题。

4.2 Create 10 Evaluation Questions

4.2 创建10个评估问题

To create effective evaluations, follow the process outlined in the evaluation guide:
  1. Tool Inspection: List available tools and understand their capabilities
  2. Content Exploration: Use READ-ONLY operations to explore available data
  3. Question Generation: Create 10 complex, realistic questions
  4. Answer Verification: Solve each question yourself to verify answers
要创建有效的评估用例，请遵循评估指南中的流程：
  1. 工具检查：列出可用工具并了解其功能
  2. 内容探索：使用只读操作探索可用数据
  3. 问题生成：创建10个复杂、真实的问题
  4. 答案验证：自行解决每个问题以验证答案的正确性

4.3 Evaluation Requirements

4.3 评估要求

Ensure each question is:
  • Independent: Not dependent on other questions
  • Read-only: Only non-destructive operations required
  • Complex: Requiring multiple tool calls and deep exploration
  • Realistic: Based on real use cases humans would care about
  • Verifiable: Single, clear answer that can be verified by string comparison
  • Stable: Answer won't change over time
确保每个问题满足：
  • 独立性：不依赖其他问题
  • 只读性：仅需非破坏性操作
  • 复杂性：需要多次调用工具和深度探索
  • 真实性：基于人类实际关心的使用场景
  • 可验证性：答案唯一、清晰，可通过字符串比对验证
  • 稳定性：答案不会随时间变化

4.4 Output Format

4.4 输出格式

Create an XML file with this structure:
xml
<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>
创建如下结构的XML文件：
xml
<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

Reference Files

参考文件

📚 Documentation Library

📚 文档库

Load these resources as needed during development:
开发过程中可按需加载以下资源：

Core MCP Documentation (Load First)

核心MCP文档（优先加载）

  • MCP Protocol: Prefer 
    https://modelcontextprotocol.io/llms-full.txt
    for the full spec. Use the sitemap at 
    https://modelcontextprotocol.io/sitemap.xml
    for targeted pages.
  • 📋 MCP Best Practices - Universal MCP guidelines including:
    • Server and tool naming conventions
    • Response format guidelines (JSON vs Markdown)
    • Pagination best practices
    • Transport selection (streamable HTTP vs stdio)
    • Security and error handling standards
  • MCP协议：优先查看完整规范
    https://modelcontextprotocol.io/llms-full.txt
    。可通过站点地图
    https://modelcontextprotocol.io/sitemap.xml
    获取针对性页面。
  • 📋 MCP最佳实践 - 通用MCP指导原则，包括：
    • 服务器与工具命名规范
    • 响应格式指南（JSON vs Markdown）
    • 分页最佳实践
    • 传输方式选择（可流式HTTP vs stdio）
    • 安全与错误处理标准

SDK Documentation (Load During Phase 1/2)

SDK文档（阶段1/2加载）

  • Python SDK: Fetch from 
    https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • TypeScript SDK: Fetch from 
    https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
  • Python SDK：从
    https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
    获取
  • TypeScript SDK：从
    https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
    获取

Language-Specific Implementation Guides (Load During Phase 2)

语言专属实现指南（阶段2加载）

  • 🐍 Python Implementation Guide - Complete Python/FastMCP guide with:
    • Server initialization patterns
    • Pydantic model examples
    • Tool registration with 
      @mcp.tool
    • Complete working examples
    • Quality checklist
  • ⚡ TypeScript Implementation Guide - Complete TypeScript guide with:
    • Project structure
    • Zod schema patterns
    • Tool registration with 
      server.registerTool
    • Complete working examples
    • Quality checklist
  • 🐍 Python实现指南 - 完整的Python/FastMCP指南，包括：
    • 服务器初始化模式
    • Pydantic模型示例
    • 使用
      @mcp.tool
      注册工具
    • 完整的工作示例
    • 质量检查清单
  • ⚡ TypeScript实现指南 - 完整的TypeScript指南，包括：
    • 项目结构
    • Zod Schema模式
    • 使用
      server.registerTool
      注册工具
    • 完整的工作示例
    • 质量检查清单

Evaluation Guide (Load During Phase 4)

评估指南（阶段4加载）

  • ✅ Evaluation Guide - Complete evaluation creation guide with:
    • Question creation guidelines
    • Answer verification strategies
    • XML format specifications
    • Example questions and answers
    • Running an evaluation with the provided scripts
  • ✅ 评估指南 - 完整的评估用例创建指南，包括：
    • 问题创建准则
    • 答案验证策略
    • XML格式规范
    • 示例问题与答案
    • 使用提供的脚本运行评估