@precode/mcp 0.2.0 → 0.3.0

package/README.md

@@ -15,14 +15,28 @@ At the end it writes an **`IMPLEMENTATION.md`** (what was built) and a **`TODO_F
 
 ## Install
 
-Runs over stdio. Point any MCP host at it.
+Runs over stdio. Point any MCP host at `npx -y @precode/mcp`. Full per-host copy-paste configs: [useprecode.vercel.app/mcp](https://useprecode.vercel.app/mcp).
 
-**Cursor** — `.cursor/mcp.json`:
+| Host | Config location | How |
+|------|-----------------|-----|
+| **Cursor** | `.cursor/mcp.json` | JSON — see below |
+| **Claude Code** | `.mcp.json` (project) | `claude mcp add --env PRECODE_TELEMETRY_DISABLED=1 --transport stdio --scope project precode -- npx -y @precode/mcp` |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | JSON — same shape as Cursor |
+| **Codex CLI** | `~/.codex/config.toml` | `codex mcp add precode -- npx -y @precode/mcp` |
+| **VS Code** | `.vscode/mcp.json` | JSON — uses `"servers"` not `"mcpServers"` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | JSON — same shape as Cursor |
+| **Antigravity** | `~/.gemini/antigravity/mcp_config.json` | Agent panel → Manage MCP Servers → View raw config |
+
+**Cursor / Claude Desktop / Windsurf / Antigravity** — `mcpServers` JSON:
 
 ```json
 {
   "mcpServers": {
-    "precode": { "command": "npx", "args": ["-y", "@precode/mcp"] }
+    "precode": {
+      "command": "npx",
+      "args": ["-y", "@precode/mcp"],
+      "env": { "PRECODE_TELEMETRY_DISABLED": "1" }
+    }
   }
 }
 ```
@@ -30,10 +44,30 @@ Runs over stdio. Point any MCP host at it.
 **Claude Code:**
 
 ```bash
-claude mcp add precode -- npx -y @precode/mcp
+claude mcp add --env PRECODE_TELEMETRY_DISABLED=1 --transport stdio --scope project precode -- npx -y @precode/mcp
+```
+
+**Codex CLI:**
+
+```bash
+codex mcp add precode -- npx -y @precode/mcp
 ```
 
-**Codex / Antigravity / VS Code** — add the same `command: npx`, `args: ["-y", "@precode/mcp"]` to their MCP config.
+**VS Code** — note `"servers"` wrapper and optional `"cwd": "${workspaceFolder}"`:
+
+```json
+{
+  "servers": {
+    "precode": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@precode/mcp"],
+      "cwd": "${workspaceFolder}",
+      "env": { "PRECODE_TELEMETRY_DISABLED": "1" }
+    }
+  }
+}
+```
 
 The server reads `.precode/` from the directory the host runs it in (`PRECODE_ROOT` overrides). Local stdio only — the build loop needs your filesystem.
 
@@ -52,13 +86,14 @@ Telemetry is off unless `PRECODE_TELEMETRY_URL` is set. When enabled, the server
 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`.
+The smoke test launches the built MCP server over stdio, verifies the tool list, runs a real executable check, confirms a failing check (and a fabricated passing report) keep the task open, confirms the task closes only once the real check passes, reads `precode://docs`, and writes the final `TODO_FOR_YOU.md`. `npm test` runs the full edge-case suite (`test/run.mjs`).
 
 ## Tools
 
 | Tool | Does |
 |------|------|
 | `precode.get_goal` | Re-anchor on the goal + progress |
+| `precode.status` | Read-only snapshot of tasks, checks, and deferred work |
 | `precode.next_phase` | Alias for the next phased build step |
 | `precode.next_task` | Pull the next step + acceptance criteria |
 | `precode.verify` | **Runs** the task's `checks.json` checks; marks done only on real exit-0 |
@@ -84,9 +119,9 @@ Declare checks in `.precode/checks.json`. Each `auto` check is **run by the MCP*
 ```
 
 - `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`.
+- `kind: "manual"` — never auto-passed; surfaced as a human gate in `TODO_FOR_YOU.md` (a manual-only task closes with its gate routed to you).
 - `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.
+- **A task never closes on a self-reported pass.** Reported `checkResults` are advisory only. A check declared with an empty `cmd` is treated as unconfigured and **HOLDs** the task — wire a real command, mark it `manual`, or `precode.defer_task`. `adopt_spec` writes such placeholders on purpose so a fresh spec can't be "verified" until you point the gate at something real.
 
 **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.
 

package/dist/index.js

@@ -2,9 +2,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { createRequire } from "node:module";
 import { PrecodeStore, adoptSpec } from "./store.js";
 import { checkKind, runChecks } from "./checks.js";
 import { recordTelemetry, taskTelemetry } from "./telemetry.js";
+// Single source of truth for the version the handshake reports — read from
+// package.json so it can never drift from the published package again.
+const VERSION = createRequire(import.meta.url)("../package.json")
+    .version ?? "0.0.0";
 /**
  * @precode/mcp — drives a phased build → recheck → fix loop over a `.precode/`
  * package. Fixes the loop/goal failure other spec MCPs ship with:
@@ -22,7 +27,15 @@ function text(s) {
 }
 const NO_STORE = text("No `.precode/` package found in this directory. Either drop a PreCode export here, " +
     "or call `precode.adopt_spec` to map a plain SPEC.md / .specify / .spec-workflow folder into one.");
-const server = new McpServer({ name: "precode", version: "0.1.0" });
+const server = new McpServer({ name: "precode", version: VERSION }, {
+    instructions: "PreCode drives a spec → build → verify loop with a hard, SELF-EXECUTING done-gate. " +
+        "Flow: ensure a .precode/ package exists (precode.adopt_spec maps any SPEC.md / .specify / .spec-workflow). " +
+        "Then loop: precode.get_goal to anchor on the goal → precode.next_task → build ONLY that task → precode.verify. " +
+        "On verify the MCP itself RUNS the commands in .precode/checks.json; a task closes only on real exit-0, so self-reported results cannot fake a pass. " +
+        "A failing or unconfigured check keeps the task OPEN with concrete fixes. If a check genuinely cannot pass here (needs a secret/deploy/external service), call precode.defer_task with a reason. " +
+        "When every task is done, call precode.finalize. Call precode.status anytime for a read-only progress snapshot. " +
+        "Resources precode://goal, ://tasks, ://docs, ://acceptance, ://progress are re-readable each phase.",
+});
 // --- Tool: get the goal (anti-drift anchor) -------------------------------
 server.tool("precode.get_goal", "Re-read the project goal and progress. Call this at the start of every phase so the build does not drift from the spec.", {}, async () => {
     const s = await store();
@@ -31,6 +44,37 @@ server.tool("precode.get_goal", "Re-read the project goal and progress. Call thi
     await recordTelemetry({ eventName: "mcp_get_goal", root: ROOT });
     return text(await s.goal());
 });
+// --- Tool: status (read-only snapshot) ------------------------------------
+server.tool("precode.status", "Read-only snapshot of the build: task counts, the current open task, deferred tasks, and whether real checks are configured. Has no side effects — safe to call anytime.", {}, async () => {
+    const s = await store();
+    if (!s)
+        return NO_STORE;
+    const tasks = await s.tasks();
+    const deferred = await s.deferredEntries();
+    const deferredSet = new Set(deferred.map((e) => e.index));
+    const done = tasks.filter((t) => t.done).length;
+    const open = tasks.filter((t) => !t.done && !deferredSet.has(t.index));
+    const next = open[0];
+    const allChecks = await s.checks();
+    const autoConfigured = allChecks.filter((c) => checkKind(c) === "auto").length;
+    const placeholders = allChecks.filter((c) => checkKind(c) === "skip").length;
+    const manual = allChecks.filter((c) => checkKind(c) === "manual").length;
+    return text([
+        `Tasks: ${done}/${tasks.length} done, ${open.length} open, ${deferred.length} deferred.`,
+        next ? `Next open task: #${next.index} — ${next.text}` : "No open tasks — call precode.finalize.",
+        `Checks in checks.json: ${autoConfigured} auto (executed), ${manual} manual, ${placeholders} unconfigured placeholder(s).`,
+        placeholders > 0
+            ? "WARNING: placeholder checks have no command — tasks they apply to will HOLD until you set a real cmd, mark them manual, or defer."
+            : autoConfigured === 0 && manual === 0
+                ? "WARNING: no checks defined — add an auto check with a real cmd so the gate can verify."
+                : "Gate is backed by real executed checks.",
+        deferred.length
+            ? `Deferred: ${deferred.map((e) => `#${e.index} (${e.reason})`).join("; ")}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n"));
+});
 // --- Tool: next task ------------------------------------------------------
 server.tool("precode.next_task", "Pull the next unchecked build step plus the goal and acceptance criteria. Build ONLY this task, then call precode.verify. Do not skip ahead.", {}, async () => {
     const s = await store();
@@ -91,7 +135,7 @@ server.tool("precode.next_phase", "Alias for precode.next_task. Pulls the next p
     ].join("\n"));
 });
 // --- Tool: verify (the hard done-gate + fix loop) -------------------------
-server.tool("precode.verify", "Close the done-gate for the current task. If the project declares checks in .precode/checks.json, the MCP RUNS them itself and the verdict comes from real exit codes — your reported results cannot fake a pass. A task is marked done only when every auto check it runs passes. Otherwise the gaps come back and the task stays OPEN — fix and call precode.verify again.", {
+server.tool("precode.verify", "Close the done-gate for the current task. The MCP RUNS the task's auto checks from .precode/checks.json itself and the verdict comes from real exit codes — your reported results CANNOT fake a pass and never close a task on their own. A task is marked done only when every auto check passes (or it has only manual gates, which route to TODO). If a declared check has no command yet, or no check is defined, you get a HOLD telling you to wire a real command, mark it manual, or precode.defer_task. Fix and call precode.verify again.", {
     checkResults: z
         .array(z.object({
         name: z.string().describe("e.g. 'build', 'typecheck', 'lint', 'smoke test'"),
@@ -99,7 +143,7 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
         detail: z.string().optional(),
     }))
         .optional()
-        .describe("Optional supplementary notes about checks you ran. Authoritative only as a FALLBACK when checks.json defines no auto check for this task."),
+        .describe("ADVISORY ONLY. Never used to mark a task done — a task closes only when the MCP executes its checks.json checks and they pass (or via a manual gate / precode.defer_task)."),
     notes: z.string().optional(),
     task: z.string().optional().describe("Optional host-side task identifier or title."),
 }, async ({ checkResults, notes, task: taskLabel }) => {
@@ -116,6 +160,7 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
         const specs = await s.checksForTask(task.index);
         const autoSpecs = specs.filter((c) => checkKind(c) === "auto");
         const manualSpecs = specs.filter((c) => checkKind(c) === "manual");
+        const placeholderSpecs = specs.filter((c) => checkKind(c) === "skip");
         // Route manual checks to the human TODO when the task closes — never auto-passed.
         const routeManual = async () => {
             if (!manualSpecs.length)
@@ -184,26 +229,48 @@ server.tool("precode.verify", "Close the done-gate for the current task. If the
             });
             return await closeTask(`Verified by MCP execution: ${runs.map((r) => `${r.name} ✓ (exit ${r.exitCode})`).join(", ")}`);
         }
-        // --- Fallback: no auto check defined for this task. Self-report is
-        //     accepted but explicitly stamped UNVERIFIED so it is never mistaken
-        //     for a machine-verified pass. ---
+        // --- No auto check ran. A task NEVER closes on a self-reported pass. ---
         const reported = checkResults ?? [];
-        if (reported.length === 0) {
-            return text(`HOLD. Task #${task.index} has no executable check in .precode/checks.json and you reported none. ` +
-                "Add a real command to checks.json (preferred — then the gate runs it), or report the checks you ran. " +
-                "Nothing is marked done on an empty report.");
+        const reportedNote = reported.length
+            ? `Agent-reported (advisory, NOT used to close): ${reported
+                .map((c) => `${c.name}=${c.passed ? "pass" : "fail"}`)
+                .join(", ")}`
+            : "";
+        // Unconfigured placeholder checks (declared but no command) — hold and
+        // tell the agent to wire a real command, mark it manual, or defer.
+        if (placeholderSpecs.length > 0) {
+            return text([
+                `HOLD. Task #${task.index} is NOT done.`,
+                `${placeholderSpecs.length} declared check(s) have no command yet: ${placeholderSpecs
+                    .map((c) => c.name)
+                    .join(", ")}.`,
+                "A task never closes on a self-reported pass. Do ONE of these in .precode/checks.json:",
+                "- set a real shell `cmd` for each check (preferred — the gate then RUNS it), or",
+                '- set its `kind` to `manual` if only a human can verify it (routed to TODO_FOR_YOU.md), or',
+                "- call precode.defer_task if it genuinely cannot be verified in this environment.",
+                reportedNote,
+            ]
+                .filter(Boolean)
+                .join("\n"));
         }
-        const failedReported = reported.filter((c) => !c.passed);
-        if (failedReported.length > 0) {
-            return await gateFailure(failedReported.map((c) => `${c.name}: FAILED${c.detail ? ` — ${c.detail}` : ""}`), failedReported.map((c) => `${c.name}: ${fixHint(c.name)}`));
+        // Only explicit manual gates apply — a legitimate human-verified close.
+        if (manualSpecs.length > 0) {
+            await recordTelemetry({
+                eventName: "mcp_verify_pass",
+                root: ROOT,
+                task: taskTelemetry(task),
+                metadata: { checkCount: manualSpecs.length, executed: false, manualOnly: true },
+            });
+            return await closeTask("Closed with MANUAL gates only (no automatable check) — routed to TODO_FOR_YOU.md for your verification.");
         }
-        await recordTelemetry({
-            eventName: "mcp_verify_pass",
-            root: ROOT,
-            task: taskTelemetry(task),
-            metadata: { checkCount: reported.length, executed: false },
-        });
-        return await closeTask(`UNVERIFIED (self-reported, no checks.json command): ${reported.map((c) => `${c.name} ✓`).join(", ")}`);
+        // No check defined at all for this task.
+        return text([
+            `HOLD. Task #${task.index} has no check defined in .precode/checks.json, so it cannot be verified.`,
+            "A task never closes on a self-reported pass. Add at least one check (preferred: an `auto` check with a real `cmd` the gate runs), mark it `manual`, or call precode.defer_task.",
+            reportedNote,
+        ]
+            .filter(Boolean)
+            .join("\n"));
     }
     finally {
         await s.releaseLock();

package/dist/store.js

@@ -193,10 +193,14 @@ export class PrecodeStore {
         const project = manifest?.project ?? {};
         const tasks = await this.tasks();
         const done = tasks.filter((t) => t.done).length;
+        const deferred = await this.deferredIndices();
+        const docs = await this.listDocFiles();
         return [
             `Project: ${project.name ?? "(unknown)"} (${project.appType ?? "app"})`,
-            `Progress: ${done}/${tasks.length} tasks complete.`,
-            "Build strictly to the spec in `.precode/docs/`. Do not invent scope. Re-read the relevant doc before each task.",
+            `Progress: ${done}/${tasks.length} tasks complete${deferred.length ? `, ${deferred.length} deferred` : ""}.`,
+            docs.length
+                ? `Build strictly to the spec docs in .precode/: ${docs.join(", ")}. Re-read the relevant one before each task; do not invent scope.`
+                : "No spec docs found in .precode/docs/. Work from the tasks and acceptance criteria; do not invent scope.",
         ].join("\n");
     }
     async appendImplementation(entry) {
@@ -324,9 +328,13 @@ export async function adoptSpec(searchRoot, specPathHint) {
             error: "No spec found. Provide a SPEC.md, a .specify/.spec-workflow folder, or a docs/ folder of markdown.",
         };
     }
-    // Derive tasks: prefer explicit checkboxes; fall back to headings only when
-    // the spec has none, so heading text never pollutes a real task list.
+    // Derive tasks, in priority order so a real list is never collapsed into one:
+    //   1. explicit checkboxes  - [ ] ...
+    //   2. plain bullets / numbered items   - x   * x   1. x
+    //   3. section headings   ## / ###
+    //   4. a single catch-all when the spec has no structure at all.
     const checkboxes = [];
+    const bullets = [];
     const headings = [];
     for (const line of specBody.split("\n")) {
         const cb = TASK_RE.exec(line);
@@ -334,11 +342,21 @@ export async function adoptSpec(searchRoot, specPathHint) {
             checkboxes.push(`- [ ] ${cb[3]}`);
             continue;
         }
+        const bullet = /^\s*(?:[-*]|\d+[.)])\s+(.*\S)\s*$/.exec(line);
+        if (bullet) {
+            if (bullets.length < 40)
+                bullets.push(`- [ ] ${bullet[1]}`);
+            continue;
+        }
         const h = /^#{2,3}\s+(.*\S)\s*$/.exec(line);
         if (h && headings.length < 40)
             headings.push(`- [ ] Implement: ${h[1]}`);
     }
-    const tasks = checkboxes.length ? checkboxes : headings;
+    const tasks = checkboxes.length
+        ? checkboxes
+        : bullets.length
+            ? bullets
+            : headings;
     if (!tasks.length)
         tasks.push("- [ ] Implement the full spec, then verify.");
     await fs.mkdir(path.join(dir, "progress"), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@precode/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Open, agent-agnostic MCP server that turns a spec (any SPEC.md, best with a PreCode .precode/ package) into a self-correcting, verified build. Drives a phased build → recheck → fix loop with hard definition-of-done gates and an implemented-vs-todo ledger.",
   "license": "MIT",
   "homepage": "https://useprecode.vercel.app/mcp",