关于
创建 MCP（模型上下文协议）服务器，使 LLM 能通过精心设计的工具与外部服务交互。MCP 服务器的质量取决于它帮助 LLM 完成实际任务的能力。
name: mcp-builder description: "创建 MCP（模型上下文协议）服务器，使 LLM 能够通过精心设计的工具与外部服务交互。MCP 服务器的质量取决于它能多好地帮助 LLM 完成真实世界的任务。" risk: unknown source: community date_added: "2026-02-27"
MCP 服务器开发指南
概述
创建 MCP（模型上下文协议）服务器，使 LLM 能够通过精心设计的工具与外部服务交互。MCP 服务器的质量取决于它能多好地帮助 LLM 完成真实世界的任务。
流程
高级工作流
创建高质量 MCP 服务器涉及四个主要阶段：
阶段 1：深度研究和规划
1.1 理解现代 MCP 设计
API 覆盖 vs 工作流工具： 在全面的 API 端点覆盖和专业工作流工具之间取得平衡。工作流工具对特定任务更方便，而全面覆盖给代理灵活性来组合操作。性能因客户端而异 — 某些客户端受益于组合基本工具的代码执行，而其他客户端使用更高级别的工作流效果更好。不确定时，优先考虑全面的 API 覆盖。
工具命名和可发现性：
清晰、描述性的工具名称帮助代理快速找到正确的工具。使用一致的前缀（如 github_create_issue、github_list_repos）和面向操作的命名。
上下文管理： 代理受益于简洁的工具描述和过滤/分页结果的能力。设计返回聚焦、相关数据的工具。某些客户端支持代码执行，可帮助代理高效过滤和处理数据。
可操作的错误消息： 错误消息应通过具体建议和下一步引导代理走向解决方案。
1.2 学习 MCP 协议文档
浏览 MCP 规范：
从站点地图开始查找相关页面：https://modelcontextprotocol.io/sitemap.xml
然后使用 .md 后缀获取特定页面的 markdown 格式（如 https://modelcontextprotocol.io/specification/draft.md）。
需要审查的关键页面：
- 规范概述和架构
- 传输机制（可流式 HTTP、stdio）
- 工具、资源和提示定义
1.3 学习框架文档
推荐技术栈：
- 语言：TypeScript（高质量 SDK 支持，在许多执行环境中兼容性好。AI 模型擅长生成 TypeScript 代码，受益于其广泛使用、静态类型和良好的 lint 工具）
- 传输：远程服务器使用可流式 HTTP，使用无状态 JSON（更易扩展和维护）。本地服务器使用 stdio。
1.4 规划实现
理解 API： 审查服务的 API 文档以识别关键端点、认证要求和数据模型。根据需要使用 Web 搜索和 WebFetch。
工具选择： 优先考虑全面的 API 覆盖。列出要实现的端点，从最常见的操作开始。
阶段 2：实现
2.1 设置项目结构
参见语言特定指南了解项目设置。
2.2 实现工具
每个工具应该：
- 有清晰的名称和描述
- 定义输入模式（使用 Zod 或等效工具）
- 处理错误并返回有用的消息
- 返回结构化的、聚焦的数据
2.3 认证
- 支持环境变量配置
- 实现 OAuth 流程（如适用）
- 安全处理令牌刷新
阶段 3：测试
- 使用 MCP Inspector 进行交互式测试
- 验证所有工具的输入验证
- 测试错误场景和边缘情况
- 验证认证流程
阶段 4：文档和部署
- 编写清晰的 README，包含设置说明
- 记录所有工具及其参数
- 提供使用示例
- 配置部署（Docker、npm 发布等）
最佳实践
- 工具粒度：每个工具做一件事并做好
- 错误处理：返回有帮助的错误消息，而非通用失败
- 分页：大型列表支持分页
- 速率限制：尊重 API 速率限制并优雅处理
- 缓存：适当缓存不常变化的数据
- 安全：永不在响应中暴露凭证