manifestation-mcp

一个让编码智能体设计优先的 MCP 服务器。当你想构建某个东西时，它不会立刻一头扎进代码——而是退后一步，向你提问，梳理出规格说明，并以易于消化的分块形式呈现给你；接着把你的签字确认转化一份小步推进的红/绿 TDD 计划，然后运行一个子智能体驱动的开发循环（实现者 → 审查者 → 质量检查关卡）来独立推进整个计划。

它是一个可移植的 Python MCP 服务器：服务器是 大脑（一个五阶段状态机 + 你的规格/计划 + 技能库），并通过 Claude Agent SDK 在内部运行它自己的子智能体——因此一次 run 调用可以在较长时间内自主工作，而不会偏离计划。

五个阶段

DISCOVERY  → interview you; do NOT write code
SPEC       → draft a spec; sign off chunk-by-chunk
PLAN       → bite-sized red/green TDD task list (YAGNI, DRY)
EXECUTE    → per task: implementer subagent → reviewer subagent → gate
DONE       → artifacts left under .manifestation/ in your repo

状态以可检查的文件形式存放在目标仓库中： <repo>/.manifestation/<project-id>/{state.json, spec.md, plan.md}。

Related MCP server: Spec Guard

环境要求

• Python 3.10+

• uv（brew install uv）

• 实时执行（run）：你需要 PATH 上存在 Claude Code CLI，并拥有 Claude 凭证（ANTHROPIC_API_KEY 或一个已登录的 Claude Code 会话）。Agent SDK 会驱动它来运行实现者/审查者子智能体。

• 目标仓库中需要有 git — TDD 门禁使用 git worktree 验证确实存在先于实现的失败测试。

设置

cd manifestation-mcp
uv sync
uv run pytest        # 96 tests, no network required (1 live smoke skipped)

运行

推荐使用本地启动器（以规避 uv 可编辑安装的怪癖）：

uv run python run_server.py

将其注册到 Claude Code：

claude mcp add manifestation -- uv run --project /ABS/PATH/TO/manifestation-mcp python /ABS/PATH/TO/manifestation-mcp/run_server.py

（对于通过 uvx/pipx 打包安装，manifestation-mcp 控制台脚本可以直接使用。）

自动触发（可选）

将 skill-shim/SKILL.md 复制到你的 Claude Code 技能（例如 ~/.claude/skills/manifestation/SKILL.md）。其描述会在“build / implement / add a feature”这类任务时触发，从而自动启动工作流——你无需手动调用任何内容。如果没有它，你也可以通过 /manifestation 提示词或调用 start_project 工具手动启动。

工具

Prompt：/atth/manifestation <brief>；资源：skills://atll、skill://<name>资源。

模型选择

没有哪一处被硬编码为某个特定 |安全模型为空。默认情况下，服务器 继承 Claude Code CLI 当前使用的模型。你可以用 MANIFESTATION_MODEL 环境变量全局覆盖（如 MANIFESTATION_MODEL=claude-opus-5），也可以在代码中通过 AgentSDKClient(model=...) 按次调用覆盖。

安全模型（使用 `时请先阅读）

run 会在仓库中执行真实的子代理，因此请明确信任边界：

• 实现者拥有写入和 Bash 权限。这意味着它可以在目标仓库内执行任意代码，这是设计的——只对受信任的仓库运行，对于不受信任的工作建议使用容器或 VM。没有沙箱。

• 评审者和规划者以两种方式实现只读：SDK 的 disalowowed_tools 屏蔽了修改工具，此外，can_use_tool 权限回调拒绝一切不在它们白名单上的工具——涵盖了我们未显式列出的所有工具（WebFetch、Task、MCP tools）。即使在不信任的仓库中也绝对安全。

• TDD 以 server 端验证为准，不依赖对话文字。实现者运行结束后，服务端会自己运行任务声明的单测：它必须在 HEAD <0>（真实 GREEN）通过，并且必须在临时 git worktree 中，针对实现者仅含测试的提交（<0>HEAD~1</0>）重新运行时失败（真实 RED）。任何伪造或篡改顺序的行为都会被识破；如果 git/test 无法证明，则默认 fail-close。

• 如果出现 PASS 但仍有任何尾部发现，则被视为矛盾，系统判定任务失败。

• <0>run</0> 要求计划已经获得批准，每一步之后都设置检查点（若崩溃，也会在恢复时从 review 步骤继续，而非重跑实现者，从而避免重复编辑；它会保留完整的审计日志（axit trail），并且永远有界—— <0>axax</0>/ax_ax（两者都由 MCP 暴露），此外还有内置默认限额。

• 用进程内锁和跨进程文件锁，对每个项目的修改工具调用进行串行化。

• 通过 brief/answers/spec 的 prompt 注入仍可能进入子代理提示词——请将项目输入视为不受信任的数据。

如何保持诚实（并保持可测试性）

所有 LLM 交互都经过唯一的可注入界面（<0>）（...</0>。单元测试注入 <0>FakeLLMClient</0>，因此接住整个状态机——发现、规格切分、计划生成，以及带重试/review 门禁的执行循环——都可以在<0>零网络调用</0>下得到验证。真正的 AgentSDKClient 位于这一接口之后，只在 opt-in 的 live 冒烟测试中运行。

架构

src/manifestation_mcp/
  server.py     # MCP tools/prompts/resources (thin wiring)
  state.py      # Project/Phase/Task model + file persistence + registry
  llm.py        # LLMClient seam: FakeLLMClient (tests) + AgentSDKClient (real)
  agents.py     # implementer / reviewer / planner subagent presets
  runner.py     # CommandRunner seam: SubprocessRunner (real) + FakeCommandRunner
  phases/       # discovery, spec, plan, execute, verify (server-side TDD check)
  skills/       # bundled Markdown skills, injected into subagent prompts
run_server.py   # bulletproof local launcher
skill-shim/     # optional Claude Code auto-trigger skill