MCP 服务器开发指南

概述

要创建使 LLMs 能够有效与外部服务交互的高质量 MCP（Model Context Protocol）服务器，请使用此技能。MCP 服务器提供允许 LLMs 访问外部服务和 API 的工具。MCP 服务器的质量取决于它使 LLMs 能够使用提供的工具完成真实世界任务的程度。

---

流程

高级工作流程

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

阶段 1：深度研究和规划

1.1 了解以代理为中心的设计原则

在深入实现之前，了解如何为 AI 代理设计工具：

为工作流而非仅为 API 端点构建：

• 不要简单包装现有 API 端点——构建深思熟虑、高影响力的工作流工具
• 整合相关操作（如

  schedule_event

  同时检查可用性和创建事件）
• 专注于实现完整任务的工具，而非仅单个 API 调用
• 考虑代理实际需要完成的工作流

针对有限上下文优化：

• 代理有受限的上下文窗口——让每个 token 都有价值
• 返回高信号信息，而非详尽的数据转储
• 提供"简洁"vs"详细"响应格式选项
• 默认为人类可读的标识符而非技术代码（名称优于 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 个 token）

错误处理策略：

• 规划优雅的故障模式
• 设计清晰、可操作、对 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 的 async/await 模式
• 实现适当的错误处理
• 支持多种响应格式（JSON 和 Markdown）
• 尊重分页参数
• 检查字符限制并适当截断

添加工具注解：

• readOnlyHint

  ：true（对于只读操作）

• destructiveHint

  ：false（对于非破坏性操作）

• idempotentHint

  ：true（如果重复调用效果相同）

• openWorldHint

  ：true（如果与外部系统交互）

2.4 遵循语言特定最佳实践

此时加载适当的语言指南：

对于 Python：加载 🐍 Python 实现指南 并确保：

• 使用带有适当工具注册的 MCP Python SDK
• Pydantic v2 模型与

  model_config

• 贯穿始终的类型提示
• 所有 I/O 操作的 async/await
• 正确的导入组织
• 模块级常量（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 个评估问题

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

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

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