名称: mcp-builder 描述: 创建高质量MCP（模型上下文协议）服务器的指南，使LLM能够通过精心设计的工具与外部服务交互。在构建MCP服务器以集成外部API或服务时使用，无论是Python（FastMCP）还是Node/TypeScript（MCP SDK）。许可证: 完整条款见LICENSE.txt 复杂度: 中级学习时间: 1小时先决条件:

后端实现模式标签:
mcp
模型上下文协议
llm工具
api集成
python
typescript 输入:
api文档
服务需求输出:
mcp服务器代码
工具定义副作用:
创建文件
运行命令触发:
用户询问mcp
用户询问模型上下文协议
上下文:mcp服务器补充:
api设计模式层级: 核心

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和适当的工具注册
带有model_config的Pydantic v2模型
整个过程中的类型提示
所有I/O操作的异步/等待
正确的导入组织
模块级常量（CHARACTER_LIMIT, API_BASE_URL）

对于Node/TypeScript：加载⚡ TypeScript实现指南并确保以下内容：

正确使用server.registerTool
带有.strict()的Zod模式
启用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格式规范
- 示例问题和答案
- 使用提供的脚本运行评估

MCP服务器开发技能 mcp-builder