Cpfs Mcp

Return CPFS Runner MCP status: package version, native core version, free-tier cap, active feature, entitlement.

Takes no parameters.

List jobs that need work: IDLE (NEW) and FAILED (KEEP WORKING), with the recommended next slug. Same queue model as the extension. Does not invent tasks from chat — only existing feature logs.

Takes no parameters.

List every feature log in the active history (All-logs/<active>/) with its derived lifecycle status (IN_PROGRESS / PASSED / FAILED / SUSPENDED / CLOSED / unknown) and the active marker. Use this to choose which feature to resume with cpfs_continue_feature — the MCP server does not auto-pick an active feature by file mtime. Use cpfs_list_histories / cpfs_use_history to switch which history is active.

Takes no parameters.

Scan a file or folder for CPFS §13 heuristic signals (numeric thresholds, path literals, semantic regex, workaround comments). Returns findings with file/line/signal/detail.

Re-run a prior task's frozen RETEST / RETEST-COMPLETE recipe and store the still-passing verdict in .cpfs/retest_results.json (extension retestTask parity).

Acknowledge a pending ### AI EXHAUSTED escalation so Pass can proceed. Pick/choose the next path (required for owner gate).

Validate-equivalent heuristic exposure: scan the feature TARGET FILES (or a workspace sample), write .cpfs/heuristic_last_review.json, and stamp the project log.

Check whether files the AI touched (or staged git files) are inside the active feature's TARGET FILES. Returns in-scope vs out-of-scope. In MCP there is no editor to block edits, so scope is enforced at commit time by the git pre-commit hook — this tool is the in-conversation check.

Scan the project log for pass-claim stamps (e.g. STATUS: SUCCESS) in the current attempt that are NOT backed by REAL TEST EVIDENCE with an on-disk artifact. Same WASM logic as the Cursor stop-hook chat-claim guard.

Start a CPFS feature: name it, set TARGET FILES, and define success criteria. Creates a feature log in the active history (All-logs/<active>/).

Return the active feature log (or a named one) as text.

Append workspace-relative paths to the feature log TARGET FILES line (no duplicates). Refreshes AI context on success. Parity with the Runner Manage target files panel and Add File to TARGET FILES.

Remove paths from the feature log TARGET FILES line. Refreshes AI context on success. Parity with Runner Manage target files → Remove selected.

Regenerate the active CPFS rule (FEATURE / TARGET FILES / DO NOT REPEAT / REAL TEST BEFORE PASS / NO FALSE COMPLETION / checksum) and write it to the connected AI client's auto-read rules file (e.g. .cursor/rules/cpfs-active.mdc in Cursor, CLAUDE.md+AGENTS.md in Claude, .windsurfrules in Windsurf). Only the current client's file(s) are written — set CPFS_CLIENTS env to override. Call this after starting a feature or ending an attempt so the AI sees fresh context on every turn.

Open a new attempt on an existing feature (e.g. after a failed attempt or owner reopen). Appends a new ATTEMPT #N block to the feature log.

Record a real-test-evidence line for the current attempt (e.g. 'ran the endpoint, got 200 + dashboard loaded | artifact: logs/verify/x.txt'). This is what the gated Pass later looks for — record it as you verify, so cpfs_end_attempt_success can pass.

Agree the VERIFY BY section of the active feature log (flip Status: pending → agreed, set the Method). This is the MCP equivalent of the owner confirming the verify method in chat. Once agreed, the gated Pass can succeed. Call this once per feature after you and the AI agree how success will be tested.

Add a line to the DO NOT REPEAT section of the active feature log, so the AI never retries a known-failed approach. Refreshes the injected rule immediately.

Close the current attempt as FAILED (owner reject). action: 'retry' opens a new attempt, 'suspend' pauses the feature, 'close' ends it. Refreshes the injected rule.

Close the active attempt as PASSED. GATED by the real engine: refuses if (a) free-tier is exhausted, (b) VERIFY BY is not agreed, or (c) there is no real-test evidence. Returns the gate verdict — do not claim 'done' to the user until this tool returns allowed=true.

Enter a CPFS Pro license key. Verified offline by the compiled WASM core (ed25519). Removes the free-tier limit.

Opt in to or out of anonymous CPFS telemetry. Default is OFF. Reversible at any time. When ON, sends only an anonymous startup ping (feature count, native core version, free-tier usage) — never source code, file paths, or prompts.

List all CPFS job-history files registered in repo-root historys.json, with which one is active for MCP and which for the extension. On startup with no active history chosen, call this to pick one.

Takes no parameters.

Switch the active job-history for the MCP server. All subsequent task reads/writes go to All-logs/<name>/. Does not affect the extension's chosen history.

Create a new job-history (a new All-logs/<name>/ folder + empty materialized index) and optionally set it as the active history for MCP and/or the extension. Does not copy existing logs — use the migration script for that.

Report which job-history is active for MCP and the extension, and where its logs/index live.

Takes no parameters.

Write the CPFS protocol block into every supported IDE's native rules file (.windsurfrules, CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) so an MCP-connected AI in any IDE follows CPFS from rules + MCP tools even without agent-lifecycle hooks. Idempotent — call when a rules file is missing or after CPFS is enabled. Returns per-IDE status.

Takes no parameters.

Enable CPFS for this workspace: scaffold .cpfs/, config, onboarding, zone map, git hook, and the mandatory .cursor/rules/cpfs-mandatory.mdc rule. Idempotent. Parity with the extension's enableWorkspace command.

Takes no parameters.

Write the mandatory CPFS policy rule to .cursor/rules/cpfs-mandatory.mdc (always-applied). Returns true if freshly created. Idempotent.

Takes no parameters.

Dismiss ALL pending out-of-scope edits for a feature so the gated Pass is no longer soft-blocked by them. Clears the MCP scope-watcher pending store for that slug AND marks the extension edit-history entries skipped (extension dismissPendingScopeEdits parity). Use after the owner decides the out-of-scope writes are acceptable but does not want to Keep/Revert each one.

DEV ONLY: set the free-tier completion counter in .cpfs/config-mcp.json (0..cap). Useful for testing free-tier exhaustion/restore behavior. No effect when a Pro license is installed.

Remove the stored CPFS Pro license key. The workspace falls back to free-tier rules. Reversible by re-entering a key via cpfs_enter_license.

Takes no parameters.

Show the current license/entitlement status: mode (full/free-enforced/free-exhausted), licensed flag, license payload (seat/email/exp) if any, and free-tier usage. Parity with the extension's showLicenseStatus.

Takes no parameters.

Re-fetch the latest valid CPFS Pro license key for an email from the CPFS license server and store it (renewal that feels like the same key got extended). The server always returns a freshly-signed key for that email; it is verified locally before storing. Default server: https://ragbox.llc.

Set the reference-images directory (relative path from workspace root) used for verify captures and owner context screenshots. Stored in .cpfs/config-mcp.json as referenceImagesPath.

Report the reference-images directory: resolved path, whether it exists, image count, and the newest images. The extension opens the folder in the OS; the MCP server has no OS opener, so it returns the listing instead.

Takes no parameters.

Enable or disable the post-edit lint hook. When enabled, the configured lint command runs after AI edits and surfaces hints. Stored in .cpfs/config-mcp.json as lintEnabled.

Set the lint command run after AI edits (e.g. 'npx eslint --fix {file}'). The {file} token is replaced with the edited file path. Stored in .cpfs/config-mcp.json as lintCommand.

Enable or disable attempt checkpoints (git snapshots taken at attempt start). When disabled, no checkpoint is created on attempt open. Stored in .cpfs/config-mcp.json as checkpointEnabled.

Enable or disable auto-restoring the attempt checkpoint when a test fails. When enabled, a failed validateAttempt restores files to the checkpoint before retrying. Stored in .cpfs/config-mcp.json as checkpointAutoRestoreOnTestFail.

Return the URL of the CPFS MCP localhost dashboard (human review surface for scope Keep/Revert, Pass, Fail, escalation acknowledge, and reports). Open it in a browser.

Takes no parameters.

Enable or disable CPFS enforcement for this workspace (writes the 'enabled' flag in .cpfs/config-mcp.json). When disabled, the MCP tools still run but report CPFS as off. Reversible.

Director/owner Pass: confirm a feature attempt as PASSED without requiring AI real-test evidence (the owner tested and confirmed). Parity with the dashboard's ownerPass / ownerPassNoArtifact. Still respects free-tier exhaustion and escalation gates.

Run the configured test command (testCommand in .cpfs/config-mcp.json) for the active feature attempt and append a VALIDATION block to the log. Returns pass/fail, exit code, and output tail. Respects the soft-block (pending out-of-scope edits) gate. Parity with the extension's validateAttempt command (the vscode modal is replaced by a structured block reason).

Run every agreed command/file outcome row from the active feature's VERIFY BY section, append an OUTCOME RESULTS block to the log, and return the rollup summary. Matches the extension's runAllChecks (automated outcome checks only — heuristic and scope are separate tools). Respects the acceptance gate and soft-block.

Restore files to the active attempt's checkpoint (a git stash ref captured at attempt start). With no files arg, restores every file changed since the checkpoint. Returns restored/failed lists. Parity with the extension's restoreAttemptCheckpoint command.

Write a self-contained HTML development report for a feature (summary, attempt timeline, success criteria, verify-by, DO NOT REPEAT, weekly activity) to <logs-dir>/<slug>-report.html and return the path. Parity with the extension's exportReport command (the save dialog is replaced by a deterministic path).

Set which development zone IDs are active for this workspace (stored as activeZones in .cpfs/config-mcp.json). The active zones determine the default TARGET FILES for new features. Returns the zone summary. Parity with the extension's manageActiveZones command (quick-pick → MCP args).

Add an explicit file path to one or more development zones in the zone map. Persists the updated zone map. Parity with the extension's addFileToZone command.

Remove an explicit file path from a development zone in the zone map. Persists the updated zone map. Parity with the extension's removeFileFromZone command.

Run the configured lint command on a single file and return pass/fail + output tail. Respects the lintEnabled flag and lintCommand in .cpfs/config-mcp.json. Parity with the extension's post-edit lint hook (exposed here as an on-demand tool).

Set the test command run by cpfs_validate_attempt (e.g. 'npm test' or 'node scripts/smoke.cjs'). Stored in .cpfs/config-mcp.json as testCommand. Parity with the extension's testCommand setting.

Mark outcome rows in ### OUTCOME ACCEPTANCE as ✓ accepted (or ✗ rejected with a note). The WASM acceptance gate blocks cpfs_run_all_checks until every row is ✓ accepted, so this is the gate's key. Parity with the extension's dashboard ✓ accept button. Default: accept all pending rows.

Generate (or regenerate) an ONBOARDING.md onboarding document for the workspace by scanning the repo structure, services, handoffs, and CPFS zones. Writes the file and returns the report + an AI fill prompt. Parity with the extension's generateOnboarding command.

Verify the onboarding document (checks required sections, handoff coverage, dir mentions) and return a formatted report. Does not modify the file. Parity with the extension's verifyOnboarding command.

Approve the onboarding document: stamp the approved frontmatter (approved: true, approved_at: today), write it back, then verify and report onboarding status. Parity with the extension's approveOnboarding command.

Re-audit the onboarding document: run auditOnboarding (updates frontmatter audited_at/audited_commit/watch_paths) and assess staleness. Scaffolds a minimal onboarding file if none exists. Returns the audit report + staleness assessment. Parity with the extension's reauditOnboarding command.

Attach an existing onboarding file (relative path) as the workspace's onboarding document. Stores it in .cpfs/config-mcp.json (onboarding.path + legacy onboardingPath). Parity with the extension's attachOnboarding command (file picker → MCP arg).

Mark the onboarding document's source as 'ai_audit' (created by AI audit) in .cpfs/config-mcp.json. Used after cpfs_generate_onboarding / cpfs_reaudit_onboarding so the dashboard shows the correct source label. Reversible by attaching a user file.

Takes no parameters.

Return the onboarding document path and its contents (the extension opens the file in the editor; the MCP server has no editor, so it returns the content instead). Reports missing-file when no onboarding is configured.

Takes no parameters.

Start a CPFS formal feature (Type 3): write a structured-test draft to .cpfs/formal_feature_draft.md and return the AI review prompt + the dashboard Formal Feature form URL. The draft is the shared workspace between the AI (chat) and the human (dashboard form). Optional tests JSON pre-fills structured tests (AI-draft fast path); the human reviews/edits in the dashboard before the feature log is created. Parity with the extension's formal feature form (webview → dashboard page).

Upgrade an existing Type 2 (non-formal) feature to Type 3 (formal): read its log, build a pre-filled formal-feature draft from it (feature name, target files, problem reconstructed from the opening request + success criteria), write the draft, and return the review prompt + dashboard form URL. The developer then fills in the structured tests / reference image in the dashboard. Parity with the extension's 'Upgrade to Type 3' button.

Open the dashboard Formal Feature form to edit the structured-test criteria of the current formal feature draft (.cpfs/formal_feature_draft.md). Returns the dashboard form URL. If no draft exists, instruct to call cpfs_start_formal_feature or cpfs_upgrade_to_type3 first. Parity with the extension's formal feature form (the webview is replaced by the dashboard page).

Takes no parameters.

Analyze legacy crossings (blast radius) for a passed CPFS task: detect pre-existing symbols the task modified, resolve their non-CPFS callers via a standalone language server (C-LSP — selected by file extension, auto-installed for npm-based servers), and scaffold one coverage task log. Falls back to symbol-existence-only ('basic blast-radius detection') when no language server is available. Returns the report + the dashboard blast-radius URL. Parity with the extension's analyzeLegacyCrossings command (vscode-coupled LSP → standalone-server LSP).