mcp-management

Codex 兼容性说明：

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

Codex 项目参考文档加载（无钩子）

Codex 不会接收基于 Claude 钩子的文档注入。 进行编码、规划、调试、测试或审查时，请使用以下路由明确打开项目文档。

始终阅读：

• 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 工具／提示词／资源，同时避免污染主上下文。

工作流：

1. 配置管理 — 使用 .claude/.mcp.json，并为 Gemini CLI 建立指向 .gemini/settings.json 的符号链接
2. 能力发现 — 运行 npx tsx scripts/cli.ts list-tools，将结果保存到 assets/tools.json
3. 智能选择 — LLM 分析 tools.json，找出与任务相关的能力
4. 执行 — 首选：通过 stdin 管道使用 Gemini CLI；次选：直接运行脚本；后备：通用子 Agent

关键规则：

• Gemini CLI 优先：使用 stdin 管道（echo "task" | gemini），不要使用 -p 标志（会跳过 MCP 初始化）
• GEMINI.md 自动加载：项目根目录中的文件要求 Gemini 返回结构化 JSON
• 渐进式披露：仅加载所需能力，由子 Agent 负责发现
• 持久化目录：list-tools 会将完整架构保存到 assets/tools.json，以便快速查阅

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

MCP 管理

用于管理和使用 Model Context Protocol（MCP）服务的技能。

先决条件

⚠️ 务必先阅读 references/configuration.md 和 references/gemini-cli-integration.md，再执行操作——这些文件包含 MCP 服务配置格式、Gemini CLI 设置、执行模式和故障排查信息，是下文“核心能力”和“实现模式”部分所必需的。若需了解协议内部机制，也**⚠️ 务必先阅读** references/mcp-protocol.md。

概述

MCP 是一种开放协议，可让 AI Agent 连接到外部工具和数据源。此技能提供脚本和实用工具，用于发现、分析和执行已配置服务上的 MCP 功能，同时避免占用主上下文窗口。

主要优势：

• 渐进式展示 MCP 功能（仅加载所需内容）
• 根据任务需求智能选择工具／提示词／资源
• 通过单个配置文件管理多个服务
• 高效利用上下文：由子 Agent 处理 MCP 发现和执行
• 持久化工具目录：自动将发现的工具保存为 JSON，以便快速查阅

何时使用此技能

在以下情况下使用此技能：

1. 发现 MCP 功能：需要列出已配置服务上可用的工具／提示词／资源
2. 基于任务选择工具：分析哪些 MCP 工具与特定任务相关
3. 执行 MCP 工具：以编程方式调用 MCP 工具，并妥善处理参数
4. MCP 集成：构建或调试 MCP 客户端实现
5. 上下文管理：将 MCP 操作委托给子 Agent，避免上下文受到干扰

核心功能

1. 配置管理

在 .claude/.mcp.json 中配置 MCP 服务。

Gemini CLI 集成（推荐）：创建指向 .gemini/settings.json 的符号链接：

mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json

请参阅 references/configuration.md 和 references/gemini-cli-integration.md。

GEMINI.md 响应格式：项目根目录包含 GEMINI.md，Gemini CLI 会自动加载该文件，以强制使用结构化 JSON 响应：

{"server":"name","tool":"name","success":true,"result":<data>,"error":null}

这样可确保输出可解析且一致，而不是难以预测的自然语言。该文件定义了：

• 必须仅使用 JSON 的响应格式（不含 Markdown 或解释）
• 响应最长为 500 个字符
• 错误处理结构
• 可用 MCP 服务参考

优势：输出可供程序解析，错误报告一致，配置符合 DRY 原则（格式只定义一次），高效利用上下文（由 Gemini CLI 自动加载）。

2. 功能发现

npx tsx scripts/cli.ts list-tools  # Saves to assets/tools.json
npx tsx scripts/cli.ts list-prompts
npx tsx scripts/cli.ts list-resources

汇总多个服务的功能，并标明服务来源。

3. 智能工具分析

大模型直接分析 assets/tools.json，效果优于关键词匹配算法。

4. 工具执行

主要方式：Gemini CLI（如果可用）

# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
echo "Take a screenshot of https://example.com" | gemini -y -m gemini-2.5-flash

次要方式：直接运行脚本

npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'

备用方式：通用 Agent

完整示例请参阅 references/gemini-cli-integration.md。

实现模式

模式 1：Gemini CLI 自动执行（主要方式）

使用 Gemini CLI 自动发现并执行工具。Gemini CLI 会自动加载项目根目录中的 GEMINI.md，以强制使用结构化 JSON 响应。

快速示例：

# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
# Add "Return JSON only per GEMINI.md instructions" to enforce structured output
echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash

预期输出：

{ "server": "puppeteer", "tool": "screenshot", "success": true, "result": "screenshot.png", "error": null }

优势：

• 自动发现工具
• 结构化 JSON 响应（可由 Claude 解析）
• 自动加载 GEMINI.md，确保格式一致
• 比子 Agent 协作更快
• 避免自然语言歧义

完整指南请参阅 references/gemini-cli-integration.md。

模式 2：基于子 Agent 的执行（备用方式）

当 Gemini CLI 不可用时，使用 general-purpose Agent。子 Agent 会发现工具、选择相关工具、执行任务并汇报结果。

优势：主上下文保持干净，仅在需要时加载相关工具定义。

模式 3：由大模型驱动的工具选择

大模型读取 assets/tools.json，利用上下文理解、同义词和意图识别，智能选择相关工具。

模式 4：多服务编排

协调多个服务上的工具。每个工具都会记录其来源服务，以便正确路由。

脚本参考

scripts/mcp-client.ts

核心 MCP 客户端管理类。负责：

• 从 .claude/.mcp.json 加载配置
• 连接多个 MCP 服务
• 列出所有服务中的工具、提示词和资源
• 妥善处理错误并执行工具
• 管理连接生命周期

scripts/cli.ts

用于 MCP 操作的命令行界面。命令：

• list-tools - 显示所有工具并保存到 assets/tools.json
• list-prompts - 显示所有提示词
• list-resources - 显示所有资源
• call-tool <server> <tool> <json> - 执行工具

注意：list-tools 会将完整的工具目录（包含完整的架构）保存到 assets/tools.json，以便快速查阅、离线浏览和版本控制。

快速开始

方法 1：Gemini CLI（推荐）

npm install -g gemini-cli
mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json
# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
# GEMINI.md auto-loads to enforce JSON responses
echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash

返回结构化 JSON：{"server":"puppeteer","tool":"screenshot","success":true,"result":"screenshot.png","error":null}

方法 2：脚本

cd .claude/skills/mcp-management/scripts && npm install
npx tsx cli.ts list-tools  # Saves to assets/tools.json
npx tsx cli.ts call-tool memory create_entities '{"entities":[...]}'

方法 3：通用子 Agent

完整指南请参阅 references/gemini-cli-integration.md。

技术详情

请参阅 references/mcp-protocol.md，了解：

• JSON-RPC 协议详情
• 消息类型和格式
• 错误代码及处理方式
• 传输机制（stdio、HTTP+SSE）
• 最佳实践

集成策略

执行优先级

1. Gemini CLI（主要）：快速、自动、智能选择工具

   • 检查：command -v gemini
   • 执行：echo "<task>" | gemini -y -m gemini-2.5-flash
   • 重要：使用 stdin 管道传入内容，不要使用 -p 标志（已弃用，会跳过 MCP 初始化）
   • 最适用于：可用时的所有任务

2. 直接使用 CLI 脚本（次要）：手动指定工具

   • 使用场景：需要控制具体工具或服务时
   • 执行：npx tsx scripts/cli.ts call-tool <server> <tool> <args>

3. 通用子 Agent（备用）：高效利用上下文进行委派

   • 使用场景：Gemini 不可用或执行失败时
   • 保持主上下文整洁

与 Agent 集成

general-purpose Agent 使用此技能来：

• 首先检查 Gemini CLI 是否可用
• 如果可用，通过 gemini 命令执行
• 回退到直接执行脚本
• 在不加载到主上下文的情况下发现 MCP 功能
• 将结果报告给主 Agent

这样可保持主 Agent 的上下文整洁，并实现高效的 MCP 集成。

相关内容

• mcp-builder
• claude-code

---

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

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

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

必须特别注意运用批判性思维——每项主张都必须有可追溯的证据，置信度 >80% 才可采取行动。防止幻觉：切勿把猜测说成事实。

必须特别注意应用 AI 错误防范措施——整体优先调试、在责任所在层修复、编码前指出歧义，并在上下文压缩后重新阅读文件。

收尾提醒

重要，必须特别注意 开始前使用任务跟踪将工作拆分为小型待办任务 重要，必须特别注意 新建代码前在代码库中搜索 3+ 个相似模式 重要，必须特别注意 每项主张都要引用 file:line 证据（置信度 >80% 才可采取行动） 重要，必须特别注意 添加最终审查待办任务，以验证工作质量 强制，重要，必须特别注意 开始前阅读以下文件： 重要，必须特别注意 开始前阅读 references/configuration.md 重要，必须特别注意 开始前阅读 references/mcp-protocol.md

[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] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。