名称: mcp-builder 描述: 创建高质量MCP（模型上下文协议）服务器的指南，使LLM能够通过设计良好的工具与外部服务交互。在构建MCP服务器以集成外部API或服务时使用，无论是Python（FastMCP）还是Node/TypeScript（MCP SDK）。 许可证: 完整条款见LICENSE.txt
MCP服务器开发指南
概述
要创建高质量的MCP（模型上下文协议）服务器，使LLM能够有效地与外部服务交互，请使用此技能。MCP服务器提供工具，允许LLM访问外部服务和API。MCP服务器的质量取决于其如何使LLM使用提供的工具完成现实世界任务。
流程
🚀 高级工作流
创建高质量的MCP服务器涉及四个主要阶段：
阶段1：深入研究和规划
1.1 理解以代理为中心的设计原则
在开始实施之前，通过回顾以下原则了解如何为AI代理设计工具：
为工作流构建，而不仅仅是API端点：
- 不要简单地包装现有API端点 - 构建深思熟虑、高影响力的工作流工具
- 整合相关操作（例如，
schedule_event同时检查可用性并创建事件） - 专注于使能完整任务的工具，而不仅仅是单个API调用
- 考虑代理实际需要完成的工作流
为有限上下文优化：
- 代理有受限的上下文窗口 - 让每个标记都计数
- 返回高信号信息，而不是详尽的数据转储
- 提供“简洁”与“详细”的响应格式选项
- 默认使用人类可读的标识符而非技术代码（名称而非ID）
- 将代理的上下文预算视为稀缺资源
设计可操作的错误消息：
- 错误消息应指导代理朝向正确的使用模式
- 建议具体下一步操作：“尝试使用filter='active_only’来减少结果”
- 使错误具有教育性，而不仅仅是诊断性
- 通过清晰的反馈帮助代理学习正确的工具使用
遵循自然任务细分：
- 工具名称应反映人类对任务的思考方式
- 使用一致的前缀分组相关工具以提高可发现性
- 围绕自然工作流而非仅是API结构设计工具
使用评估驱动的开发：
- 尽早创建现实的评估场景
- 让代理反馈驱动工具改进
- 快速原型制作并根据实际代理性能迭代
1.3 学习MCP协议文档
获取最新的MCP协议文档：
使用WebFetch加载：https://modelcontextprotocol.io/llms-full.txt
此全面文档包含完整的MCP规范和指南。
1.4 学习框架文档
加载并阅读以下参考文件：
- MCP最佳实践：📋 查看最佳实践 - 所有MCP服务器的核心指南
对于Python实现，也加载：
- Python SDK文档：使用WebFetch加载
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - 🐍 Python实现指南 - Python特定的最佳实践和示例
对于Node/TypeScript实现，也加载：
- TypeScript SDK文档：使用WebFetch加载
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md - ⚡ TypeScript实现指南 - Node/TypeScript特定的最佳实践和示例
1.5 详尽学习API文档
要集成服务，阅读所有可用的API文档：
- 官方API参考文档
- 认证和授权要求
- 速率限制和分页模式
- 错误响应和状态码
- 可用端点及其参数
- 数据模型和模式
要收集全面信息，根据需要使用网络搜索和WebFetch工具。
1.6 创建全面的实施计划
基于研究，创建一个详细的计划，包括：
工具选择：
- 列出要实施的最有价值的端点/操作
- 优先处理使能最常见和最重要用例的工具
- 考虑哪些工具共同工作以启用复杂工作流
共享实用程序和助手：
- 识别常见的API请求模式
- 计划分页助手
- 设计过滤和格式化实用程序
- 计划错误处理策略
输入/输出设计：
- 定义输入验证模型（Python用Pydantic，TypeScript用Zod）
- 设计一致的响应格式（例如，JSON或Markdown），以及可配置的详细级别（例如，详细或简洁）
- 规划大规模使用（数千用户/资源）
- 实施字符限制和截断策略（例如，25,000个标记）
错误处理策略：
- 计划优雅的失败模式
- 设计清晰、可操作、LLM友好、自然语言的错误消息，提示进一步操作
- 考虑速率限制和超时场景
- 处理认证和授权错误
阶段2：实施
现在你有了全面的计划，开始实施，遵循语言特定的最佳实践。
2.1 设置项目结构
对于Python：
- 创建单个
.py文件，如果复杂则组织成模块（见🐍 Python指南） - 使用MCP Python SDK进行工具注册
- 为输入验证定义Pydantic模型
对于Node/TypeScript：
- 创建适当的项目结构（见⚡ TypeScript指南）
- 设置
package.json和tsconfig.json - 使用MCP TypeScript SDK
- 为输入验证定义Zod模式
2.2 首先实施核心基础设施
开始实施，在实现工具之前创建共享实用程序：
- API请求助手函数
- 错误处理实用程序
- 响应格式化函数（JSON和Markdown）
- 分页助手
- 认证/令牌管理
2.3 系统化实施工具
对于计划中的每个工具：
定义输入模式：
- 使用Pydantic（Python）或Zod（TypeScript）进行验证
- 包括适当的约束（最小/最大长度、正则模式、最小/最大值、范围）
- 提供清晰、描述性的字段描述
- 在字段描述中包含多样化的示例
编写全面的文档字符串/描述：
- 一行摘要说明工具做什么
- 详细解释目的和功能
- 显式参数类型带示例
- 完整返回类型模式
- 使用示例（何时使用、何时不使用）
- 错误处理文档，概述给定特定错误时如何继续
实施工具逻辑：
- 使用共享实用程序避免代码重复
- 对所有I/O遵循异步/等待模式
- 实施适当的错误处理
- 支持多种响应格式（JSON和Markdown）
- 尊重分页参数
- 检查字符限制并适当截断
添加工具注解：
readOnlyHint：true（对于只读操作）destructiveHint：false（对于非破坏性操作）idempotentHint：true（如果重复调用有相同效果）openWorldHint：true（如果与外部系统交互）
2.4 遵循语言特定最佳实践
此时，加载适当的语言指南：
对于Python：加载🐍 Python实现指南并确保以下：
- 使用MCP Python SDK进行正确的工具注册
- Pydantic v2模型带
model_config - 整个使用类型提示
- 所有I/O操作使用异步/等待
- 正确的导入组织
- 模块级常量（CHARACTER_LIMIT，API_BASE_URL）
对于Node/TypeScript：加载⚡ TypeScript实现指南并确保以下：
- 正确使用
server.registerTool - Zod模式带
.strict() - 启用TypeScript严格模式
- 无
any类型 - 使用适当类型 - 显式Promise<T>返回类型
- 配置构建过程（
npm run build）
阶段3：审查和优化
初步实施后：
3.1 代码质量审查
为确保质量，审查代码的：
- DRY原则：工具之间没有重复代码
- 可组合性：共享逻辑提取到函数中
- 一致性：类似操作返回类似格式
- 错误处理：所有外部调用都有错误处理
- 类型安全：完全类型覆盖（Python类型提示，TypeScript类型）
- 文档：每个工具都有全面的文档字符串/描述
3.2 测试和构建
重要：MCP服务器是长期运行的进程，通过stdio/stdin或sse/http等待请求。直接在主进程中运行它们（例如，python server.py或node dist/index.js）将导致进程无限期挂起。
安全测试服务器的方法：
- 使用评估工具链（见阶段4） - 推荐方法
- 在tmux中运行服务器以保持在主进程外
- 测试时使用超时：
timeout 5s python server.py
对于Python：
- 验证Python语法：
python -m py_compile your_server.py - 通过查看文件检查导入是否正确工作
- 手动测试：在tmux中运行服务器，然后在主进程中使用评估工具链测试
- 或直接使用评估工具链（它为stdio传输管理服务器）
对于Node/TypeScript：
- 运行
npm run build并确保完成无错误 - 验证dist/index.js已创建
- 手动测试：在tmux中运行服务器，然后在主进程中使用评估工具链测试
- 或直接使用评估工具链（它为stdio传输管理服务器）
3.3 使用质量检查清单
要验证实施质量，从语言特定指南加载适当的检查清单：
- Python：见🐍 Python指南中的“质量检查清单”
- Node/TypeScript：见⚡ TypeScript指南中的“质量检查清单”
阶段4：创建评估
实施MCP服务器后，创建全面评估以测试其有效性。
加载✅ 评估指南获取完整的评估指南。
4.1 理解评估目的
评估测试LLM是否能有效使用你的MCP服务器回答现实、复杂的问题。
4.2 创建10个评估问题
要创建有效评估，遵循评估指南概述的过程：
- 工具检查：列出可用工具并理解其能力
- 内容探索：使用只读操作探索可用数据
- 问题生成：创建10个复杂、现实的问题
- 答案验证：自己解决每个问题以验证答案
4.3 评估要求
每个问题必须：
- 独立：不依赖于其他问题
- 只读：仅需要非破坏性操作
- 复杂：需要多次工具调用和深入探索
- 现实：基于人类关心的真实用例
- 可验证：单一、清晰的答案可通过字符串比较验证
- 稳定：答案不会随时间变化
4.4 输出格式
创建具有以下结构的XML文件：
<evaluation>
<qa_pair>
<question>找到关于具有动物代号名称的AI模型发布的讨论。一个模型需要一个特定安全标识，格式为ASL-X。对于以斑点野生猫命名的模型，确定数字X是多少？</question>
<answer>3</answer>
</qa_pair>
<!-- 更多qa_pairs... -->
</evaluation>
参考文件
📚 文档库
开发过程中根据需要加载这些资源：
核心MCP文档（首先加载）
- MCP协议：从
https://modelcontextprotocol.io/llms-full.txt获取 - 完整的MCP规范 - 📋 MCP最佳实践 - 通用MCP指南，包括：
- 服务器和工具命名约定
- 响应格式指南（JSON vs Markdown）
- 分页最佳实践
- 字符限制和截断策略
- 工具开发指南
- 安全和错误处理标准
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格式规范
- 示例问题和答案
- 使用提供脚本运行评估