name: mcp-builder description: 创建高质量MCP（模型上下文协议）服务器的指南，使LLMs能够通过设计良好的工具与外部服务交互。在构建MCP服务器以集成外部API或服务时使用，无论是Python（FastMCP）还是Node/TypeScript（MCP SDK）。 license: 完整条款见LICENSE.txt

MCP服务器开发指南

概述

创建MCP（模型上下文协议）服务器，使LLMs能够通过设计良好的工具与外部服务交互。MCP服务器的质量取决于它如何有效地使LLMs完成现实世界任务。

流程

🚀 高级工作流

创建高质量的MCP服务器涉及四个主要阶段：

阶段1：深度研究与规划

1.1 理解现代MCP设计

API覆盖与工作流工具： 在全面的API端点覆盖和专业化工作流工具之间取得平衡。工作流工具对于特定任务可能更方便，而全面覆盖则给代理灵活性以组合操作。性能因客户端而异—有些客户端受益于组合基本工具的代码执行，而其他客户端则更适用于更高级别的工作流。不确定时，优先选择全面的API覆盖。

工具命名和可发现性： 清晰、描述性的工具名称帮助代理快速找到正确的工具。使用一致的前缀（例如github_create_issue、github_list_repos）和面向操作的命名。

上下文管理： 代理受益于简洁的工具描述和过滤/分页结果的能力。设计返回集中、相关数据的工具。某些客户端支持代码执行，这可以帮助代理高效过滤和处理数据。

可操作的错误消息： 错误消息应通过具体建议和后续步骤指导代理解决问题。

1.2 学习MCP协议文档

浏览MCP规范：

从站点地图开始寻找相关页面：https://modelcontextprotocol.io/sitemap.xml

然后获取带有.md后缀的特定页面以获取Markdown格式（例如https://modelcontextprotocol.io/specification/draft.md）。

关键页面回顾：

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

1.3 学习框架文档

推荐技术栈：

语言：TypeScript（高质量的SDK支持和良好的兼容性，例如在MCPB中。此外，AI模型擅长生成TypeScript代码，得益于其广泛使用、静态类型和良好的linting工具）
传输：用于远程服务器的可流式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 规划您的实现

理解API： 查看服务的API文档以识别关键端点、认证要求和数据模型。根据需要使用网络搜索和WebFetch。

工具选择： 优先选择全面的API覆盖。列出要实现的端点，从最常见的操作开始。

阶段2：实现

2.1 设置项目结构

参见语言特定指南进行项目设置：

⚡ TypeScript指南 - 项目结构、package.json、tsconfig.json
🐍 Python指南 - 模块组织、依赖关系

2.2 实现核心基础设施

创建共享工具：

带认证的API客户端
错误处理助手
响应格式化（JSON/Markdown）
分页支持

2.3 实现工具

对于每个工具：

输入模式：

使用Zod（TypeScript）或Pydantic（Python）
包括约束和清晰的描述
在字段描述中添加示例

输出模式：

尽可能定义outputSchema以获取结构化数据
在工具响应中使用structuredContent（TypeScript SDK功能）
帮助客户端理解和处理工具输出

工具描述：

功能的简洁总结
参数描述
返回类型模式

实现：

I/O操作使用Async/await
具有可操作消息的正确错误处理
适用时支持分页
使用现代SDK时返回文本内容和结构化数据

注释：

readOnlyHint：真/假
destructiveHint：真/假
idempotentHint：真/假
openWorldHint：真/假

阶段3：审查和测试

3.1 代码质量

审查：

无重复代码（DRY原则）
一致的错误处理
完整的类型覆盖
清晰的工具描述

3.2 构建和测试

TypeScript：

运行npm run build以验证编译
使用MCP Inspector测试：npx @modelcontextprotocol/inspector

Python：

验证语法：python -m py_compile your_server.py
使用MCP Inspector测试

参见语言特定指南获取详细的测试方法和质量检查清单。

阶段4：创建评估

实现MCP服务器后，创建全面的评估以测试其有效性。

加载✅ 评估指南获取完整的评估指南。

4.1 理解评估目的

使用评估测试LLMs是否能有效使用您的MCP服务器回答现实、复杂的问题。

4.2 创建10个评估问题

创建有效的评估，遵循评估指南中概述的流程：

工具检查：列出可用工具并理解其能力
内容探索：使用只读操作探索可用数据
问题生成：创建10个复杂、现实的问题
答案验证：自己解决每个问题以验证答案

4.3 评估要求

确保每个问题：

独立：不依赖于其他问题
只读：仅需要非破坏性操作
复杂：需要多次工具调用和深度探索
现实：基于人类会关心的真实用例
可验证：单一、清晰的答案，可通过字符串比较验证
稳定：答案不会随时间改变

4.4 输出格式

创建具有此结构的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>

参考文件

📚 文档库

在开发过程中根据需要加载这些资源：

核心MCP文档（首先加载）

MCP协议：从站点地图开始：https://modelcontextprotocol.io/sitemap.xml，然后获取带有.md后缀的特定页面
📋 MCP最佳实践 - 通用MCP指南，包括：
- 服务器和工具命名约定
- 响应格式指南（JSON vs Markdown）
- 分页最佳实践
- 传输选择（可流式HTTP vs stdio）
- 安全和错误处理标准

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

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

语言特定实现指南（在阶段2期间加载）

🐍 Python实现指南 - 完整的Python/FastMCP指南，包括：
- 服务器初始化模式
- Pydantic模型示例
- 使用@mcp.tool注册工具
- 完整工作示例
- 质量检查清单
⚡ TypeScript实现指南 - 完整的TypeScript指南，包括：
- 项目结构
- Zod模式模式
- 使用server.registerTool注册工具
- 完整工作示例
- 质量检查清单

评估指南（在阶段4期间加载）

✅ 评估指南 - 完整的评估创建指南，包括：
- 问题创建指南
- 答案验证策略
- XML格式规范
- 示例问题和答案
- 使用提供的脚本运行评估