05 - MCP 服务体系设计

1. 定位

MCP（Model Context Protocol）服务器通过标准协议连接外部工具和服务，扩展 Claude Code 的能力边界。

核心定位：MCP 是胶水，不是大脑。 它负责连接和数据搬运，不负责决策。决策由 Prompt/Skill/SubAgent 完成。

2. 关键约束

同时激活不超过 5 个 MCP — 每个 MCP 都向上下文注入工具定义，消耗 token
总 MCP 上下文控制在约 20K token 以内 — 超出会挤压有效工作空间
Tool Search 延迟发现 — Claude Code 默认启用 Tool Search Tool，MCP 工具最多加载上下文的 10%，其余按需延迟发现。内部测试显示可节省约 85% token，Opus 4 工具调用成功率从 49%→74%，Opus 4.5 从 79.5%→88.1%。可在 MCP 配置中对不常用工具设置 defer_loading: true 标记为可发现但不预加载
禁用未使用的 MCP — 即使不调用，工具定义仍然占用上下文
MCP 每次会话都占 context，Skill 按需加载 — 能用 Skill 解决的不用 MCP
审慎对待第三方 MCP — 第三方 MCP 服务器存在 prompt injection 风险，优先使用官方或经过审计的服务器
显式禁用项目 MCP 自动加载 — 在 settings.json 中设置 "enableAllProjectMcpServers": false。.mcp.json 存在于 git 中，恶意或被入侵的仓库可能通过 .mcp.json 注入 MCP 服务器。显式禁用后，每个项目 MCP 需要手动确认启用

3. MCP vs Skill 的边界

场景	用 MCP	用 Skill
查询实时数据库	Yes	No
操作浏览器做 E2E 测试	Yes	No
检索第三方库最新文档	Yes	No
代码审查流程	No	Yes
生成 commit message	No	Yes
编码规范检查	No	Yes（或 Hook）
项目脚手架生成	No	Yes

判断标准：需要访问外部实时系统 → MCP，固化的内部流程 → Skill

4. React + Node.js 全栈推荐 MCP 清单

4.1 P0 — 强烈推荐（日常必用）

Context7 — 实时框架文档

解决 AI 知识截止日期问题。Next.js、React、Prisma 等快速迭代框架的最新文档。

json

{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp@latest"]
  }
}

使用场景：

用到框架新 API 时："用 Context7 查一下 Next.js 15 的 Server Actions 用法"
遇到废弃警告时："查一下 React 19 中 forwardRef 的替代方案"

Playwright — 浏览器自动化

E2E 测试和 UI 验证，使用无障碍树（非截图），更高效。

json

{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest"]
  }
}

使用场景：

验证前端页面渲染是否正确
自动化 E2E 测试执行
调试 UI 交互问题

4.2 P1 — 推荐（按需启用）

PostgreSQL — 数据库操作

直接在 Claude Code 中查询和验证数据库。

json

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
    }
  }
}

使用场景：

验证 Prisma migration 是否正确执行
调试数据问题（直接查询验证）
Schema 设计时检查索引和约束

Sequential Thinking — 链式推理

复杂问题的结构化思考，减少幻觉。

json

{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  }
}

使用场景：

复杂架构决策（多方案权衡）
难以定位的 Bug 分析
大型功能的分步规划

Figma MCP — 设计稿到代码

从 Figma 设计文件中提取结构化设计信息，实现 Design-to-Code 工作流。

配置（官方 Remote MCP Server，无需桌面端）：

bash

# 项目级安装
claude mcp add --transport http figma https://mcp.figma.com/mcp

# 全局安装（跨项目共享，推荐）
claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

# 首次使用：/mcp → 选择 figma → Authenticate 完成 OAuth 授权

也可写入 .mcp.json 供团队共享：

json

{
  "figma": {
    "type": "http",
    "url": "https://mcp.figma.com/mcp"
  }
}

核心工具（13 个中最常用的 6 个）：

工具	功能
`get_design_context`	提取选中图层的结构化表示（默认 React + Tailwind），包含样式和布局
`get_metadata`	获取大文件节点地图，大型设计应先调用此工具再精准获取子节点
`get_screenshot`	捕获视觉截图，用于实现后的 1:1 对比
`get_code_connect_map`	获取 Figma 组件→代码组件的映射关系
`add_code_connect_map`	建立/更新组件映射，让 AI 遇到设计组件实例时直接导入生产组件
`create_design_system_rules`	自动生成设计系统规则文件，约束 AI 代码生成行为

其他工具：get_variable_defs（design tokens）、generate_figma_design（Code to Canvas，将代码 UI 推送到 Figma，仅 Remote Server 支持）等。

使用场景：

从 Figma 设计稿生成页面代码（粘贴 Figma 链接即可）
提取 design tokens 生成 Tailwind 配置或 CSS 变量
Code Connect：AI 遇到设计中的组件实例时直接导入已有生产组件
双向迭代：代码→Figma→精修→拉回代码

注意事项：

要点	说明
速率限制	Dev/Full 席位：约 10-20 次/分，200-600 次/天；Starter 计划：仅 6 次/月
Token 超限	`get_design_context` 对大型设计可能返回 35 万+ token，先用 `get_metadata` 获取节点地图再精准获取子节点
Figma 文件质量	语义化命名、Auto Layout、组件化、变量定义——直接决定 MCP 输出质量
安全	优先使用 Figma 官方 MCP Server，第三方方案曾有 RCE 漏洞

详细的 UI 开发工作流配合见 doc-11 §4.3 和 §5。

4.3 P2 — 可选（特定场景）

GitHub MCP — PR/Issue 管理

替代手动切换到 GitHub 网页。

json

{
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp",
    "headers": {
      "Authorization": "Bearer ${GITHUB_PAT}"
    }
  }
}

Memory — 跨会话记忆

知识图谱存储，跨会话保持记忆。

json

{
  "memory": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"],
    "env": {
      "MEMORY_FILE_PATH": "./.claude/memory.jsonl"
    }
  }
}

Codex MCP — 异构模型审查

跨模型族的反证审查器。在高风险变更的设计/实施/验收节点调用 OpenAI Codex，获取异构"第二意见"，补足同模型体系的确认偏差。

配置（一次性，用户级）：

bash

# 前置：安装 Codex CLI 并认证
npm i -g @openai/codex
export OPENAI_API_KEY='your_key'
printenv OPENAI_API_KEY | codex login --with-api-key

# 注册 MCP（仅需一次）
claude mcp add --scope user codex -- codex mcp-server

# 验证
claude mcp list

使用原则：

门禁触发，不常驻 — 仅在高风险变更时启用（认证/支付/数据迁移/核心架构），日常 CRUD 不调用
反证视角，不做决策 — Codex 提供风险假设和反例，人做最终仲裁，符合"胶水不是大脑"
按需启停 — 不计入日常 5 个 MCP 配额，用完即可 claude mcp remove codex 或下次按需重新启用
注意数据外发 — 代码会发送到 OpenAI API，评估隐私/合规要求

调用模板（三个关键节点）：

节点	调用时机	Prompt 示例
设计关	方案确定前	`用 Codex 审查这个架构方案，列出风险假设和反例`
实施关	核心代码完成后	`用 Codex 审查 git diff，找出可能导致崩溃或数据丢失的场景`
验收关	合并前	`用 Codex 做最终安全审查，列出遗漏的边界条件`

成本提示： 额外产生 OpenAI API 费用。对个人开发者，建议先做 2 周试点，记录发现问题数和误报率，评估 ROI 后决定是否长期启用。

风险与缓解：

风险	缓解
结论冲突（Claude vs Codex 意见相反）	人工仲裁，参考三会话隔离审查模式（食谱 04 §6）
成本失控	门禁触发 + 限制上下文大小（只传 diff，不传全量代码）
过度依赖	"第二意见"≠"最终正确"，始终由人做最终决策

5. .mcp.json 配置模板

项目根目录的 .mcp.json（Git 追踪，团队共享）：

json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

用户级配置 ~/.claude.json（个人全局）：

json

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

原则：项目共用的 MCP 放 .mcp.json，个人偏好的 MCP 放 ~/.claude.json。

6. MCP 管理命令

bash

# 添加 MCP
claude mcp add context7 npx -- -y @upstash/context7-mcp@latest

# 查看已配置的 MCP
claude mcp list

# 移除 MCP
claude mcp remove context7

# 添加到项目级（默认）vs 用户级
claude mcp add --scope project context7 ...
claude mcp add --scope user sequential-thinking ...

作用域优先级： local（会话级）> project（.mcp.json）> user（~/.claude.json）。同名 MCP 服务器，高优先级层级的配置胜出。

7. 性能与成本考量

按需启用策略

不是所有 MCP 都需要一直开着：

日常开发：Context7（查文档）
前端调试：+ Playwright
数据库工作：+ PostgreSQL
架构设计：+ Sequential Thinking
发布流程：+ GitHub

建议在 .mcp.json 中只配置最常用的 2 个，其他通过 claude mcp add 临时启用。

MCP 故障处理

故障	表现	处理
MCP 服务器启动失败	会话启动时报错	检查 npx 版本和网络，或临时 remove
MCP 调用超时	工具调用长时间无响应	检查外部服务连通性
MCP 连接静默断开	工具突然不可用，无显式报错	输入 `/mcp` 检查连接状态，必要时重启会话
MCP 返回错误数据	AI 基于错误信息做判断	让 AI 验证 MCP 返回内容的合理性
上下文被 MCP 挤占	AI 开始"忘记"之前的指令	减少同时启用的 MCP 数量

8. 与其他子系统的关系

CLAUDE.md：MCP 的使用规则写在 CLAUDE.md 中
  如："使用 Context7 查询框架文档时，指定具体版本号"

Skills：Skill 内部可以指导何时调用 MCP
  如：/plan Skill 内部 "使用 Sequential Thinking 分析方案"

SubAgents：子代理可以调用 MCP
  如：Explore Agent 可以调用 Context7 查文档

Hooks：Hooks 不直接调用 MCP
  Hooks 是确定性脚本，不经过 Claude 的工具调用机制

Codex MCP：作为 P2 异构审查器，与 /review Skill 互补
  如：高风险变更时 /review 先做内部审查，再用 Codex 做异构复审

05 - MCP 服务体系设计 ​

1. 定位 ​

2. 关键约束 ​

3. MCP vs Skill 的边界 ​

4. React + Node.js 全栈推荐 MCP 清单 ​

4.1 P0 — 强烈推荐（日常必用） ​

Context7 — 实时框架文档 ​

Playwright — 浏览器自动化 ​

4.2 P1 — 推荐（按需启用） ​

PostgreSQL — 数据库操作 ​

Sequential Thinking — 链式推理 ​

Figma MCP — 设计稿到代码 ​

4.3 P2 — 可选（特定场景） ​

GitHub MCP — PR/Issue 管理 ​

Memory — 跨会话记忆 ​

Codex MCP — 异构模型审查 ​

5. .mcp.json 配置模板 ​

6. MCP 管理命令 ​

7. 性能与成本考量 ​

按需启用策略 ​

MCP 故障处理 ​

8. 与其他子系统的关系 ​

05 - MCP 服务体系设计

1. 定位

2. 关键约束

3. MCP vs Skill 的边界

4. React + Node.js 全栈推荐 MCP 清单

4.1 P0 — 强烈推荐（日常必用）

Context7 — 实时框架文档

Playwright — 浏览器自动化

4.2 P1 — 推荐（按需启用）

PostgreSQL — 数据库操作

Sequential Thinking — 链式推理

Figma MCP — 设计稿到代码

4.3 P2 — 可选（特定场景）

GitHub MCP — PR/Issue 管理

Memory — 跨会话记忆

Codex MCP — 异构模型审查

5. .mcp.json 配置模板

6. MCP 管理命令

7. 性能与成本考量

按需启用策略

MCP 故障处理

8. 与其他子系统的关系