@precode/mcp

Open, agent-agnostic MCP server that turns a spec into a self-correcting, verified build. Works with any spec (SPEC.md, .specify, .spec-workflow) and best with a PreCode .precode/ package. Runs locally on your agent and your tokens.

Install: @precode/mcp on npm. Docs: useprecode.vercel.app/mcp.

It fixes the loop/goal failure other spec MCPs ship with:

• Goal re-anchoring — the agent re-reads the goal every phase, so long builds don't drift.
• Hard definition-of-done — when you declare checks in .precode/checks.json, the MCP runs them itself and the verdict comes from the real exit codes. A fabricated "it passed" cannot move a task to done.
• Closed verify → fix → re-verify — gaps come back with fixes and the loop will not advance past them.
• Honest escapes — a check that genuinely can't pass here (needs a secret, a deploy, a paid service) is precode.defer_task'd with a reason and surfaced in TODO_FOR_YOU.md, never silently skipped.

At the end it writes an IMPLEMENTATION.md (what was built) and a TODO_FOR_YOU.md (what you still need to do — secrets, env, deploy).

Install

Runs over stdio. Point any MCP host at it.

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "precode": { "command": "npx", "args": ["-y", "@precode/mcp"] }
  }
}

Claude Code:

claude mcp add precode -- npx -y @precode/mcp

Codex / Antigravity / VS Code — add the same command: npx, args: ["-y", "@precode/mcp"] to their MCP config.

The server reads .precode/ from the directory the host runs it in (PRECODE_ROOT overrides). Local stdio only — the build loop needs your filesystem.

Telemetry

Telemetry is off unless PRECODE_TELEMETRY_URL is set. When enabled, the server sends privacy-safe beta events such as mcp_next_task, mcp_verify_pass, and mcp_finalize; it hashes the local root path and never sends spec contents, file contents, secrets, or task text. Set PRECODE_TELEMETRY_DISABLED=1 to force-disable it.

Use

1. Drop a PreCode export (or run precode.adopt_spec on your own SPEC.md).
2. Run the precode_build prompt, or just tell your agent: "build this with the precode loop."

Local Verification

npm run test:stdio

The smoke test launches the built MCP server over stdio, verifies the tool list, confirms failed checks keep a task open, confirms passing checks mark it done, reads precode://docs, and writes the final TODO_FOR_YOU.md.

Tools

Checks — the executable done-gate

Declare checks in .precode/checks.json. Each auto check is run by the MCP from the project root on every precode.verify; the task closes only when its real exit code is 0.

{
  "checks": [
    { "id": "typecheck", "name": "Type-check", "kind": "auto", "cmd": "npm run typecheck" },
    { "id": "build", "name": "Build", "kind": "auto", "cmd": "npm run build" },
    { "id": "test", "name": "Tests", "kind": "auto", "cmd": "npm test", "expect": "/\\d+ passing/" },
    { "id": "deploy-task-3", "name": "Smoke route /health", "kind": "auto", "cmd": "curl -fsS localhost:3000/health", "taskIndex": 3 },
    { "id": "secrets", "name": "Prod secrets set in real accounts", "kind": "manual" }
  ]
}

• kind: "auto" — executed; pass = exit 0 (and expect substring//regex/ matches output if set). Optional timeoutMs (default 120s).
• kind: "manual" — never auto-passed; surfaced as a human gate in TODO_FOR_YOU.md.
• taskIndex — scope a check to one task; omit for a global check that runs on every task.
• No auto check for a task? verify falls back to your self-reported results but stamps the pass UNVERIFIED, so it's never mistaken for a machine-verified one.

Security: the runner only executes commands you put in your own repo's checks.json — the same trust level as the agent already running your build. Commands run with a timeout and captured output. Because checks.json lives in your repo, gate tampering shows up in your diff.

Resources

Release

Tagged releases publish to npm via GitHub Actions. See RELEASE.md.