manifestation-mcp

An MCP server that makes a coding agent design-first. The moment you want to build something, it doesn't lunge into code — it steps back and interviews you, teases out a spec and shows it back in digestible chunks, turns your sign-off into a bite-sized red/green TDD plan, and then runs a subagent-driven development loop (implementer → reviewer → quality gate) that can grind through the plan on its own.

It's a portable Python MCP server: the server is the brain (a five-phase state machine + your spec/plan + a skills library) and it runs its own subagents internally via the Claude Agent SDK — so one run call can work autonomously for a long stretch without drifting from the plan.

The five phases

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

State lives as inspectable files in the target repo: <repo>/.manifestation/<project-id>/{state.json, spec.md, plan.md}.

Requirements

• Python 3.10+
• uv (brew install uv)
• For live execution (run): the Claude Code CLI on your PATH and Claude credentials (ANTHROPIC_API_KEY or an existing Claude Code login). The Agent SDK drives it to run the implementer/reviewer subagents.
• git in the target repo — the TDD gate uses git worktree to verify that a real failing test preceded the implementation.

Setup

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

Run it

Recommended local launcher (robust against uv's editable-install quirk):

uv run python run_server.py

Register it with Claude Code:

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

(For a packaged install via uvx/pipx, the manifestation-mcp console script works directly.)

Auto-trigger (optional)

Copy skill-shim/SKILL.md into your Claude Code skills (e.g. ~/.claude/skills/manifestation/SKILL.md). Its description fires on "build / implement / add a feature", so the workflow starts itself — you don't have to invoke anything. Without it, kick off manually with the /manifestation prompt or by calling the start_project tool.

The tools

Tool	What it does
start_project(brief, repo_path)	Create a project (validates the repo path); returns interview questions.
submit_answers(project_id, answers)	Feed answers; asks more or advances to SPEC.
next_spec_chunk(project_id)	Next digestible spec chunk to review (bounded in size).
review_spec_chunk(project_id, decision, feedback?)	approve / revise a chunk.
make_plan(project_id)	Generate the repo-aware TDD plan; returns full task bodies. Does not start execution.
approve_plan(project_id)	Record the user's sign-off and advance to EXECUTE.
run(project_id, until?, max_agent_calls?, max_budget_usd?)	Subagent-driven loop with a server-verified TDD gate; checkpoints per step; streams progress; reports agent_calls/cost_usd.
reset_task(project_id, task_id)	Unblock a BLOCKED task so run can retry it.
status(project_id) / list_projects()	Inspect progress (per-task attempts, findings, approval state).

Prompt: /manifestation <brief>. Resources: skills://all, skill://<name>.

Model selection

Nothing is hard-coded to a dated model. By default the server inherits the model the Claude Code CLI is configured with. Override globally with the MANIFESTATION_MODEL env var (e.g. MANIFESTATION_MODEL=claude-opus-5), or per-invocation in code via AgentSDKClient(model=...).

Safety model (read before using run)

run executes real subagents in your repo, so understand the trust boundary:

• The implementer gets write + Bash. That is arbitrary code execution in the target repo by design — run it only against repos you trust, and prefer a container/VM for untrusted work. There is no sandbox.
• The reviewer and planner are read-only two ways: mutating tools are in the SDK's disallowed_tools, and a can_use_tool permission callback denies every tool not on their allowlist — covering tools we didn't enumerate (WebFetch, Task, MCP tools). Safe even in an untrusted repo.
• TDD is verified server-side, not trusted from prose. After the implementer runs, the server runs the task's declared test command itself: it must pass at HEAD (real GREEN), and it must fail when re-run against the implementer's test-only commit (HEAD~1) in a throwaway git worktree (real RED). Fabricated or reordered evidence is caught; fail-closed if git/test can't confirm it.
• A PASS verdict with any trailing findings is treated as a contradiction and fails the task.
• run requires an approved plan, checkpoints after every step (and resumes a crashed attempt at the review step rather than re-running the implementer, so edits aren't duplicated), keeps a full audit trail, and is always bounded — max_agent_calls / max_budget_usd (both exposed via MCP), or a built-in default cap.
• Mutating tool calls are serialized per project by an in-process lock and a cross-process file lock.
• Prompt injection via the brief/answers/spec still flows into subagent prompts — treat project inputs as untrusted.

How it stays honest (and testable)

Every LLM interaction goes through one injectable seam (LLMClient). Unit tests inject a FakeLLMClient, so the whole state machine — discovery, spec chunking, plan generation, and the execute loop with its retries and review gates — is verified with zero network calls. The real AgentSDKClient sits behind that seam and is only exercised by the opt-in live smoke test.

Architecture

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