名称: mcp-builder 描述: 创建高质量的 MCP 服务器，使 LLM 能有效与外部服务交互。当为 API 或服务在 Python（FastMCP）或 Node/TypeScript（MCP SDK）中构建 MCP 集成时使用。许可证: 完整条款见 LICENSE.txt 渐进披露: 入口点: 摘要: “通过研究驱动设计、周到实施和基于评估的迭代来构建代理友好的 MCP 服务器” 何时使用: “当通过 MCP 协议集成外部 API/服务时。优先考虑代理工作流而非 API 包装，优化上下文效率，设计可操作的错误。” 快速开始: “1. 研究协议和 API 文档 2. 规划以代理为中心的工具 3. 带验证实施 4. 创建评估 5. 基于代理反馈迭代” 参考文献: - design_principles.md - workflow.md - mcp_best_practices.md - python_mcp_server.md - node_mcp_server.md - evaluation.md

MCP 服务器开发指南

概述

构建高质量的 MCP（模型上下文协议）服务器，使 LLM 能通过设计良好的工具完成现实世界任务。质量不是由 API 覆盖率衡量，而是由代理使用您的工具完成现实工作流的有效性衡量。

核心见解： MCP 服务器为 AI 代理暴露工具，而非人类用户。为代理约束设计（有限上下文、无视觉 UI、工作流导向），而非人类便利。

何时使用此技能

激活时：

为外部 API 集成构建 MCP 服务器
向现有 MCP 服务器添加工具
改进 MCP 服务器工具设计以提升代理可用性
创建评估以测试 MCP 服务器有效性
调试代理在使用您的 MCP 工具时遇到的问题

语言支持：

Python: FastMCP 框架（推荐用于快速开发）
Node/TypeScript: MCP SDK（推荐用于生产服务）

铁律

为代理设计，而非人类

每个工具必须优化：
- 上下文效率（代理有限制令牌）
- 工作流完成（不仅仅是 API 调用）
- 可操作的错误（引导代理成功）
- 自然任务细分（代理的思考方式）

如果您的工具只是薄薄的 API 包装，那么您就违反了铁律。

核心原则

以代理为中心的设计优先：在编码前研究设计原则。工具应启用工作流，而非镜像 API。
研究驱动的规划：在编写代码前加载 MCP 文档、SDK 文档和详尽的 API 文档。
基于评估的迭代：早期创建现实评估。让代理反馈驱动改进。
上下文优化：每个响应令牌都很重要。默认简洁，需要时提供详细。
可操作的错误：错误信息应教导代理正确使用模式。

快速开始

阶段 1: 研究和规划（40% 的精力）

学习设计原则：加载 design_principles.md 以理解以代理为中心的设计
加载协议文档：获取 https://modelcontextprotocol.io/llms-full.txt 以获取 MCP 规范
学习 SDK 文档：从 GitHub 加载 Python 或 TypeScript SDK 文档
详尽学习 API：阅读所有 API 文档、端点、认证、速率限制
创建实施计划：定义工具、共享工具、分页策略、错误处理

见 workflow.md 了解完整阶段 1 步骤。

阶段 2: 实施（30% 的精力）

设置项目：创建结构，遵循语言特定指南
构建共享工具：API 助手、错误处理器、格式化器在工具之前
实施工具：使用 Pydantic（Python）或 Zod（TypeScript）进行验证
遵循最佳实践：加载语言特定指南以了解模式

见 workflow.md 了解完整阶段 2 步骤和语言指南。

阶段 3: 审查和精炼（15% 的精力）

代码质量审查：检查 DRY、可组合性、一致性、类型安全
测试构建：验证语法、导入、构建过程
质量检查表：使用语言特定检查表

见 workflow.md 了解完整阶段 3 步骤。

阶段 4: 创建评估（15% 的精力）

理解目的：评估测试代理是否能使用您的工具回答现实问题
创建 10 个问题：复杂、只读、独立、可验证的问题
验证答案：自行解决以确保稳定性和正确性
运行评估：使用提供的脚本测试代理有效性

见 evaluation.md 了解完整评估指南。

关键提醒

研究优先：编码前花 40% 时间研究
以代理为中心：为 AI 工作流设计，而非 API 完整性
上下文高效：每个令牌都很重要 - 默认简洁，提供详细
可操作的错误：引导代理正确使用
共享工具：提取通用代码 - 避免重复
评估驱动：早期创建评估，基于反馈迭代
MCP 服务器阻塞：永远不要直接运行服务器 - 使用评估框架或 tmux

红旗 - 停止

如果您发现自己：

“只是直接包装这些 API 端点”
“返回所有可用数据字段”
“错误信息只说明失败了什么”（而不是如何修复）
没有阅读设计原则就开始实施
编码前没有加载 MCP 协议文档
创建工具而不知道代理用例
跳过评估创建
直接运行 python server.py（将永远挂起）

所有这些意味着：停止。返回到设计原则和工作流。

与其他技能的集成

系统调试：系统调试 MCP 服务器问题
测试驱动开发：实施前创建失败测试
完成前验证：验证构建成功后再声称完成
深度防御：在多个层级添加输入验证

实际影响

从 MCP 服务器开发经验：

设计良好的服务器：代理 80-90% 任务完成率
API 包装方法：30-40% 任务完成率
上下文优化响应：在相同令牌预算下信息量增加 3 倍
可操作的错误：代理重试尝试减少 60%
评估驱动迭代：代理成功率提高 2-3 倍

记住： MCP 服务器的质量不是由包装 API 的全面性衡量，而是由它使 LLM 能完成现实任务的效果衡量。

MCP服务器构建技能Skill mcp-builder