forge-mcp

The director of the forge pipeline. An MCP server that tells Claude Code which phase to run next and what it must produce, then validates the evidence before letting the flow advance. Claude is the executor — forge never runs the work itself. It directs, you build.

🇪🇸 Léelo en español

The idea

A long piece of work — design a feature, build it, test it, ship it — is easy to do out of order, skip a step of, or declare "done" without proof. forge turns that flow into a pipeline of phases that can only advance in order, and only when each phase hands back real evidence.

• forge says which phase is next and exactly what it expects from it (the full criteria, not a summary).

• You (Claude) execute the phase — reading code, writing it, running tests, asking the user when a decision is theirs.

• You report the phase done with evidence; forge validates it and advances.

• You cannot skip a phase, cannot close one with empty or fake evidence, and cannot finish before every phase is closed.

The state lives in SQLite (node:sqlite, a Node built-in — no native build step), so a run resumes in any session: Claude's context does not survive a close, a compaction or picking up the next day — the flow's state does.

Related MCP server: Vibe-Coder MCP Server

The 13 phases

classify → clarify → setup → precondition → design → plan → build
        → gates → qa → reconcile → contraste → reflect → deliver

Each phase carries a goal (short instruction), a full systemPrompt (the complete criteria for that phase), the skills to load before running it, and flags for whether it needs the user or is optional. All defined in src/phases.ts.

Evidence is validated, not trusted

forge does not accept "done" as a string. forge_complete_phase validates the evidence each phase must hand back, and rejects the close if it does not hold up:

• gates requires the real exit codes (lint / build / test) and they must all be 0.

• qa requires a structured result: it passed, and it was actually attacked.

• clarify (a user decision) requires an explicit userConfirmed.

• An optional phase can only be skipped with a stated reason.

So a phase cannot be closed with an invented summary. The pipeline advances on proof.

The skills library (128)

src/skills.ts + the skills/ folder ship 128 skills, each with its own SKILL.md, versioned in the repo (forge is self-contained — it does not depend on anything external for these). Each phase declares which skills it loads; the domain map (SKILL_MAP) says which skills belong to which domain. Skills load on demand — Claude asks for the list with forge_skills and the content of a specific one with forge_skill(name), never all at once.

The 7 tools

Install

git clone https://github.com/DevRik99/forge-mcp
cd forge-mcp
npm install
npm run build

Register it in Claude Code (.mcp.json or project config):

{ "mcpServers": { "forge": { "command": "node", "args": ["dist/server.js"] } } }

Requires Node ≥ 22.5 (for node:sqlite).

How a run resumes

The state lives in a single global SQLite DB at ~/.forge/forge-mcp.db (override with FORGE_MCP_DB), so every project shares one store and runs are told apart by their cwd. Two tables:

• runs: one row per run (id, request, cwd, current_phase, status, timestamps).

• phase_artifacts: one row per closed phase (run_id, phase, summary, closed_at) — the real decision/artifact Claude reported, not just a boolean flag.

After a lost session (close, compaction, next day), any new Claude session with this MCP connected can:

1. Call forge_tasks() to see which runs are still active and in what phase.

2. Call forge_next(runId) to get the current phase's full systemPrompt again — Claude does not need to remember anything; forge hands it back verbatim.

3. Read the closed phases' artifacts via forge_status so nothing already decided (e.g. in clarify) is re-asked.

Guarantees (and honest limits)

forge enforces: the phase order, closing every phase before finishing, and validated evidence per phase (no fake gates/qa, no skipping user decisions or optional phases without a reason). Under concurrency, closing a phase is atomic — a stale double-close is rejected, not silently applied.

forge cannot stop you from editing the project without using it at all — an MCP only sees its own tools, not your Edit/Write/Bash. To force every change through the pipeline, pair it with the forge-flow gate from claude-gates, which blocks edits when no forge run is active.

License

MIT.