MCP Setup 指南

spec-mcp-setup 是进入主工作流前的 readiness 入口。它负责检查并准备宿主运行 spec-first workflow 所需的 MCP servers、graph provider 配置、helper CLIs 和项目 setup facts。

使用方式

宿主	入口
Claude Code	/spec:mcp-setup
Codex	$spec-mcp-setup

先运行 package CLI 的 spec-first doctor 和 spec-first init --claude / spec-first init --codex，再重启宿主进入本 workflow。

执行逻辑图

用户运行 /spec:mcp-setup 或 $spec-mcp-setup
  |
  v
读取 AGENTS.md / CLAUDE.md、developer profile、runtime state
  |
  v
检查 Node、Git、MCP servers、graph providers、helper CLIs
  |
  +-- 缺失或不可用
  |     |
  |     v
  |   输出 blocked / degraded 原因和修复动作
  |
  +-- 可用
        |
        v
      写入 .spec-first/config/*
        |
        v
      记录 provider artifact path contract 和 fallback 能力
        |
        v
      提示下一步运行 spec-graph-bootstrap

产物边界

目录	作用
.spec-first/config/	host baseline、provider 配置、fallback 能力和 artifact path contract
.spec-first/providers/	provider 运行状态、原始日志和 normalized facts 的上游位置

这些产物是当前机器的 control-plane facts。它们通常不作为长期知识提交，除非团队明确需要共享某个 reviewable artifact。

Helper 工具范围

spec-mcp-setup 在 host runtime 之外还会检查并按需引导安装以下本地 helper：

Helper	角色
agent-browser	浏览器自动化，供 polish/visual review 等 UI 工作流使用
ast-grep	结构化代码搜索，支撑 code review 与 refactor 类决策
gh	GitHub CLI，PR / issue 检索与发布脚本
jq	JSON 处理与 readiness ledger 解析
vhs / silicon / ffmpeg	终端录制、代码截图与视频转码，供 feature 演示与 release notes 使用

helper 不可用不会阻塞主链 workflow，但相关能力会进入 degraded 状态；setup 输出会列出每项 helper 的 install/verify 结果。

下一步

spec-mcp-setup ready 后，继续运行：

spec-mcp-setup
→ spec-graph-bootstrap
→ spec-standards
→ ideate / brainstorm / plan / work / review

如果 setup 显示某个 provider 或 helper tool 不可用，后续 workflow 应明确说明 degraded 状态，并降级到 bounded direct repo reads。