mcp-builder

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（模型上下文协议）服务器，让LLM可以通过设计完善的工具与外部服务交互。MCP服务器的质量以其支持LLM完成真实世界任务的效果来衡量。

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.

API覆盖度 vs 工作流工具： 在全面的API端点覆盖和专用工作流工具之间取得平衡。工作流工具对特定任务来说更易用，而全面的覆盖则能让Agent灵活组合操作。性能因客户端而异：部分客户端受益于结合基础工具的代码执行能力，另一部分则更适合使用更高层级的工作流。如果无法确定优先级，优先实现全面的API覆盖。

工具命名与可发现性： 清晰、描述性的工具名称可以帮助Agent快速找到合适的工具。使用统一的前缀（例如

github_create_issue

、

github_list_repos

）和面向动作的命名规则。

上下文管理： 简洁的工具描述以及对结果进行过滤/分页的能力能为Agent提供帮助。要设计返回聚焦、相关数据的工具。部分客户端支持代码执行，可帮助Agent高效过滤和处理数据。

可落地的错误信息： 错误信息应通过具体建议和后续步骤引导Agent找到解决方案。

1.2 Study MCP Protocol Documentation

1.2 学习MCP协议文档

Navigate the MCP specification:

Start with the sitemap to find relevant pages:

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/sitemap.xml

然后获取带

.md

后缀的特定页面得到Markdown格式内容（例如

https://modelcontextprotocol.io/specification/draft.md

）。

需要重点查看的页面：

规范概述与架构
传输机制（可流式HTTP、stdio）
工具、资源与Prompt定义

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代码，这得益于其广泛的应用、静态类型和优秀的lint工具）
传输协议： 远程服务器使用可流式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

代码实现：

I/O操作使用async/await
完善的错误处理，返回可落地的错误信息
适用场景下支持分页
使用新版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 构建与测试

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.

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.

通过评估测试LLM是否能有效使用你开发的MCP服务器来回答真实的复杂问题。

4.2 Create 10 Evaluation Questions

4.2 创建10个评估问题

To create effective evaluations, follow the process outlined in the evaluation guide:

Tool Inspection: List available tools and understand their capabilities
Content Exploration: Use READ-ONLY operations to explore available data
Question Generation: Create 10 complex, realistic questions
Answer Verification: Solve each question yourself to verify answers

按照评估指南中列出的流程创建有效的评估用例：

工具梳理: 列出所有可用工具，理解其能力边界
内容探索: 使用只读操作探索可用数据
问题生成: 创建10个复杂、贴近真实场景的问题
答案验证: 自行解答每个问题，验证答案准确性

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: Start with sitemap at
```
https://modelcontextprotocol.io/sitemap.xml
```
, then fetch specific pages with
```
.md
```
suffix
📋 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/sitemap.xml
```
，然后获取带
```
.md
```
后缀的特定页面
📋 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格式规范
- 问题与答案示例
- 使用提供的脚本运行评估