MCP 服务器开发指南

创建 MCP 服务器，使 LLM 通过精心设计的工具与外部服务交互。MCP 服务器质量以 LLM 完成真实世界任务的能力衡量。

高级工作流程

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

阶段 1：深度研究与规划

1.1 理解现代 MCP 设计：平衡全面 API 端点覆盖与专业工作流工具。工作流工具对特定任务更便利，而全面覆盖给代理组合操作的灵活性。性能因客户端而异—某些客户端受益于组合基本工具的代码执行，而其他客户端更适合高级工作流。不确定时，优先全面 API 覆盖。
工具命名与可发现性：清晰、描述性工具名帮助代理快速找到正确工具。使用一致前缀（如 github_create_issue、github_list_repos）与面向动作的命名。
上下文管理：代理受益于简洁工具描述与过滤/分页结果能力。设计返回聚焦、相关数据的工具。某些客户端支持代码执行，可帮助代理高效过滤与处理数据。
可操作错误消息：错误消息应通过具体建议与下一步指导代理走向解决方案。

1.2 研究 MCP 协议文档：从 sitemap 开始：https://modelcontextprotocol.io/sitemap.xml，然后获取带 .md 后缀的特定页面（如 https://modelcontextprotocol.io/specification/draft.md）。关键页面：规范概览与架构、传输机制（可流式 HTTP、stdio）、工具、资源与提示定义。

1.3 研究框架文档：推荐栈：TypeScript（高质量 SDK 支持与许多执行环境良好兼容性，AI 模型擅长生成 TypeScript 代码，受益于广泛使用、静态类型与良好 linting 工具）、传输：可流式 HTTP 用于远程服务器（使用无状态 JSON），stdio 用于本地服务器。
加载框架文档：MCP 最佳实践、TypeScript SDK（从 GitHub 获取 README）、Python SDK（从 GitHub 获取 README）。