mcp-phase-gate

An MCP server that turns any AI coding agent into a gated, auditable, batch-by-batch engineering workflow.

This is the main README, in English · Read it in Spanish.

Problem: an AI coding agent jumps straight to code, makes decisions nobody asked it to make, and its reasoning dies with the chat. Solution: five phases with a gate between them, each one leaving a document on disk; in phase 4 the server itself writes each batch's receipt after checking the commit against git. See it: the live demo is the Studio on example data, read-only, in English and Spanish; it hangs off the project site.

Try it in 10 seconds

npx mcp-phase-gate ui --demo

It opens the Studio in your browser on a demo generated in a temporary folder (three projects, real git commits); it doesn't touch your documentation. --idioma en or --idioma es picks the demo's language; without it, PHASE_GATE_LANG or the system's decides.

---

An MCP (Model Context Protocol) server that splits every incoming requirement into five gated phases, and forces each one to leave a written document behind before the next can start. Your client's panel will show it as mcp-phase-gate.

How it works

Ask an AI assistant to implement a requirement and it starts writing code. It breaks something it never read, quietly makes decisions it never asked you about, and when you switch chats or sit down at your other machine, the whole reasoning is gone: it lived in the conversation, and conversations don't travel.

Here the assistant doesn't touch code until phase 4. By then it has diagnosed the problem by reading the repository, asked you what it couldn't decide alone, and written a plan checked against the real code. Every phase leaves a document in a central folder, so the thinking outlives both the chat and the device.

It starts from a requirement (an email, a ticket) and goes through five phases, in this order, each leaving its document:

1. Discovery reads the code and diagnoses. It leaves 01 · Technical Analysis.
2. Decisions asks, validates, and stops. It leaves 02 · Decisions.
3. Technical Plan turns decisions into exact code. It leaves 03 · Technical Plan.
4. Execution implements and verifies by running. It leaves 04 · Execution.
5. Audit reviews as an outside reviewer. It leaves 05 · Audit, and its output is the PR description, also in the chat.

The mandatory stop is phase 2: it halts there and will not move on until you answer, and whatever you decide gets written down with its rationale. Between one phase and the next there is a gate, which is what gives the server its name: ask for a phase while skipping the previous one and the server notices and warns you (more).

In phase 4 the AI commits each batch only with your OK (the default policy; a project can choose another) and never pushes or opens the PR, under any policy. Each batch's receipt is written by the server, which checks against git that its commit exists and is on the branch (how). In phase 5 it only reads. The flow adapts to the kind of work through presets (code with or without tests, several repositories, maintaining an AI agent, research), and everything works in English and Spanish.

Who it's for

For people working on code that already exists and must not break, who need a record of why each thing was done. It fits especially well if you work from more than one machine, or if you have to justify decisions weeks later. It is not for throwaway prototypes or greenfield projects: five phases to change a colour is absurd ceremony. It speaks standard MCP, so it works with any compatible client. The phase commands were checked on Cursor and Claude Code. On VS Code the server starts, and /f1…/f5 do not appear in the / menu; the installation guide has what each client showed.

Architecture

The server talks to the client over stdio and keeps almost no state of its own: the phase of a task is deduced from the documents on disk, the prompt is assembled from its layers on every call, and git is queried through one read-only door. The Central Documentation is a plain folder you own, synced or not; the server only writes inside task folders, and receipts only through record_batch. The Studio is a separate process, loaded only by ui, with a local HTTP API and live events over the same functions the tools use. Every design choice is recorded with its reason in docs/decisiones.md (in Spanish), and the diagram is in CONTRIBUTING.

This is the beginning of the README. Read the rest at the original. Read the full README ↗