mcp-builder

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会将旧版 Claude /skill-name 引用改写为此格式。
• 任务跟踪要求：在执行任何工作流或技能步骤之前，先为所有步骤创建/更新任务跟踪，并随进度变化保持同步。
• 用户问题提示表示要在 Codex 中直接询问用户。
• 忽略出现的 Claude 专属模式切换指令。
• 严格执行约定：用户明确调用某项技能时，必须按书面规定执行该技能协议。
• 子 Agent 授权：当用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权在该任务中使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，明确执行每个列出的子技能步骤，并逐步报告证据。
• 如果所需步骤/工具无法在此环境中运行，请停止并询问用户，然后再进行调整。

Codex 项目参考资料加载（无 Hooks）

Codex 不会接收基于 Claude Hooks 的文档注入。 进行编码、规划、调试、测试或审查时，请按此路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块和工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的防护准则和反模式）

视情况阅读文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规范/测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件选择的领域文档

不要不加甄别地阅读所有文档。请从 docs-index-reference.md 开始，然后仅打开与任务相关的文件。

快速摘要

目标： 创建高质量的 MCP（Model Context Protocol）服务，使大模型能够通过精心设计的工具与外部服务交互。

工作流：

1. 深入研究 — 全面研究以 Agent 为中心的设计原则、MCP 协议、SDK 文档和 API 文档
2. 实施计划 — 工具选择、共享实用程序、输入/输出设计、错误处理
3. 实施 — 项目结构、核心基础设施、具备适当架构和文档的工具，以及特定语言的最佳实践
4. 审查与改进 — 代码质量审查（DRY、可组合性、一致性）、测试与构建
5. 创建评估 — 编写 10 个真实、复杂、只读的评估问题，并核实答案

关键规则：

• 围绕工作流构建：不只是 API 封装，还要整合相关操作
• 优化上下文：返回高信号信息，并支持简洁/详细格式
• 提供可执行的错误信息：通过具体建议引导 Agent 正确使用
• 优先使用脚本：执行检测/获取/分析脚本，实现零 Token 开销

保持审慎。运用批判性思维和顺序思维。每项声明都需要可追溯的证据和置信度百分比（Idea 应高于 80%）。

MCP 服务开发指南

概述

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

---

流程

🚀 高层工作流

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

阶段 1：深入研究与规划

1.1 理解以 Agent 为中心的设计原则

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

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

• 构建经过深思熟虑、影响显著的工作流工具，不要只是一对一地封装现有 API 端点
• 合并相关操作（例如，schedule_event 同时检查可用时间并创建活动）
• 专注于能够完成完整任务的工具，而不只是单个 API 调用
• 考虑 Agent 实际需要完成哪些工作流

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

• Agent 的上下文窗口有限，因此每个 token 都要物尽其用
• 返回高价值信息，而不是详尽的数据倾倒
• 提供“简洁”和“详细”两种响应格式选项
• 默认使用易于人类阅读的标识符，而不是技术代码（名称优于 ID）
• 将 Agent 的上下文预算视为稀缺资源

设计可指导后续操作的错误消息：

• 错误消息应引导 Agent 采用正确的使用方式
• 提供具体的后续步骤建议：“尝试使用 filter='active_only' 来减少结果”
• 让错误消息具有指导性，而不只是用于诊断
• 通过清晰的反馈帮助 Agent 学会正确使用工具

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

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

采用评估驱动的开发方式：

• 尽早创建贴近实际的评估场景
• 根据 Agent 的反馈改进工具
• 快速制作原型，并根据 Agent 的实际表现进行迭代

1.3 学习 MCP 协议文档

获取最新的 MCP 协议文档：

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

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

1.4 学习框架文档

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

• MCP 最佳实践：📋 查看最佳实践 — 所有 MCP 服务的核心指南

对于 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 使用质量检查清单

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

• Python：参见 🐍 Python 指南中的“质量检查清单”
• Node/TypeScript：参见 ⚡ TypeScript 指南中的“质量检查清单”

---

第 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 格式规范
  • 问题和答案示例
  • 使用提供的脚本运行评估

相关内容

• mcp-management
• claude-code

---

[IMPORTANT] 开始前，使用任务跟踪将所有工作拆分成小任务——包括为每个要读取的文件创建任务。这可以防止长文件导致上下文丢失。对于简单任务，AI MUST ATTENTION 询问用户是否跳过。

防止 AI 出错——每项任务都要避免以下失败模式： 删除前检查下游引用。 删除组件会引发文档和代码过时的连锁问题。移除前，先梳理所有引用该组件的文件。 根据实际代码验证 AI 生成的内容。 AI 可能会臆造 API、类名和方法签名。记录或引用前，务必使用 grep 确认其存在。 编辑后追踪完整依赖链。 修改定义时，可能会遗漏下游变量及其使用方。务必追踪完整依赖链。 验证正确性时追踪所有代码路径。 确认代码存在，不代表它会执行。务必追踪提前退出、错误分支和条件跳过，不要只检查正常路径。 调试时，修复前先问“该由谁负责？”。 追踪问题出在调用方（数据错误）还是被调用方（处理错误）。在责任所在的层修复，切勿只修补表面症状。 假定现有值是有意设置的——更改前先问为什么。 更改任何常量、限制、标志或模式前：阅读注释、检查 git blame，并查看周边代码。 验证所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，必须验证每个输出。通过一项检查，不代表所有检查都通过。 整体优先的调试——警惕注意力被最近线索吸引。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐项根据证据验证，然后再推测代码层面的原因。 精确修改——执行差异检查。 修复 bug 时，每一处更改都必须能直接追溯到该 bug。不要顺手调整格式或改进相邻代码。处理增强任务时，落实改进并明确说明。 编码前明确歧义——不要默默自行选择。 如果请求有多种解释，列出每种解释及其工作量估算并询问用户。绝不要擅自假定应处理所有记录、采用基于文件的方案或选择更复杂的路径。

批判性思维模式——运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，置信度超过 80% 才能采取行动。 防止幻觉： 绝不要把猜测说成事实——每项主张都要引用来源，坦然承认不确定性，自查输出是否有误，独立交叉核验，并对自己的判断保持怀疑——没有证据的确定性是所有幻觉的根源。

MUST ATTENTION 运用批判性思维——每项主张都必须有可追溯的证据，置信度超过 80% 才能采取行动。防止幻觉：绝不要把猜测说成事实。

MUST ATTENTION 落实 AI 错误预防措施——整体优先调试、在责任所在的层修复、编码前明确歧义、上下文压缩后重新阅读文件。

收尾提醒

IMPORTANT MUST ATTENTION 开始前，使用任务跟踪将工作拆分成小型待办任务 IMPORTANT MUST ATTENTION 新建代码前，在代码库中搜索 3 个或更多相似模式 IMPORTANT MUST ATTENTION 每项主张都要引用 file:line 证据（置信度超过 80% 才能采取行动） IMPORTANT MUST ATTENTION 添加一项最终审查待办任务，以验证工作质量

[TASK-PLANNING] 开始前，分析任务范围，并使用任务跟踪系统地将工作拆分成小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制、重要、必须、关键。无论出于何种原因，都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应与项目无关；从 docs/project-config.json 和 docs/project-reference/ 中查找项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
5. 创建任务： 跟踪工作流的所有步骤
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。