mcpField
B
build-mcp

build-mcp

github.com/neolabhq开发1.8k1.2k 次安装9 周前更新
代码仓库

关于 build-mcp

build-mcp 是用于规划、实现、审查和评估 MCP 服务的开发技能。它引导开发者研究 API、围绕 Agent 工作流设计工具，并进行语言适配实现与评估。

主要功能

  1. 01围绕 Agent 工作流规划工具
  2. 02指导 API 与协议研究
  3. 03提供 Python 和 TypeScript 实现指南
  4. 04涵盖审查、测试与构建检查
  5. 05创建真实的只读评估

适用场景

  1. 01为外部服务集成设计工具
  2. 02使用 Python 或 TypeScript 实现 MCP 服务
  3. 03审查服务代码和错误处理
  4. 04评估 Agent 能否回答真实问题

MCP 相关

该技能指导开发者构建 MCP 服务，为 LLM 提供与外部服务和 API 交互的工具。内容涵盖协议和 SDK 调研、实现与评估。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/neolabhq/context-engineering-kit --skill build-mcp

安装后在 Claude Code 中输入/build-mcp确认已加载。

详细介绍

MCP 服务开发指南

概述

使用此技能创建高质量的 MCP（Model Context Protocol）服务，让大模型能够有效地与外部服务交互。MCP 服务提供工具，让大模型能够访问外部服务和 API。MCP 服务的质量取决于它能否借助所提供的工具，帮助大模型完成现实世界中的任务。

流程

🚀 高层工作流

创建高质量的 MCP 服务主要分为四个阶段：

阶段 1：深入研究与规划
1.1 理解以 Agent 为中心的设计原则

在开始实现之前，请先了解如何为 AI Agent 设计工具，并查阅以下原则：

围绕工作流构建，而不只是封装 API 端点：

  • 不要只封装现有 API 端点，而要构建经过深思熟虑、影响力大的工作流工具
  • 合并相关操作（例如，schedule_event 同时检查可用时间并创建事件）
  • 重点打造能够完成完整任务的工具，而不只是调用单个 API
  • 考虑 Agent 实际需要完成哪些工作流

针对有限的上下文进行优化：

  • Agent 的上下文窗口有限，因此要让每个词元都发挥作用
  • 返回高价值信息，而非详尽的数据转储
  • 提供“简洁”与“详细”两种响应格式选项
  • 默认使用便于人类理解的标识符，而非技术代码（名称优先于 ID）
  • 将 Agent 的上下文预算视为稀缺资源

设计可执行的错误消息：

  • 错误消息应引导 Agent 正确使用工具
  • 提供具体的后续操作建议：“尝试使用 filter='active_only' 来减少结果”
  • 让错误消息能够帮助用户学习，而不只是诊断问题
  • 通过清晰的反馈，帮助 Agent 学会正确使用工具

遵循自然的任务划分方式：

  • 工具名称应反映人们思考任务的方式
  • 使用一致的前缀对相关工具分组，方便发现
  • 围绕自然的工作流设计工具，而不只是遵循 API 结构

采用评估驱动开发：

  • 尽早创建真实的评估场景
  • 根据 Agent 的反馈改进工具
  • 快速制作原型，并根据 Agent 的实际表现迭代
1.3 阅读 MCP 协议文档

获取最新的 MCP 协议文档：

使用 WebFetch 加载：https://modelcontextprotocol.io/llms-full.txt

这份综合文档包含完整的 MCP 规范和指南。

1.4 阅读框架文档

加载并阅读以下参考文件：

对于 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 个令牌）

错误处理策略：

  • 规划优雅的失败模式
  • 设计清晰、可操作、适合大模型且使用自然语言的错误消息，以提示后续操作
  • 考虑速率限制和超时场景
  • 处理身份验证和授权错误
第 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 正确注册工具
  • 使用带有 model_config 的 Pydantic v2 模型
  • 全程添加类型提示
  • 所有 I/O 操作均使用 Async/await
  • 正确组织导入语句
  • 使用模块级常量（CHARACTER_LIMIT、API_BASE_URL）

对于 Node/TypeScript：加载 ⚡ TypeScript 实现指南，并确保以下事项：

  • 正确使用 server.registerTool
  • 使用带有 .strict() 的 Zod 架构
  • 启用 TypeScript 严格模式
  • 不使用 any 类型，改用合适的类型
  • 显式声明 Promise 返回类型
  • 配置构建流程（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 使用质量检查清单

为验证实现质量，请从相应的语言指南中加载检查清单：

第 4 阶段：创建评估

实现 MCP 服务后，请创建全面的评估，以测试其效果。

加载 ✅ 评估指南，了解完整的评估指南。

4.1 了解评估目的

评估用于测试大模型能否有效使用 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>

</evaluation>

参考文件

📚 文档库

开发过程中根据需要加载以下资源：

MCP 核心文档（首先加载）
  • MCP 协议：从 https://modelcontextprotocol.io/llms-full.txt 获取——完整的 MCP 规范
  • 📋 MCP 最佳实践 - 通用 MCP 指南，包括：
    • 服务和工具的命名约定
    • 响应格式指南（JSON 与 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 格式规范
    • 问题和答案示例
    • 使用提供的脚本运行评估

评论

支持 Markdown