MCP Services

MCP 服务使用规范（全量）

本文件是 MCP 的全量使用规范与手册，目标是把 MCP 相关规则集中在一个地方，避免分散与丢失信息。

提示：MCP 相关规则以本文件为唯一真源；不要在 rules 目录再维护一份重复的 mcp.md，避免漂移。

1. 全局原则

• 离线优先：能用本地工具完成的，不调用外部 MCP
• 单轮单工具：每轮对话最多调用 1–2 个 MCP 服务（超过时必须说明收益与原因）
• 最小必要：限制查询范围，避免过度数据捕获
• 可追溯：引用外部信息时标注来源

2. 工具决策流程

任务开始时，按以下流程判断是否使用 MCP 以及使用哪个：

Task received
  │
  ├─ Identify task type (code understanding / docs / repo search / complex planning / cross-agent collaboration)
  │
  ├─ Can native tools complete it efficiently?
  │    ├─ Yes → use native tools, skip MCP
  │    └─ No  → select the most suitable MCP service
  │
  └─ Execute and monitor
       ├─ Success → done
       └─ Failure → trigger switch (see below)

2.1 切换触发条件

2.2 缺失工具处理

当识别出任务需要但未配置的 MCP 时：

1. 告知用户缺失的工具及其价值
2. 提供安装配置命令
3. 用当前可用的方案先完成任务（降级执行）

3. 服务选择与触发时机

4. 服务使用指南

4.1 Sequential Thinking

结构化思维链工具，将复杂问题拆解为可执行的线性步骤。

适用场景：

• 多步骤任务的分解与排序（如：重构方案设计、迁移计划）
• 多方案权衡评估（需要列出 pros/cons 再做决策时）
• 风险识别与应对策略制定
• 调试时的根因分析（从现象倒推可能原因）

不适用场景：

• 单步骤简单任务（直接执行即可）
• 已有明确方案、无需权衡的场景
• 纯信息查询（改用 context7 或 codebase-retrieval）

使用约束：

• 步骤上限 6–10 步，每步一句话描述
• 输出可执行计划，不暴露中间推理过程
• 步骤间保持线性依赖，避免并行分支

4.2 Context7

基于 @upstash/context7-mcp 的技术文档检索工具，获取库/框架的最新官方文档。

适用场景：

• 查询第三方库的 API 用法和参数签名
• 确认框架最新版本的 breaking changes 或新特性
• 获取官方推荐的最佳实践和配置方式
• 对比不同版本间的 API 差异

不适用场景：

• 查询项目自身代码（改用 codebase-retrieval）
• 查询通用编程概念（Agent 自身知识已足够）
• 查询非公开的内部文档或私有 API

使用约束：

• 使用第三方库时，优先查询 Context7 获取最新文档，防止生成过时或不存在的 API
• 调用工作流：先 resolve-library-id 获取 Context7 ID（用户已提供 /org/project 格式时可跳过）→ 再 get-library-docs 获取文档
• 查询时指定具体的库名和版本号以提高准确性
• 优先用于 Agent 知识截止日期之后的新版本特性

与 google-developer-knowledge 的选择标准：

4.3 Async MCP（跨 Agent 协作）

允许不同 Agent CLI 之间互相异步调用，通过 uvx 运行，无需额外配置。

适用场景：

• 任务超出当前 Agent 的能力边界（如上下文窗口不足）
• 需要不同 Agent 的差异化优势（如 Claude 擅长推理、Codex 擅长代码生成）
• 并行处理独立子任务以提高效率
• 需要二次验证（让另一个 Agent 审查方案）

不适用场景：

• 当前 Agent 可以独立完成的简单任务
• 需要实时交互的场景（异步调用有延迟）
• 涉及敏感信息且不宜跨 Agent 传递的任务

4.4 GitHub MCP（GitHub 全平台检索与项目管理）

基于 github/github-mcp-server 的官方 MCP 服务，通过 Docker 运行，需要 GITHUB_PERSONAL_ACCESS_TOKEN。

核心工具分类

适用场景

场景 1：寻找类似功能的开源库

• 用 search_repositories 按关键词 + 语言 + 最低 stars 筛选
• 用 get_file_contents 阅读候选库的 README 和核心代码
• 用 list_commits 判断项目活跃度

示例："搜索 Kotlin 语言、stars > 100 的图片加载库" → search_repositories

场景 2：学习某功能的实现方式

• 用 search_code 在高质量仓库中搜索特定 API/模式的用法
• 用 get_repository_tree 了解项目结构，再用 get_file_contents 读具体实现
• 用 get_commit 查看关键功能是如何逐步引入的

示例："在 OkHttp 仓库中搜索拦截器链的实现" → search_code + get_file_contents

场景 3：项目日常管理

• 用 search_issues / search_pull_requests 查找相关 Issue 和 PR
• 用 create_pull_request 直接创建 PR
• 用 list_code_scanning_alerts 检查安全告警

场景 4：技术选型调研

• 用 search_repositories 对比多个候选库（stars、最近提交、license）
• 用 get_latest_release 确认版本发布节奏
• 用 list_dependabot_alerts 评估依赖安全性

不适用场景

• 搜索项目自身代码（改用 codebase-retrieval）
• 查询库的官方文档和 API 说明（改用 context7）
• 不需要 GitHub 数据的纯本地任务

4.5 JetBrains MCP（IDE 集成）

通过 SSE 协议连接本地运行的 JetBrains IDE（IntelliJ IDEA、Android Studio、WebStorm 等），端口固定为 64343。

决策规则、降级策略与执行方法见 jetbrains-skill（其中包含“何时不使用/降级策略”部分）。

适用场景：

• 在 IDE 中执行代码导航（跳转到定义、查找用法、查看类层次）
• 触发 IDE 内置重构操作（重命名、提取方法/变量、移动类）
• 读取 IDE 感知的项目信息（运行配置、模块结构、依赖树）
• 利用 IDE 内置的代码分析和检查能力（Lint、Inspection）
• 在 IDE 中执行构建、运行或调试任务

不适用场景：

• IDE 未启动时（SSE 端点不可用，会连接失败）
• 纯文本编辑（Agent 自身的文件读写能力已足够）
• 查询第三方库文档（改用 context7）
• 语义级代码搜索（改用 codebase-retrieval）

使用约束：

• 需要 JetBrains IDE 已安装并启用 MCP 插件
• IDE 必须处于运行状态，端口 64343 可达
• 操作结果依赖 IDE 当前打开的项目上下文

4.6 Google Developer Knowledge（Google 官方文档检索）

Google 提供的远程 MCP 服务（HTTP 类型），通过 GOOGLE_DEVELOPER_KNOWLEDGE_API_KEY 鉴权，直接检索 Google 官方开发者文档。

核心工具

覆盖范围

Android (developer.android.com)、Firebase (firebase.google.com)、Google Cloud (docs.cloud.google.com)、Chrome (developer.chrome.com)、Google AI (ai.google.dev)、Google Maps / Ads / Search / YouTube (developers.google.com)、Google Home (developers.home.google.com)、TensorFlow (www.tensorflow.org)、Web (web.dev)、Apigee (docs.apigee.com)、Fuchsia (fuchsia.dev)

适用场景

• 查询 Google 系 SDK 的 API 用法、参数签名、代码示例
• 获取 Android / Firebase / Cloud 等产品的最佳实践和配置指南
• 排查 Google API 相关错误（如 Maps API key 问题、Cloud IAM 配置）
• 对比 Google 产品的功能差异（如 Cloud Run vs Cloud Functions）

不适用场景

• 查询非 Google 的第三方库文档（改用 context7）
• 搜索项目自身代码（改用 codebase-retrieval）
• 查询 GitHub、博客、YouTube 等非官方文档来源（不在覆盖范围内）
• 非英语文档查询（仅支持英文结果）

使用约束

• 仅英文结果：不支持中文等其他语言的文档
• 仅公开文档：不含 GitHub、OSS 站点、博客或 YouTube 内容
• 网络依赖：依赖 Google Cloud 在线服务，离线不可用
• 推荐工作流：先 search_documents 获取片段 → 片段不够详细时用 get_document 或 batch_get_documents 获取全文

5. Auggie-MCP codebase-retrieval 使用规范

5.1 工具定位

codebase-retrieval 是基于语义嵌入的 AI 代码检索引擎，支持自然语言查询、跨语言检索，实时索引当前工作副本代码。

5.2 适用场景（优先使用）

• 理解业务流程 / 架构：
  • "用户认证是在哪个模块里实现的？"
  • "登录功能有哪些测试用例？"
  • "数据库是如何连接到应用的？"
• 追踪调用链：了解模块职责、业务流程关键入口
• 编辑前上下文获取：修改代码前，先用它查询涉及的类、函数、属性等完整定义

5.3 不适用场景（改用 grep / IDE）

• 精确查找某个类 / 函数定义（如 class Foo）
• 查找某个函数的所有调用点（find all references）
• 查看某个文件的全文内容
• 精确字符串 / 常量匹配（UUID、配置值、错误信息）
• 代码注释标记搜索（TODO、FIXME、HACK）

5.4 编辑前深度查询协议

在编辑任何文件之前，必须先调用 codebase-retrieval 获取详细上下文：

查询示例：

• ✅ "我要修改 UserService.login()，请提供：UserService 类定义、login 方法实现、它调用的 AuthProvider 接口和 TokenManager 相关方法"
• ❌ 分多次分别查询每个符号

5.5 搜索工具快速选择表

6. 常见多工具协作模式

单个 MCP 解决单一问题，多个 MCP 串联解决复合任务。以下是常见的协作模式：

6.1 技术选型调研

github (search_repositories)  →  context7 / google-developer-knowledge  →  sequential-thinking
   discover candidates             query docs (by product)                    weigh pros/cons and decide

典型流程：

1. github: search_repositories 按语言 + stars 筛选候选库
2. github: get_file_contents 阅读候选库 README 和核心代码
3. 文档查询（按归属选择）：Google 系产品用 google-developer-knowledge，其他用 context7
4. sequential-thinking: 列出对比维度，逐步权衡，输出推荐方案

6.2 新代码库上手

codebase-retrieval  →  github (search_code)  →  context7 / google-developer-knowledge
  understand local arch     search similar impls        query dependency docs

典型流程：

1. codebase-retrieval: 了解项目整体架构、模块划分、核心入口
2. codebase-retrieval: 追踪关键业务流程的调用链
3. github: search_code 搜索同类项目中类似功能的实现方式作为参考
4. 文档查询：Google 系产品用 google-developer-knowledge，其他用 context7

6.3 复杂功能规划

codebase-retrieval  →  sequential-thinking  →  async-mcp (optional)
   survey existing code        plan steps           delegate subtasks

典型流程：

1. codebase-retrieval: 查询涉及修改的所有类、函数、依赖关系
2. sequential-thinking: 将需求拆解为 6–10 个可执行步骤
3. async-mcp（可选）: 将独立子任务委派给其他 Agent 并行处理

6.4 Bug 排查

codebase-retrieval  →  github (search_issues)  →  context7 / google-developer-knowledge
   locate problem code          search known issues            query correct API usage

典型流程：

1. codebase-retrieval: 根据错误现象定位相关代码和调用链
2. github: search_issues 在依赖库中搜索是否为已知问题
3. 文档查询：Google 系 API 问题用 google-developer-knowledge，其他用 context7

7. 失败降级

7.1 通用原则

• 首选服务失败时，尝试备用服务
• 全部失败时，提供保守的本地答案并标注不确定性
• 记录失败原因，便于后续优化

7.2 各服务降级策略