PreCode MCP

Local loop for specs. It gives your coding agent one task at a time, checks the work against the plan, and keeps a plain-English ledger of what passed, what drifted, and what still needs you.

Published as @precode/mcp. Free to use from the public npm registry. Works with any spec format; optimized when paired with PreCode docs. No PreCode account required.

Quick start

Open the repo you are building in (or add a plain `SPEC.md` at the root).
Install globally: `npm i -g @precode/mcp` then point your host at `precode-mcp` (recommended; quiet `npx` fallback is in the host guide).
New to the loop? Have your agent call `precode.help` — it returns the full workflow and `checks.json` schema in one read. `precode.version` reports the exact build.
For a plain spec, put your real build/test commands in `.precode/checks.json` so the gate can run them (`adopt_spec` writes a starter; PreCode exports already include it plus the package manifest).
Run the `precode_build` prompt, or say: build this with the precode loop.

Connect in your agent

MCP is a local stdio bridge: your agent spawns precode-mcp, which reads .precode/ from your repo. Install once, pick your host, paste config, restart — then run precode_build.

1. Install

npm i -g @precode/mcp

2. Configure

Pick your agent · paste its config

3. Restart

Quit the app fully, then reopen

Step 1 · Install once

$ npm i -g @precode/mcp

MCP hosts spawn precode-mcp — you do not run that in your terminal.

Runs locally over stdio. Reads `.precode/` from your repo — nothing is uploaded to PreCode.

Choose your agent

Config file

.cursor/mcp.json

Project-level · or ~/.cursor/mcp.json for all projects

Cursor docs →

1.Settings → Tools & MCP → add stdio server, or create the file below
2.Paste the JSON · save
3.Quit Cursor fully (Cmd+Q) and reopen

Paste this · .cursor/mcp.json

{
  "mcpServers": {
    "precode": {
      "command": "precode-mcp",
      "env": {
        "PRECODE_TELEMETRY_DISABLED": "1"
      }
    }
  }
}

Verify · Tools & MCP shows precode (green) · in Agent, call precode.get_goal

Troubleshooting & npx fallback

·spawn ENOENT? Use the full binary path (e.g. /opt/homebrew/bin/precode-mcp) or the quiet npx fallback.
·Set PRECODE_ROOT to your repo path if the MCP host does not open the project root.
·After a crashed verify: PRECODE_LOCK_STALE_MS=10000 recovers stale locks in 10s.

Quiet npx fallback — only if global install is impossible. Never use bare npx without --silent.

{
  "mcpServers": {
    "precode": {
      "command": "npx",
      "args": ["-y", "--silent", "@precode/mcp"],
      "env": {
        "PRECODE_TELEMETRY_DISABLED": "1",
        "NPM_CONFIG_LOGLEVEL": "silent",
        "npm_config_update_notifier": "false"
      }
    }
  }
}

Keep the build honest

Your agent writes the code. The MCP decides what passed — not the agent.

Real commands run

On precode.verify, the MCP runs the commands in .precode/checks.json. Exit code 0 closes the task. A self-reported “it passed” never can.

Failures stay open

Failed checks return fix hints. The task stays open until the commands actually pass.

Three strikes → you

After 3 failures on one task, the loop writes .precode/progress/TODO_FOR_YOU.md instead of silently passing.

Can't run here? Defer

Needs a secret, deploy, or paid API? precode.defer_task records why and surfaces it in TODO_FOR_YOU.md.

Configure your checks

Put your real build and test commands in `.precode/checks.json`. That's the gate.

auto checks

Run from your repo root on every verify. Task closes only when exit code is 0.

manual checks

For things only you can do — deploy, review, click-through. Mark kind: "manual". Never auto-passed; routed to TODO_FOR_YOU.md.

adopt_spec helps

Detects package.json, Cargo.toml, go.mod scripts and writes starters. Empty placeholder holds the task until you fill it, mark manual, or defer.

You control what runs

Only commands in your repo's checks.json execute — same trust as the agent building your code. Changes show up in your diff.

More detail

·Optional expect: require a substring or /regex/ in combined stdout+stderr.
·timeoutMs caps how long a check can run.
·Output usually ends with a trailing newline — prefer a substring or "/^alpha\n?$/" over hard-anchored "/^alpha$/".

Works with any spec

Works with any spec format; optimized for PreCode documentation packages.

PreCode export

.precode/ already includes docs, tasks, acceptance criteria, and progress files. Connect and go.

Plain spec

Have SPEC.md, .specify, .spec-workflow, or a docs folder? Call precode.adopt_spec to map it into .precode/ and start the loop.

Privacy and safety

Everything runs on your machine. Nothing leaves your repo unless you opt in.

Local only

Stdio bridge on your machine. Specs and file contents are never uploaded to PreCode servers.

Telemetry off by default

Enabled only if you set PRECODE_TELEMETRY_URL. Sends event names and counts — no spec text, files, secrets, or task content. Set PRECODE_TELEMETRY_DISABLED=1 to force off.

Tools

Tool	Does
precode.help	Full self-contained usage guide: the loop and the checks.json schema.
precode.version	Report the exact loaded server version.
precode.get_goal	Re-anchor on the goal and task progress.
precode.status	Read-only snapshot of tasks, checks, and deferred work.
precode.next_task	Pull the next open step plus acceptance criteria.
precode.next_phase	Alias for precode.next_task.
precode.verify	Runs checks.json checks and closes a task only on real pass/manual gate.
precode.verify_phase	Run a phase's checks once all its tasks are done (phased specs).
precode.defer_task	Defer work that cannot be verified in this environment.
precode.record_implementation	Append to .precode/progress/IMPLEMENTATION.md.
precode.finalize	Write TODO_FOR_YOU.md with your remaining steps.
precode.adopt_spec	Map a non-PreCode spec into .precode/.

Resources

Resources are not hosted on PreCode servers. The MCP reads them from your local .precode/ folder at build time.

URI	Contains
precode://goal	Goal and task progress.
precode://docs	Bundled .precode/docs/*.md specs.
precode://tasks	Current phased task plan.
precode://acceptance	Acceptance criteria and self-checks.
precode://progress	Implementation ledger and human TODOs.
precode://help	Full workflow guide and checks.json schema.
precode://version	The exact server version string.

Support and issues

For MCP bugs, install questions, or adoption issues, email support@useprecode.com.

Include your MCP host (Cursor, Claude Code, Claude Desktop, Codex CLI, VS Code, Windsurf, Antigravity), Node version, and a short description of what you expected versus what happened.