@precode/mcp 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @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/`](https://precode.dev) package. MIT licensed, free, runs on your agent and your tokens.
+
+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** — a task is marked done **only when its checks actually pass**, never when the agent merely claims so.
+- **Closed verify → fix → re-verify** — gaps come back with fixes and the loop will not advance past them.
+- **Deterministic-first** — trusts the build/type-check/lint/test results your agent runs in its terminal.
+
+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`:
+
+```json
+{
+  "mcpServers": {
+    "precode": { "command": "npx", "args": ["-y", "@precode/mcp"] }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add precode -- npx -y @precode/mcp
+```
+
+**Codex / Windsurf / 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
+
+```bash
+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
+
+| Tool | Does |
+|------|------|
+| `precode.get_goal` | Re-anchor on the goal + progress |
+| `precode.next_phase` | Alias for the next phased build step |
+| `precode.next_task` | Pull the next step + acceptance criteria |
+| `precode.verify` | Report check results; marks done **only if they pass** |
+| `precode.record_implementation` | Append to the implementation ledger |
+| `precode.finalize` | Write `TODO_FOR_YOU.md` |
+| `precode.adopt_spec` | Map a non-PreCode spec into `.precode/` |
+
+## Resources
+
+| Resource | 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 |

package/dist/index.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { PrecodeStore, adoptSpec } from "./store.js";
+import { recordTelemetry, taskTelemetry } from "./telemetry.js";
+/**
+ * @precode/mcp — drives a phased build → recheck → fix loop over a `.precode/`
+ * package. Fixes the loop/goal failure other spec MCPs ship with:
+ *  - goal re-anchoring every phase (get_goal / next_task echo the goal),
+ *  - HARD definition-of-done: a task is only marked done when its checks pass,
+ *  - closed verify→fix→re-verify (gaps return fixes, do not advance),
+ *  - deterministic checks run by the agent; LLM-judgment is not trusted here.
+ */
+const ROOT = process.env.PRECODE_ROOT ?? process.cwd();
+async function store() {
+    return PrecodeStore.locate(ROOT);
+}
+function text(s) {
+    return { content: [{ type: "text", 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" });
+// --- 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();
+    if (!s)
+        return NO_STORE;
+    await recordTelemetry({ eventName: "mcp_get_goal", root: ROOT });
+    return text(await s.goal());
+});
+// --- 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();
+    if (!s)
+        return NO_STORE;
+    const task = await s.nextOpenTask();
+    await recordTelemetry({
+        eventName: "mcp_next_task",
+        root: ROOT,
+        task: taskTelemetry(task),
+    });
+    if (!task) {
+        return text("All tasks complete. Run precode.finalize to write the implementation ledger and TODO_FOR_YOU.md.");
+    }
+    const goal = await s.goal();
+    const acceptance = await s.acceptance();
+    return text([
+        "## GOAL (re-anchor before building)",
+        goal,
+        "",
+        `## NEXT TASK (#${task.index})`,
+        task.text,
+        "",
+        "Re-read the relevant doc in `.precode/docs/` before coding.",
+        "Build ONLY this task. Then run the checks and call precode.verify.",
+        "",
+        "## ACCEPTANCE CRITERIA",
+        acceptance,
+    ].join("\n"));
+});
+server.tool("precode.next_phase", "Alias for precode.next_task. Pulls the next phased build step plus the goal and acceptance criteria.", {}, async () => {
+    const s = await store();
+    if (!s)
+        return NO_STORE;
+    const task = await s.nextOpenTask();
+    await recordTelemetry({
+        eventName: "mcp_next_task",
+        root: ROOT,
+        task: taskTelemetry(task),
+    });
+    if (!task) {
+        return text("All tasks complete. Run precode.finalize to write the implementation ledger and TODO_FOR_YOU.md.");
+    }
+    const goal = await s.goal();
+    const acceptance = await s.acceptance();
+    return text([
+        "## GOAL (re-anchor before building)",
+        goal,
+        "",
+        `## NEXT PHASE / TASK (#${task.index})`,
+        task.text,
+        "",
+        "Re-read the relevant doc in `.precode/docs/` before coding.",
+        "Build ONLY this task. Then run the checks and call precode.verify.",
+        "",
+        "## ACCEPTANCE CRITERIA",
+        acceptance,
+    ].join("\n"));
+});
+// --- Tool: verify (the hard done-gate + fix loop) -------------------------
+server.tool("precode.verify", "Report the results of the deterministic checks you RAN (build/type-check/lint/tests). The task is marked done ONLY if every reported check passed and at least one ran. Otherwise you get the gaps back and the task stays open — fix and call precode.verify again.", {
+    checkResults: z
+        .array(z.object({
+        name: z.string().describe("e.g. 'build', 'typecheck', 'lint', 'smoke test'"),
+        passed: z.boolean(),
+        detail: z.string().optional(),
+    }))
+        .describe("Results of checks you actually executed in the terminal."),
+    notes: z.string().optional(),
+    task: z.string().optional().describe("Optional host-side task identifier or title."),
+}, async ({ checkResults, notes, task: taskLabel }) => {
+    const s = await store();
+    if (!s)
+        return NO_STORE;
+    const task = await s.nextOpenTask();
+    if (!task)
+        return text("No open task to verify. Run precode.finalize.");
+    if (checkResults.length === 0) {
+        return text(`HOLD. Task #${task.index} cannot be marked done — you reported no checks. ` +
+            "Run the acceptance checks (build, type-check, lint, smoke test) in your terminal, then report results.");
+    }
+    const failed = checkResults.filter((c) => !c.passed);
+    if (failed.length > 0) {
+        const failureLines = failed.map((c) => `${c.name}: FAILED${c.detail ? ` — ${c.detail}` : ""}`);
+        const retry = await s.recordVerificationFailure({
+            task,
+            failures: failureLines,
+        });
+        await recordTelemetry({
+            eventName: "mcp_verify_fail",
+            root: ROOT,
+            task: taskTelemetry(task),
+            metadata: {
+                checkCount: checkResults.length,
+                failedCount: failed.length,
+                attempts: retry.attempts,
+                escalated: retry.escalated,
+            },
+        });
+        const gaps = failed
+            .map((c) => `- ${c.name}: FAILED${c.detail ? ` — ${c.detail}` : ""}`)
+            .join("\n");
+        const fixes = failed
+            .map((c) => `- ${c.name}: ${fixHint(c.name)}`)
+            .join("\n");
+        return text([
+            `GATE: Task #${task.index} stays OPEN. ${failed.length} check(s) failed:`,
+            gaps,
+            "",
+            "Concrete next fixes:",
+            fixes,
+            "",
+            `Verify attempt ${retry.attempts}/3 for this task.`,
+            retry.escalated
+                ? "Escalated honestly into .precode/progress/TODO_FOR_YOU.md because the retry bound was reached."
+                : "Fix these, re-run the checks, and call precode.verify again. Do not call precode.next_task until this passes.",
+        ].join("\n"));
+    }
+    await s.markTaskDone(task.index);
+    await recordTelemetry({
+        eventName: "mcp_verify_pass",
+        root: ROOT,
+        task: taskTelemetry(task),
+        metadata: { checkCount: checkResults.length },
+    });
+    await s.appendImplementation([
+        `## Task #${task.index}: ${task.text}`,
+        taskLabel ? `Host task: ${taskLabel}` : "",
+        `Verified: ${checkResults.map((c) => `${c.name} ✓`).join(", ")}`,
+        notes ? `Notes: ${notes}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n"));
+    const next = await s.nextOpenTask();
+    return text(next
+        ? `PASS. Task #${task.index} marked done. Call precode.next_task for the next step (#${next.index}).`
+        : `PASS. Task #${task.index} marked done. All tasks complete — call precode.finalize.`);
+});
+// --- Tool: record implementation (ledger) ---------------------------------
+server.tool("precode.record_implementation", "Log what you built for a task and any undocumented decisions, into .precode/progress/IMPLEMENTATION.md.", {
+    summary: z.string(),
+    task: z.string().optional(),
+    files: z.array(z.string()).optional(),
+    decisions: z.array(z.string()).optional(),
+}, async ({ summary, task, files, decisions }) => {
+    const s = await store();
+    if (!s)
+        return NO_STORE;
+    await recordTelemetry({
+        eventName: "mcp_record_implementation",
+        root: ROOT,
+        metadata: {
+            fileCount: files?.length ?? 0,
+            decisionCount: decisions?.length ?? 0,
+        },
+    });
+    await s.appendImplementation([
+        `### ${summary}`,
+        task ? `Task: ${task}` : "",
+        files?.length ? `Files: ${files.join(", ")}` : "",
+        decisions?.length ? `Decisions:\n${decisions.map((d) => `- ${d}`).join("\n")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n"));
+    return text("Recorded to .precode/progress/IMPLEMENTATION.md.");
+});
+// --- Tool: finalize (handoff ledger) --------------------------------------
+server.tool("precode.finalize", "Write the handoff: confirm all tasks done and record what the USER still must do (secrets, env, deploy, anything not auto-verifiable) into .precode/progress/TODO_FOR_YOU.md.", {
+    userTodos: z
+        .array(z.string())
+        .describe("Plain-language steps the human must do: API keys, env vars, deploy, manual checks."),
+    unresolved: z
+        .array(z.string())
+        .optional()
+        .describe("Anything the loop could NOT satisfy — be honest, do not hide gaps."),
+}, async ({ userTodos, unresolved }) => {
+    const s = await store();
+    if (!s)
+        return NO_STORE;
+    const tasks = await s.tasks();
+    const open = tasks.filter((t) => !t.done);
+    await recordTelemetry({
+        eventName: "mcp_finalize",
+        root: ROOT,
+        metadata: {
+            taskCount: tasks.length,
+            openTaskCount: open.length,
+            userTodoCount: userTodos.length,
+            unresolvedCount: unresolved?.length ?? 0,
+        },
+    });
+    const body = [
+        "# What you still need to do",
+        "",
+        "Generated by the PreCode MCP after the build+verify loop.",
+        "",
+        "## Your steps",
+        ...(userTodos.length ? userTodos.map((t) => `- [ ] ${t}`) : ["- [ ] (none reported)"]),
+        "",
+        "## Not yet satisfied by the build",
+        ...(unresolved?.length
+            ? unresolved.map((u) => `- ${u}`)
+            : open.length
+                ? open.map((t) => `- Task #${t.index} still open: ${t.text}`)
+                : ["- Nothing outstanding."]),
+        "",
+    ].join("\n");
+    await s.writeTodo(body);
+    return text(`Finalized. ${tasks.length - open.length}/${tasks.length} tasks done. ` +
+        `Wrote .precode/progress/TODO_FOR_YOU.md and IMPLEMENTATION.md. ` +
+        (open.length ? `WARNING: ${open.length} task(s) still open — surfaced honestly in the TODO.` : "All tasks verified."));
+});
+// --- Tool: adopt any spec -------------------------------------------------
+server.tool("precode.adopt_spec", "If there is no .precode/ here, map a plain SPEC.md / .specify / .spec-workflow / docs folder into a minimal .precode/ package so this loop works with ANY spec.", { specPath: z.string().optional().describe("Optional path hint to the spec file or folder.") }, async ({ specPath }) => {
+    const existing = await store();
+    if (existing)
+        return text("A .precode/ package already exists here. Call precode.next_task.");
+    const result = await adoptSpec(ROOT, specPath);
+    await recordTelemetry({
+        eventName: "mcp_adopt_spec",
+        root: ROOT,
+        metadata: { ok: result.ok, hasSpecPath: !!specPath },
+    });
+    return text(result.ok
+        ? `Adopted spec into .precode/. Call precode.next_task to start the build+verify loop.`
+        : `Could not adopt a spec: ${result.error}`);
+});
+// --- Resources: goal + acceptance (re-readable each phase) ----------------
+server.resource("precode-goal", "precode://goal", async (uri) => {
+    const s = await store();
+    return { contents: [{ uri: uri.href, text: s ? await s.goal() : "No .precode/ package found." }] };
+});
+server.resource("precode-acceptance", "precode://acceptance", async (uri) => {
+    const s = await store();
+    return { contents: [{ uri: uri.href, text: s ? await s.acceptance() : "No .precode/ package found." }] };
+});
+server.resource("precode-docs", "precode://docs", async (uri) => {
+    const s = await store();
+    return { contents: [{ uri: uri.href, text: s ? await s.docsBundle() : "No .precode/ package found." }] };
+});
+server.resource("precode-tasks", "precode://tasks", async (uri) => {
+    const s = await store();
+    return { contents: [{ uri: uri.href, text: s ? await s.tasksRaw() : "No .precode/ package found." }] };
+});
+server.resource("precode-progress", "precode://progress", async (uri) => {
+    const s = await store();
+    return { contents: [{ uri: uri.href, text: s ? await s.progressBundle() : "No .precode/ package found." }] };
+});
+// --- Prompt: kick off the whole loop --------------------------------------
+server.prompt("precode_build", "Start the PreCode build+verify loop for the spec in this repo.", () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: "Build this project from its spec using the PreCode loop. Steps, repeated until done:\n" +
+                    "1. Call precode.get_goal to anchor on the goal.\n" +
+                    "2. Call precode.next_task. Re-read the cited doc. Build ONLY that task.\n" +
+                    "3. Run the deterministic checks (build, type-check, lint, smoke test) in the terminal.\n" +
+                    "4. Call precode.verify with the real results. If it stays OPEN, fix and re-verify — do NOT skip ahead.\n" +
+                    "5. Call precode.record_implementation.\n" +
+                    "When precode.next_task says all done, call precode.finalize with the user's remaining steps.\n" +
+                    "If there is no .precode/ package, call precode.adopt_spec first.",
+            },
+        },
+    ],
+}));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the MCP channel.
+    console.error(`[precode-mcp] ready. root=${ROOT}`);
+}
+main().catch((err) => {
+    console.error("[precode-mcp] fatal:", err);
+    process.exit(1);
+});
+function fixHint(checkName) {
+    const lower = checkName.toLowerCase();
+    if (lower.includes("type") || lower.includes("tsc")) {
+        return "open the TypeScript diagnostics, fix the reported type errors, then rerun the same type-check command.";
+    }
+    if (lower.includes("lint") || lower.includes("eslint")) {
+        return "fix the reported lint violations without changing spec scope, then rerun lint.";
+    }
+    if (lower.includes("build")) {
+        return "inspect the build error, fix the first failing route/module/env issue, then rerun the production build.";
+    }
+    if (lower.includes("test") || lower.includes("smoke") || lower.includes("e2e")) {
+        return "reproduce the failing flow, align behavior to the acceptance criteria, then rerun the test.";
+    }
+    return "inspect the failing command output, make the smallest spec-aligned fix, then rerun this exact check.";
+}

package/dist/store.js

@@ -0,0 +1,258 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const TASK_RE = /^(\s*)-\s*\[( |x|X)\]\s+(.*\S)\s*$/;
+const MAX_VERIFY_FAILURES = 3;
+export class PrecodeStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    /** Absolute path to the `.precode/` directory. */
+    get root() {
+        return this.dir;
+    }
+    static async locate(searchRoot) {
+        const candidate = path.join(searchRoot, ".precode");
+        try {
+            const stat = await fs.stat(candidate);
+            if (stat.isDirectory())
+                return new PrecodeStore(candidate);
+        }
+        catch {
+            /* not found */
+        }
+        return null;
+    }
+    file(rel) {
+        return path.join(this.dir, rel);
+    }
+    async read(rel) {
+        try {
+            return await fs.readFile(this.file(rel), "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    async manifest() {
+        const raw = await this.read("manifest.json");
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async acceptance() {
+        return (await this.read("acceptance.md")) ?? "(no acceptance.md found)";
+    }
+    async tasksRaw() {
+        return (await this.read("tasks.md")) ?? "";
+    }
+    async tasks() {
+        const raw = await this.tasksRaw();
+        const tasks = [];
+        let index = 0;
+        for (const line of raw.split("\n")) {
+            const m = TASK_RE.exec(line);
+            if (m) {
+                tasks.push({ index, text: m[3], done: m[2].toLowerCase() === "x" });
+                index += 1;
+            }
+        }
+        return tasks;
+    }
+    async nextOpenTask() {
+        return (await this.tasks()).find((t) => !t.done) ?? null;
+    }
+    /** Hard done-gate: only flips a task to [x]. Caller must verify checks first. */
+    async markTaskDone(taskIndex) {
+        const raw = await this.tasksRaw();
+        const lines = raw.split("\n");
+        let seen = -1;
+        for (let i = 0; i < lines.length; i++) {
+            const m = TASK_RE.exec(lines[i]);
+            if (!m)
+                continue;
+            seen += 1;
+            if (seen === taskIndex) {
+                lines[i] = `${m[1]}- [x] ${m[3]}`;
+                await fs.writeFile(this.file("tasks.md"), lines.join("\n"), "utf8");
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Project + goal anchor re-read each phase to fight context drift. */
+    async goal() {
+        const manifest = await this.manifest();
+        const project = manifest?.project ?? {};
+        const tasks = await this.tasks();
+        const done = tasks.filter((t) => t.done).length;
+        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.",
+        ].join("\n");
+    }
+    async appendImplementation(entry) {
+        await fs.mkdir(this.file("progress"), { recursive: true });
+        const cur = (await this.read("progress/IMPLEMENTATION.md")) ?? "# Implementation log\n";
+        await fs.writeFile(this.file("progress/IMPLEMENTATION.md"), `${cur.trimEnd()}\n\n${entry}\n`, "utf8");
+    }
+    async recordVerificationFailure(params) {
+        await fs.mkdir(this.file("progress"), { recursive: true });
+        const rel = "progress/verification-failures.json";
+        const raw = await this.read(rel);
+        let counts = {};
+        if (raw) {
+            try {
+                counts = JSON.parse(raw);
+            }
+            catch {
+                counts = {};
+            }
+        }
+        const key = String(params.task.index);
+        const attempts = (counts[key] ?? 0) + 1;
+        counts[key] = attempts;
+        await fs.writeFile(this.file(rel), JSON.stringify(counts, null, 2), "utf8");
+        if (attempts < MAX_VERIFY_FAILURES) {
+            return { attempts, escalated: false };
+        }
+        const cur = (await this.read("progress/TODO_FOR_YOU.md")) ??
+            "# TODO for you\n\nNo manual follow-up has been recorded yet.\n";
+        const entry = [
+            `## Task #${params.task.index} needs attention`,
+            "",
+            `The MCP verify gate has failed ${attempts} time(s) for this task: ${params.task.text}`,
+            "",
+            "Failed checks:",
+            ...params.failures.map((failure) => `- ${failure}`),
+            "",
+        ].join("\n");
+        await fs.writeFile(this.file("progress/TODO_FOR_YOU.md"), `${cur.trimEnd()}\n\n${entry}`, "utf8");
+        return { attempts, escalated: true };
+    }
+    async writeTodo(content) {
+        await fs.mkdir(this.file("progress"), { recursive: true });
+        await fs.writeFile(this.file("progress/TODO_FOR_YOU.md"), content, "utf8");
+    }
+    async listDocFiles() {
+        try {
+            const files = await fs.readdir(this.file("docs"));
+            return files.filter((f) => f.endsWith(".md")).map((f) => `docs/${f}`);
+        }
+        catch {
+            return [];
+        }
+    }
+    async readRel(rel) {
+        return this.read(rel);
+    }
+    async docsBundle() {
+        const files = await this.listDocFiles();
+        if (!files.length) {
+            return "(no docs found in .precode/docs)";
+        }
+        const parts = [];
+        for (const file of files) {
+            const body = await this.read(file);
+            parts.push(`# ${file}`, "", body ?? "(unreadable)", "");
+        }
+        return parts.join("\n");
+    }
+    async progressBundle() {
+        const implementation = (await this.read("progress/IMPLEMENTATION.md")) ??
+            "# Implementation ledger\n\nNo implementation has been recorded yet.";
+        const todo = (await this.read("progress/TODO_FOR_YOU.md")) ??
+            "# TODO for you\n\nNo manual follow-up has been recorded yet.";
+        return [implementation, "", "---", "", todo].join("\n");
+    }
+}
+/**
+ * Adopt any spec into a minimal `.precode/` so non-PreCode specs get the loop.
+ * Looks for SPEC.md, a .specify/ or .spec-workflow/ folder, or a docs folder.
+ */
+export async function adoptSpec(searchRoot, specPathHint) {
+    const dir = path.join(searchRoot, ".precode");
+    const candidates = [
+        specPathHint,
+        "SPEC.md",
+        "spec.md",
+        ".specify",
+        ".spec-workflow/specs",
+        "docs",
+    ].filter(Boolean);
+    let specBody = "";
+    let found = "";
+    for (const c of candidates) {
+        const abs = path.join(searchRoot, c);
+        try {
+            const stat = await fs.stat(abs);
+            if (stat.isFile()) {
+                specBody = await fs.readFile(abs, "utf8");
+                found = c;
+                break;
+            }
+            if (stat.isDirectory()) {
+                const files = (await fs.readdir(abs)).filter((f) => f.endsWith(".md"));
+                if (files.length) {
+                    specBody = (await Promise.all(files.map((f) => fs.readFile(path.join(abs, f), "utf8")))).join("\n\n");
+                    found = c;
+                    break;
+                }
+            }
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    if (!specBody) {
+        return {
+            ok: false,
+            error: "No spec found. Provide a SPEC.md, a .specify/.spec-workflow folder, or a docs/ folder of markdown.",
+        };
+    }
+    // Derive tasks from markdown headings / existing checkboxes.
+    const tasks = [];
+    for (const line of specBody.split("\n")) {
+        const cb = TASK_RE.exec(line);
+        if (cb) {
+            tasks.push(`- [ ] ${cb[3]}`);
+            continue;
+        }
+        const h = /^#{2,3}\s+(.*\S)\s*$/.exec(line);
+        if (h && tasks.length < 40)
+            tasks.push(`- [ ] Implement: ${h[1]}`);
+    }
+    if (!tasks.length)
+        tasks.push("- [ ] Implement the full spec, then verify.");
+    await fs.mkdir(path.join(dir, "progress"), { recursive: true });
+    await fs.writeFile(path.join(dir, "docs", "SPEC.md"), specBody, "utf8").catch(async () => {
+        await fs.mkdir(path.join(dir, "docs"), { recursive: true });
+        await fs.writeFile(path.join(dir, "docs", "SPEC.md"), specBody, "utf8");
+    });
+    await fs.writeFile(path.join(dir, "tasks.md"), `# Tasks (adopted from ${found})\n\n${tasks.join("\n")}\n`, "utf8");
+    await fs.writeFile(path.join(dir, "acceptance.md"), [
+        "# Acceptance criteria and self-checks",
+        "",
+        "Adopted spec — outcome checks. Mark non-automatable items `needs manual verification`.",
+        "",
+        "## Runnable checks",
+        "- [ ] Dependencies install.",
+        "- [ ] Type-check passes.",
+        "- [ ] Lint passes.",
+        "- [ ] Production build succeeds.",
+        "- [ ] Primary user flow works end to end.",
+        "",
+        "## Manual verification",
+        "- [ ] Behavior matches `docs/SPEC.md`.",
+        "- [ ] Secrets, deploy env, and third-party integrations verified in real accounts.",
+        "",
+    ].join("\n"), "utf8");
+    await fs.writeFile(path.join(dir, "manifest.json"), JSON.stringify({ project: { name: "Adopted spec", appType: "app" }, adoptedFrom: found }, null, 2), "utf8");
+    return { ok: true, dir };
+}

package/dist/telemetry.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+function telemetryEnabled() {
+    if (process.env.PRECODE_TELEMETRY_DISABLED === "1") {
+        return false;
+    }
+    return !!process.env.PRECODE_TELEMETRY_URL;
+}
+export async function recordTelemetry(payload) {
+    if (!telemetryEnabled()) {
+        return;
+    }
+    try {
+        await fetch(process.env.PRECODE_TELEMETRY_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                ...payload,
+                root: undefined,
+                rootHash: hashRoot(payload.root),
+                createdAt: new Date().toISOString(),
+            }),
+        });
+    }
+    catch (e) {
+        console.error("[precode-mcp] telemetry failed:", e);
+    }
+}
+export function taskTelemetry(task) {
+    if (!task) {
+        return undefined;
+    }
+    return {
+        index: task.index,
+        done: task.done,
+        textLength: task.text.length,
+    };
+}
+function hashRoot(root) {
+    return createHash("sha256").update(root).digest("hex").slice(0, 16);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@precode/mcp",
+  "version": "0.1.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",
+  "type": "module",
+  "bin": {
+    "precode-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test:stdio": "npm run build && node scripts/stdio-smoke.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "spec-driven-development",
+    "precode",
+    "ai-agents",
+    "verification"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}