cpfs-mcp — CPFS Runner as an MCP server

The same CPFS Runner guardrail engine (compiled Rust → WASM core) that powers the VS Code / Cursor extension, exposed as an MCP server. No editor required — works in any MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, Zed, Continue, Cline, Roo, GitHub Copilot.

The engine is shared, not forked. Customer installs load the compiled WASM core and closed node-safe modules from bundled cpfs-mcp/runtime/ (synced from the extension build). Monorepo dogfood can fall back to sibling cpfs-runner/dist. One implementation, two hosts — no product TypeScript in the npm tarball.

One subscription unlocks both the CPFS Runner extension (Cursor/VS Code) and the cpfs-mcp server (any MCP client). Use whichever surface fits the task — no double billing. But only one runtime may be active in a given workspace at any time. If the extension is enabled in a workspace, the MCP server refuses to start (and tells you to disable the extension first); if the MCP server is running in a workspace, the extension refuses to enable (and tells you to stop the MCP server first). This is per-workspace, so the MCP server in a different workspace (e.g., Claude Desktop elsewhere) does not conflict with the extension here. Stale locks from a crashed runtime are auto-cleaned.

What you get

• Heuristic scan (cpfs_check_heuristics) — the §13 detector that flags numeric thresholds, path literals, semantic regex, and workaround comments. Same findings the extension shows.
• Feature lifecycle (cpfs_start_feature, cpfs_get_feature_log) — name a feature, set TARGET FILES, define success criteria, write the log under logs/development_history/.
• Auto-injected context (cpfs_refresh_ai_context) — regenerates the active rule (FEATURE / TARGET FILES / DO NOT REPEAT / REAL TEST BEFORE PASS / NO FALSE COMPLETION / checksum) and writes it to every AI client's auto-read rules file, so the AI sees fresh context on every turn — without editor hooks:
  • .cursor/rules/cpfs-active.mdc (Cursor — alwaysApply: true)
  • AGENTS.md (Claude Code, Zed, generic)
  • CLAUDE.md (Claude Code)
  • .clinerules (Cline) · .roorules (Roo) · .windsurfrules (Windsurf)
  • .github/copilot-instructions.md (Copilot) · CONVENTIONS.md (Aider)
• Gated Pass (cpfs_end_attempt_success) — the only way to mark a task done. Refuses if (a) free-tier is exhausted, (b) VERIFY BY is not agreed, or (c) there is no real-test evidence. The AI cannot bypass this — it's a server-side tool call, not chat text.
• License (cpfs_enter_license) — verified offline by the WASM core (ed25519).
• Status (cpfs_status) — native core version, free-tier cap/usage, active feature.
• Scope check (cpfs_check_scope) — are the files the AI touched inside TARGET FILES? The in-conversation check; the git pre-commit hook is the hard backstop.
• Telemetry (cpfs_set_telemetry) — opt in/out, default OFF, reversible. Anonymous startup ping only (feature count, core version, free-tier usage) — never source, paths, or prompts.

Dashboard (the director's view)

The MCP server runs an embedded localhost HTTP server serving the real CPFS cockpit (renderCockpit from the closed runtime) — the same surface the extension shows, fed with live data from your feature logs. Open it in any browser:

http://127.0.0.1:8765          # cockpit (live feature, target files, decision actions)
http://127.0.0.1:8765/heuristic  # §13 heuristic report across the workspace

Set CPFS_DASHBOARD_PORT=0 to disable.

Git pre-commit hook (editor-agnostic backstop)

Since MCP has no editor to block edits in, scope + §13 enforcement runs at commit time:

node src/install.js     # writes .git/hooks/pre-commit + prints client configs

The hook blocks a commit if staged files are outside the active feature's TARGET FILES, or if staged added lines trip a §13 heuristic signal. Override with CPFS_SCOPE_ALLOW=1 / CPFS_HEURISTIC_ALLOW=1 (e.g. git commit --no-verify bypasses entirely).

Install

Full step-by-step guide: see docs/INSTALL.md — covers every supported MCP client (Claude Desktop, Cursor, Windsurf, Zed, Cline, Roo, Continue, Copilot), verification, first task, and troubleshooting.

cd cpfs-mcp
npm install
npm run sync-runtime       # (monorepo) refresh runtime/ from cpfs-runner/dist
npm test                   # smoke + MCP + pack self-containment
# or: npm pack && npm install -g ./cpfs-mcp-*.tgz

Published / packed installs already include runtime/ (WASM + closed JS). You do not need a sibling cpfs-runner checkout.

WASM is mandatory. If required native files are missing or the install is corrupt, the MCP server exits immediately and tells the user to reinstall or contact the manufacturer. It does not continue in a degraded mode.

Configure your MCP client

Add cpfs-mcp as an MCP server. Set CPFS_WORKSPACE to the project root you want CPFS to supervise.

Claude Desktop / Claude Code (claude_desktop_config.json)

{
  "mcpServers": {
    "cpfs": {
      "command": "node",
      "args": ["/absolute/path/to/factai/cpfs-mcp/src/index.js"],
      "env": { "CPFS_WORKSPACE": "/absolute/path/to/your/project" }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "cpfs": {
      "command": "node",
      "args": ["/absolute/path/to/factai/cpfs-mcp/src/index.js"],
      "env": { "CPFS_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Windsurf / Continue / Zed / Cline / Roo

Same command/args/env shape — each client's MCP config file accepts the same server entry. See your client's "MCP servers" docs for the file location.

How enforcement maps from the extension

| Extension (Cursor) | MCP server | |---|---| | Editor hook refreshes rule before each message | File watcher keeps rules files fresh; client's own rules engine attaches them | | Chat-claim guard inspects AI reply text | Server-side gate on cpfs_end_attempt_success — the only path to "done" | | Webview dashboard | Embedded localhost HTTP server serving renderCockpit + Formal Feature + legacy-crossings pages | | Diff-tab scope alerts | Git pre-commit hook — editor-agnostic backstop | | Formal Feature webview (Type 3) | Dashboard /formal-feature criteria editor page (Phase 4) | | Legacy crossings (LSP via IDE) | cpfs_analyze_legacy_crossings drives standalone language servers over LSP (Phase 5) |

The transport changes; the effect is preserved. See ../marketing/cpfs-runner/MCP_SERVER_FEATURE_MAP.md for the full feature-by-feature analysis.

Status

v0.2 — extension feature parity (this commit):

• ✅ WASM core loads under plain Node (no editor)
• ✅ Heuristic scan returns real findings
• ✅ Rule generation + 8 client rules files written (auto-injection relocated)
• ✅ Success gate, real-test gate, free-tier gate all enforced server-side (proven: gated PASS succeeds only with agreed VERIFY BY + real-test evidence)
• ✅ Embedded dashboard HTTP server (renderCockpit + heuristic report) — interactive: Pass/Fail/Refresh buttons POST to /api/action and mutate the log via the same gated ops
• ✅ Git pre-commit hook (scope + §13 enforcement) + installer
• ✅ Telemetry opt-in (default OFF; send path implemented, fires only if CPFS_TELEMETRY_URL set)
• ✅ Full lifecycle proven end-to-end (start → agree verify → record evidence → gated pass → continue → fail → dashboard actions)
• ✅ Every test auto-saves its proof artifact to logs/verify/ with exit_code + sha256

MCP tools (extension parity)

Lifecycle & gating (v0.1): cpfs_status, cpfs_check_heuristics, cpfs_check_scope, cpfs_start_feature, cpfs_get_feature_log, cpfs_refresh_ai_context, cpfs_agree_verify, cpfs_record_evidence, cpfs_end_attempt_success (gated), cpfs_continue_feature, cpfs_fail_attempt, cpfs_add_do_not_repeat, cpfs_enter_license, cpfs_set_telemetry.

Phase 1 — thin wrappers: cpfs_enable_workspace, cpfs_install_mandatory_rule, cpfs_dismiss_pending_scope_edits, cpfs_dev_set_free_counter, cpfs_remove_license, cpfs_show_license_status, cpfs_refresh_license, cpfs_set_reference_images_dir, cpfs_open_reference_images_dir, cpfs_toggle_lint_enabled, cpfs_set_lint_command, cpfs_toggle_checkpoint_enabled, cpfs_toggle_checkpoint_auto_restore, cpfs_open_dashboard, cpfs_toggle_cpfs, cpfs_owner_pass.

Phase 2 — core enforcement: cpfs_validate_attempt, cpfs_run_all_checks, cpfs_restore_attempt_checkpoint, cpfs_export_report, cpfs_manage_active_zones, cpfs_add_file_to_zone, cpfs_remove_file_from_zone, cpfs_lint_file, cpfs_set_test_command, cpfs_accept_outcomes.

Phase 3 — onboarding suite: cpfs_generate_onboarding, cpfs_verify_onboarding, cpfs_approve_onboarding, cpfs_reaudit_onboarding, cpfs_attach_onboarding, cpfs_mark_onboarding_ai_audit, cpfs_open_onboarding.

Phase 4 — formal features (Type 3): cpfs_start_formal_feature, cpfs_upgrade_to_type3, cpfs_edit_criteria.

Phase 5 — legacy crossings (C-LSP): cpfs_analyze_legacy_crossings — drives standalone language servers (pyright, typescript-language-server, gopls, rust-analyzer, clangd) over LSP to resolve non-CPFS callers of a changed symbol; auto-installs npm-based servers, surfaces a one-line install hint for toolchain-based servers, and falls back to symbol-existence-only ("basic blast-radius detection") when no server is available.

Dashboard pages

http://127.0.0.1:8765/                       # cockpit (live feature, target files, decisions)
http://127.0.0.1:8765/heuristic              # §13 heuristic report across the workspace
http://127.0.0.1:8765/formal-feature          # Formal Feature (Type 3) criteria editor (Phase 4)
http://127.0.0.1:8765/legacy-crossings?slug=  # blast-radius report + coverage-task creation (Phase 5)

Run the tests: npm test (artifacts auto-saved to logs/verify/)

Remaining (user testing only): load cpfs-mcp into a real AI client (Claude Desktop / Cursor / etc.) via the config in node src/install.js and run a live task. The protocol, gates, dashboard, hook, and extension-parity tools are all proven; the last mile is a real client session.