MCP 服务器开发指南

概述

使用本技能创建高质量的 MCP（模型上下文协议）服务器，使 LLM 能够有效地与外部服务交互。MCP 服务器提供工具，允许 LLM 访问外部服务和 API。MCP 服务器的质量取决于它能多好地使 LLM 使用提供的工具完成实际任务。

---

流程

高级工作流

创建高质量 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 加载 Python SDK README
• Python 实现指南——Python 特定的最佳实践和示例

Node/TypeScript 实现还需加载：

• TypeScript SDK 文档：使用 WebFetch 加载 TypeScript SDK README
• TypeScript 实现指南——Node/TypeScript 特定的最佳实践和示例

1.5 详尽学习 API 文档

要集成服务，通读所有可用的 API 文档：

• 官方 API 参考文档
• 认证和授权要求
• 限流和分页模式
• 错误响应和状态码
• 可用端点及其参数
• 数据模型和 Schema

1.6 创建全面的实施计划

基于研究，创建详细计划，包括：

工具选择：

• 列出最有价值的端点/操作
• 优先考虑能实现最常见和最重要用例的工具
• 考虑哪些工具协同工作以实现复杂工作流

共享工具和辅助函数：

• 识别常见的 API 请求模式
• 规划分页辅助函数
• 设计过滤和格式化工具
• 规划错误处理策略

输入/输出设计：

• 定义输入验证模型（Python 用 Pydantic，TypeScript 用 Zod）
• 设计一致的响应格式（如 JSON 或 Markdown），以及可配置的详细级别
• 为大规模使用做规划（数千用户/资源）
• 实现字符限制和截断策略（如 25,000 Token）

错误处理策略：

• 规划优雅的失败模式
• 设计清晰、可操作、LLM 友好的自然语言错误消息
• 考虑限流和超时场景
• 处理认证和授权错误

---

阶段 2：实现

现在你有了全面的计划，开始按照语言特定的最佳实践进行实现。

2.1 设置项目结构

按照所选语言的标准项目结构设置项目。