id: “4d2c05df-e8ff-5c17-9c45-4a93c1c1d07d” name: mcp-builder description: 创建高质量 MCP（模型上下文协议）服务器的指南，使 LLMs 能够通过精心设计的工具与外部服务交互。适用于构建 MCP 服务器以集成外部 API 或服务，无论是使用 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。 license: 完整条款见 LICENSE.txt

MCP 服务器开发指南

概述

要创建高质量的 MCP（模型上下文协议）服务器，使 LLMs 能够有效地与外部服务交互，请使用此技能。MCP 服务器提供工具，允许 LLMs 访问外部服务和 API。MCP 服务器的质量取决于其如何使 LLMs 使用提供的工具完成现实世界任务。

流程

🚀 高层级工作流

创建高质量的 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 理解评估目的

评估测试 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/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 格式规范
- 示例问题和答案
- 使用提供的脚本运行评估