manifestation-mcp

코딩 에이전트가 **설계 우선(design-first)**으로 동작하게 만드는 MCP 서버입니다. 무언가를 만들고 싶은 순간, 코드로 바로 뛰어들지 않고 한 걸음 물러서서 인터뷰를 하며, 스펙을 끌어내 **소화하기 쉬운 덩어리(chunk)**로 다시 보여줍니다. 그리고 사용자의 승인을 한 입 크기의 레드/그린 TDD 계획으로 바꾼 뒤, 서브에이전트 기반 개발 루프(구현자 → 검토자 → 품질 게이트)를 실행해 그 계획을 스스로 끝까지 진행하게 합니다.

이식 가능한 Python MCP 서버입니다. 서버가 두뇌(5단계 상태 머신 + 스펙/계획 + 스킬 라이브러리) 역할을 하고, 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의 editable-install 문제점에 견고함):

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 도구를 호출해 수동으로 시작하면 됩니다.

도구

프롬프트: /manifestation <brief>. 리소스: skills://all, skill://<name>.

모델 선택

날짜가 있는 특정 모델에 하드코딩된 것은 없습니다. 기본적으로 서버는 Claude Code CLI에 설정된 모델을 상속합니다. 전역적으로는 MANIFESTATION_MODEL 환경 변수(예: MANIFESTATION_MODEL=claude-opus-5)로 덮어쓰고, 코드에서는 AgentSDKClient(model=...)로 호출 단위로 다르게 지정할 수 있습니다.

안전 모델 (run 사용 전에 읽으세요)

run은 저장소에서 실제 서브에이전트를 실행하므로 신뢰 경계를 이해하세요:

• **구현자(implementer)**는 쓰기 권한과 Bash를 갖습니다. 이것은 대상 저장소에서 의도적으로 임의 코드를 실행하는 것이므로, 신뢰할 수 있는 저장소에서만 실행하고 신뢰할 수 없는 작업에는 컨테이너/VM을 사용하세요. 샌드박스는 없습니다.

• **검토자(reviewer)**와 **플래너(planner)**는 다음 두 가지 방식으로 읽기 전용입니다. SDK의 변형 도구가 disallowed_tools에 들어 있고, 또한 can_use_tool 권한 콜백이 허용 목록에 없는 모든 도구 — 우리가 열거하지 않은 도구(WebFetch, Task, MCP 도구)까지 포함 — 를 거부합니다.

• TDD는 텍스트로 신뢰하는 것이 아니라 서버 측에서 확인됩니다. 구현자가 실행된 후, 서버는 작업이 명시한 테스트 명령을 직접 실행합니다. 이 명령은 HEAD에서 성공해야 하며(실제 GREEN), 구현자의 테스트 전용 커밋(HEAD~1)을 대상으로 재실행하면 반드시 실패해야 합니다(실제 RED). 조작하거나 순서를 바꾼 증거는 잡아내며, git/테스트가 확인할 수 없을 때는 실패 처리합니다.

• 후속 발견 사항이 남은 채 PASS 판정이 나면 모순으로 처리되어 작업이 실패합니다.

• run은 승인된 플랜이 필요하고 각 단계마다 체크포인트를 남기며, 크래시 난 시도는 처음부터 다시 실행하지 않고 검토 단계부터 이어서 구현자 실행을 다시 하지 않으므로 편집이 중복되지 않습니다. 또한 **감사 추적(audit trail)**을 유지하며 항상 한도가 정해져 있습니다 — max_agent_calls / max_budget_usd(둘 다 MCP로 지정 가능) 또는 기본 내장 한도를 사용합니다.

• 변이(mutating) 도구 호출은 프로젝트별로 프로세스 내부 잠금과 프로세스 간 파일 잠금으로 직렬화됩니다.

• brief/답변/spec을 통한 프롬프트 주입은 여전히 서브에이전트 프롬프트로 흘러 들어갈 수 있습니다. 프로젝트 입력은 신뢰할 수 없는 것으로 취급하세요.

그것이 정직함을 지키는 방법(그리고 테스트 가능하게 하는 법)

모든 LLM 상호작용은 하나의 주입 가능한 접점(LLMClient)을 거쳐 갑니다. 단위 테스트에서는 FakeLLMClient를 주입하므로 상태 머신 전체 — 발견, 양식 작성, 계획 생성, 재시도와 검토 게이트가 있는 실행 루프까지 — 를 네트워크 호출 없이 검증합니다. 실제 AgentSDKClient는 그 접점 뒤에 있으며 기능을 선택한 라이브 스모크 테스트에서만 실행됩니다.

아키텍처

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