@mushi-mushi/mcp 0.8.0 → 0.10.0

package/CONTRIBUTING.md

@@ -101,17 +101,6 @@ Releases are fully automated. Maintainers don't run `npm publish` by hand.
 
 If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
 
-### Known CI/CD quirks and their automatic safeguards
-
-A handful of GitHub-Actions × Changesets edge cases have caused release-pipeline stalls in the past. Each is now caught automatically — keep these in mind when you see the symptom:
-
-| Symptom | Root cause | Automatic safeguard |
-| --- | --- | --- |
-| The `Build & Test` required check never registers on the `chore: version packages` PR — the PR stays "Required check missing" forever | `changeset-release/master` is pushed by `github-actions[bot]`. GitHub silently drops the downstream `pull_request` event to prevent bot loops (observed on PR #45, #102, #124). | `ci.yml` now also triggers on `push` to `changeset-release/master`, so `Build & Test` reports against the head commit directly. No empty-commit nudge needed. |
-| Release workflow fails with `No commits between master and changeset-release/master` after merging a PR with a new changeset. | A `.changeset/*.md` file whose YAML frontmatter only targets packages listed in `.changeset/config.json#ignore` (e.g. `@mushi-mushi/server`, `@mushi-mushi/admin`). `changeset version` produces no bumps, the version PR is empty, the next push errors (PR #102 / #121, 2026-05-19). | `pnpm check:changeset-orphans` runs in both `ci.yml` and `release.yml`. PR CI fails with an actionable message naming the orphan file *before* it can reach master. If you legitimately need to record an internal-only change, omit the changeset entirely — the diff lives in git history. |
-| Release workflow's `Audit signatures of installed dependencies` step fails with `npm ETARGET / No matching version found for @mushi-mushi/<pkg>@<ver>` seconds after the publish step succeeded. | npm's registry CDN can take up to ~30s to propagate a freshly-published manifest. The audit step shells out to `npm install` against the just-published version and races the CDN (observed 2026-05-20, run 26149167393). | The audit step retries with exponential backoff (1, 2, 4, 8, 16, 32s — 63s total) before failing. Sigstore signatures are written at publish time, so a one-off audit failure never indicates a corrupted package — `pnpm view <pkg> version` is the ground truth. |
-| Push to `master` after merging a PR doesn't fire the `Release` workflow. | Same anti-loop protection: when a squash merge is attributed to `github-actions[bot]`, GitHub may suppress the downstream `push` trigger. Sporadic — observed twice in the last 60 days. | `release.yml` keeps `workflow_dispatch` as the manual fallback. Recovery: **Actions → Release → Run workflow → master**. The `Build & Verify` job re-runs identically to the auto-fired path. |
-
 ### Adding a brand-new publishable package
 
 Trusted Publisher bindings are configured **per package** on `npmjs.com` and require the package to already exist on the registry. New packages therefore need a one-time bootstrap before OIDC can take over.

package/README.md

@@ -1,18 +1,44 @@
-# @mushi-mushi/mcp
+# mushi-mcp
 
-[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi Mushi's closed-loop bug intelligence into your AI coding agent — so Cursor, Claude Code, Copilot, and any other MCP-compatible client can read classified reports, query the lesson library, and dispatch AI-generated fixes directly from the editor.
+> **Sentry sees what code throws. Mushi sees what users feel — and closes the loop with AI.**
 
-**The evolutionary angle:** the lesson library (`lessons.query` tool) is the agent's institutional memory. Every bug cluster your team has ever named is available to the agent before it touches a single line of code — so it doesn't repeat the same class of mistake the last agent made. That's the "cumulative selection" loop the [main README](https://www.npmjs.com/package/mushi-mushi) describes, delivered to your IDE.
+[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi's **evolution loop** into your AI coding agent. The loop is already running in your Mushi project:
+
+```
+User feels a bug → Mushi captures it → AI triages → AI opens a PR
+→ QA verifies → Judge scores → Lesson library remembers → next agent is smarter
+```
+
+Wire it into Cursor, Claude Code, or any MCP client in one command:
+
+```bash
+npx mushi-mushi setup --ide cursor
+# or: npx mushi-mushi setup --ide claude
+```
+
+That command reads `~/.mushirc`, writes `.cursor/mcp.json` with the `mushi` server block, and prints "Done — restart Cursor and ask: `list mushi tools`". No copy-pasting environment variables.
 
 > **What this is, and what it isn't**
 >
-> - **This package** is the MCP **server** — runs locally next to your editor, talks to the Mushi Mushi API, and presents bug reports as MCP tools/resources to your coding agent.
+> - **This package** (`mushi-mcp`) is the MCP **server** — runs locally next to your editor, talks to the Mushi API, and presents bug reports as MCP tools/resources to your coding agent. The npm package name is `mushi-mcp`; the scoped alias `@mushi-mushi/mcp` still works.
 > - **`@mushi-mushi/agents`** ships the MCP **client adapter** — used by the autofix orchestrator when your project's `autofix_agent = 'mcp'`. See `packages/agents/src/adapters/mcp.ts`.
 > - The `generic_mcp` adapter shipped before V5.3 was a misnomer (it spoke plain REST). It is now `RestFixWorkerAgent`; the old export is kept as a deprecated alias for one more minor.
 
 ## Quick start
 
-### 1. With Claude Desktop
+### 0. One-liner (recommended)
+
+```bash
+# First: make sure you've logged in
+npx mushi-mushi login --api-key mushi_xxx --endpoint https://<ref>.supabase.co/functions/v1/api
+
+# Then wire your IDE
+npx mushi-mushi setup --ide cursor          # Cursor
+npx mushi-mushi setup --ide claude          # Claude Code / Claude Desktop
+npx mushi-mushi setup --ide cursor --with-rules  # also write .cursorrules
+```
+
+### 1. With Claude Desktop (manual)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 

package/dist/index.js

@@ -129,6 +129,15 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What did Stage 2 say we should try for this report?"
   },
+  // --- Setup / admin -------------------------------------------------------
+  {
+    name: "setup_check",
+    title: "Dispatch preflight check",
+    description: "Run the 4 dispatch-readiness checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, Anthropic BYOK key present, autofix enabled). Also returns the target repo URL when GitHub is connected. Use this before calling dispatch_fix to understand why a dispatch might fail \u2014 or to validate that the onboarding wizard is complete.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is this project ready to auto-fix bugs? What is blocking me?"
+  },
   // --- Write / agentic ----------------------------------------------------
   {
     name: "submit_fix_result",
@@ -198,6 +207,88 @@ var TOOL_CATALOG = [
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Manually promote this user to Champion tier as a thank-you."
+  },
+  {
+    name: "setup_repo_for_mushi",
+    title: "Bootstrap repo for Mushi",
+    description: "Writes the three Mushi bootstrap files into the current repo root: `.cursorrules` (Cursor evolution-loop coding rules), `.mushi/lessons.json` (initial empty lesson cache), and `MUSHI.md` (one-page project contract for agents). Idempotent \u2014 safe to re-run after lessons sync. Requires mcp:write scope. Call this once after connecting the repo; subsequently use `mushi sync-lessons` from CI to keep lessons current.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: false },
+    useCase: "Set up this repo for the Mushi evolution loop in one step."
+  }
+];
+var TDD_TOOL_CATALOG = [
+  {
+    name: "map_user_stories",
+    title: "Map user stories from live app",
+    description: 'Crawl a live application URL with Firecrawl/Browserbase and ask Claude to draft an inventory.yaml with pages and user stories. Creates a story_map_run row for progress tracking, then writes an inventory_proposals row (source=live_crawl). Optionally dispatches a Cursor Cloud agent to refine the draft and open a PR. Returns { runId, status: "pending" } immediately \u2014 poll get_map_run_status for progress.',
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "Map the user stories in my live app automatically without writing YAML by hand."
+  },
+  {
+    name: "get_map_run_status",
+    title: "Story map run status",
+    description: "Get the status and results of a story_map_run (pending \u2192 running \u2192 completed/failed). Returns pages_crawled, proposal_id (once done), and cursor_pr_url if Cursor Cloud refined the draft.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is my story mapping crawl done yet?"
+  },
+  {
+    name: "generate_tdd_from_story",
+    title: "Generate TDD test from user story",
+    description: "Given a user story id (from the accepted inventory), ask Claude to write a full Playwright TypeScript test. Inserts a qa_stories row (source=test_gen_from_story) with approval_status driven by automation_mode. Optionally opens a draft GitHub PR. Returns { qaStoryId, prUrl, approvalStatus, needsHumanReview }.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "Generate a Playwright test for this user story."
+  },
+  {
+    name: "improve_qa_story",
+    title: "PDCA auto-improve a failing QA story",
+    description: "Trigger the PDCA improver for a specific project. Finds recently failed qa_story_runs and uses Claude to write improved test scripts. New tests are created with source=pdca and approval gated by the original story's automation_mode.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "Fix my failing QA tests automatically."
+  },
+  {
+    name: "run_qa_story",
+    title: "Trigger a manual QA story run",
+    description: 'Queue a manual run for an enabled + approved qa_story. Returns the run id immediately; poll qa_story_runs or use get_report_detail for progress. Equivalent to "Run now" in the console.',
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "Run the login flow test right now."
+  },
+  {
+    name: "list_byok_keys",
+    title: "List BYOK API key pool",
+    description: "List all BYOK API keys for the project, grouped by provider. Shows label, priority, status, and cooldown. Never returns the raw key value \u2014 only metadata. Use this to see which keys are active or exhausted.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Which API keys are active and which are rate-limited?"
+  },
+  {
+    name: "add_byok_key",
+    title: "Add a BYOK API key",
+    description: "Add a new API key to the project's BYOK pool for a given provider (anthropic, openai, firecrawl, browserbase, cursor). Specify label and priority for ordering. The key is stored encrypted in Supabase Vault.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "Add a backup Anthropic key to the pool."
+  },
+  {
+    name: "list_pending_review_stories",
+    title: "List QA stories pending review",
+    description: "Get the queue of TDD tests that were auto-generated and are waiting for human approval before they run in the QA schedule.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What TDD tests need my approval today?"
+  },
+  {
+    name: "approve_qa_story",
+    title: "Approve or reject a pending QA story",
+    description: "Approve or reject a qa_story that is in pending_review. Approved stories are enabled in the QA schedule immediately.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    useCase: "Approve this auto-generated test."
   }
 ];
 
@@ -217,7 +308,9 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
-  const grantedScopes = new Set(config.scopes ?? ALL_SCOPES);
+  if (config.scopes !== void 0 && config.scopes.length === 0) {
+    return new McpServer({ name: "mushi-mushi", version });
+  }
   async function apiCall(path, options) {
     const res = await doFetch(`${apiEndpoint}${path}`, {
       ...options,
@@ -263,12 +356,19 @@ function createMushiServer(config) {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
     };
   }
+  function jsonResult(value) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+      structuredContent: value
+    };
+  }
   const server = new McpServer({
     name: "mushi-mushi",
     version
   });
-  function annotationsFor(name) {
-    const spec = TOOL_CATALOG.find((t) => t.name === name);
+  const ALL_TOOL_CATALOG = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+  function annotationsFor(name, catalog = ALL_TOOL_CATALOG) {
+    const spec = catalog.find((t) => t.name === name);
     if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
     const a = {
       title: spec.title,
@@ -279,33 +379,17 @@ function createMushiServer(config) {
     if (spec.hints.openWorld !== void 0) a.openWorldHint = spec.hints.openWorld;
     return a;
   }
-  function descOf(name) {
-    const spec = TOOL_CATALOG.find((t) => t.name === name);
+  function descOf(name, catalog = ALL_TOOL_CATALOG) {
+    const spec = catalog.find((t) => t.name === name);
     if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
     return spec.description;
   }
-  function titleOf(name) {
-    const spec = TOOL_CATALOG.find((t) => t.name === name);
+  function titleOf(name, catalog = ALL_TOOL_CATALOG) {
+    const spec = catalog.find((t) => t.name === name);
     if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
     return spec.title;
   }
-  function shouldRegister(name) {
-    const spec = TOOL_CATALOG.find((t) => t.name === name);
-    if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
-    return grantedScopes.has(spec.scope);
-  }
-  function jsonResult(value) {
-    return {
-      content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
-      structuredContent: value
-    };
-  }
-  const _serverRegisterTool = server.registerTool.bind(server);
-  const registerScopedTool = ((name, ...rest) => {
-    if (!shouldRegister(name)) return void 0;
-    return _serverRegisterTool(name, ...rest);
-  });
-  registerScopedTool(
+  server.registerTool(
     "get_recent_reports",
     {
       title: titleOf("get_recent_reports"),
@@ -317,12 +401,9 @@ function createMushiServer(config) {
         severity: z.string().optional().describe("Filter by severity: critical, high, medium, low"),
         limit: z.number().optional().describe("Max reports to return (default 20, max 100)")
       },
-      // Output schema (MCP 2025-06-18): when set, the SDK validates the
-      // tool's `structuredContent` and lets typed clients deserialize
-      // without re-parsing the text payload.
       outputSchema: {
-        reports: z.array(z.record(z.string(), z.unknown())).describe("Array of report rows"),
-        total: z.number().describe("Total matching rows (before limit)")
+        reports: z.array(z.unknown()),
+        total: z.number()
       }
     },
     async (args) => {
@@ -332,13 +413,10 @@ function createMushiServer(config) {
       if (args.severity) params.set("severity", args.severity);
       params.set("limit", String(Math.min(args.limit ?? 20, 100)));
       const data = await apiCall(`/v1/admin/reports?${params}`);
-      return jsonResult({
-        reports: data.reports ?? [],
-        total: data.total ?? 0
-      });
+      return jsonResult(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "get_report_detail",
     {
       title: titleOf("get_report_detail"),
@@ -348,7 +426,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}`))
   );
-  registerScopedTool(
+  server.registerTool(
     "search_reports",
     {
       title: titleOf("search_reports"),
@@ -360,7 +438,7 @@ function createMushiServer(config) {
         threshold: z.number().optional().describe("Similarity threshold 0..1, default 0.2")
       },
       outputSchema: {
-        results: z.array(z.record(z.string(), z.unknown())).describe("Ranked report rows with similarity scores")
+        results: z.array(z.unknown())
       }
     },
     async (args) => {
@@ -373,10 +451,10 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonResult({ results: data.results ?? [] });
+      return jsonResult(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "get_similar_bugs",
     {
       title: titleOf("get_similar_bugs"),
@@ -385,9 +463,6 @@ function createMushiServer(config) {
       inputSchema: {
         query: z.string().describe("Component name, page path, or bug description"),
         limit: z.number().optional().describe("Max results (default 5, max 20)")
-      },
-      outputSchema: {
-        results: z.array(z.record(z.string(), z.unknown())).describe("Ranked report rows with similarity scores")
       }
     },
     async (args) => {
@@ -400,10 +475,10 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonResult({ results: data.results ?? [] });
+      return jsonText(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "get_fix_context",
     {
       title: titleOf("get_fix_context"),
@@ -422,7 +497,7 @@ function createMushiServer(config) {
       });
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "get_fix_timeline",
     {
       title: titleOf("get_fix_timeline"),
@@ -432,7 +507,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`))
   );
-  registerScopedTool(
+  server.registerTool(
     "get_blast_radius",
     {
       title: titleOf("get_blast_radius"),
@@ -442,7 +517,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`))
   );
-  registerScopedTool(
+  server.registerTool(
     "get_knowledge_graph",
     {
       title: titleOf("get_knowledge_graph"),
@@ -461,7 +536,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "graph_neighborhood",
     {
       title: titleOf("graph_neighborhood"),
@@ -480,7 +555,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "graph_node_status",
     {
       title: titleOf("graph_node_status"),
@@ -490,7 +565,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
   );
-  registerScopedTool(
+  server.registerTool(
     "inventory_get",
     {
       title: titleOf("inventory_get"),
@@ -506,7 +581,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "inventory_diff",
     {
       title: titleOf("inventory_diff"),
@@ -525,7 +600,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "inventory_findings",
     {
       title: titleOf("inventory_findings"),
@@ -547,7 +622,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`));
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "fix_suggest",
     {
       title: titleOf("fix_suggest"),
@@ -568,7 +643,7 @@ function createMushiServer(config) {
       });
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "run_nl_query",
     {
       title: titleOf("run_nl_query"),
@@ -584,7 +659,44 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
+    "setup_check",
+    {
+      title: titleOf("setup_check"),
+      description: descOf("setup_check"),
+      annotations: annotationsFor("setup_check"),
+      inputSchema: {
+        projectId: z.string().optional().describe(
+          "Project UUID to check. Falls back to the projectId the server was initialised with."
+        )
+      }
+    },
+    async (args) => {
+      const resolvedId = args.projectId ?? projectId;
+      if (!resolvedId) {
+        return jsonText({
+          ok: false,
+          error: "No projectId provided and none configured on the MCP server. Pass projectId explicitly."
+        });
+      }
+      const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
+      const summary = data.checks.map((c) => ({
+        check: c.key,
+        label: c.label,
+        passed: c.ready,
+        hint: c.hint,
+        fixPath: c.fixHref
+      }));
+      return jsonText({
+        ready: data.ready,
+        repoUrl: data.repoUrl ?? null,
+        checks: summary,
+        // Human-readable summary for agents that paste the result into a prompt
+        summary: data.ready ? `Project ${resolvedId} is ready to dispatch auto-fixes${data.repoUrl ? ` (target: ${data.repoUrl})` : ""}.` : `Project ${resolvedId} cannot dispatch yet \u2014 ${summary.filter((c) => !c.passed).map((c) => c.label).join(", ")}.`
+      });
+    }
+  );
+  server.registerTool(
     "submit_fix_result",
     {
       title: titleOf("submit_fix_result"),
@@ -619,7 +731,7 @@ function createMushiServer(config) {
       return jsonText({ ok: true, fixId: created.fixId });
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "dispatch_fix",
     {
       title: titleOf("dispatch_fix"),
@@ -627,20 +739,13 @@ function createMushiServer(config) {
       annotations: annotationsFor("dispatch_fix"),
       inputSchema: {
         reportId: z.string().describe("Report UUID to fix"),
-        agent: z.enum(["claude_code", "codex", "rest_worker", "mcp", "cursor_cloud"]).optional().describe('Override the agent adapter. Use "cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR.'),
-        backend: z.enum(["default", "claude_code", "cursor_cloud", "mcp"]).optional().describe("Alias for agent \u2014 prefer agent. When both are set, agent wins."),
-        cursorModel: z.string().optional().describe('Optional model override when agent=cursor_cloud (e.g. "composer-latest").'),
+        agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
         idempotencyKey: z.string().uuid().optional().describe("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
         inventoryActionNodeId: z.string().uuid().optional().describe("Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR.")
       },
-      // Typed write-tool result. fixId is the cursor for get_fix_timeline so
-      // downstream tools can chain without re-parsing the text payload.
       outputSchema: {
-        fixId: z.string().describe("Newly created fix_attempt UUID"),
-        status: z.string().optional().describe("Initial status (queued, running, delegated, \u2026)"),
-        agentId: z.string().optional().describe("Cursor agent ID (bc-\u2026) when agent=cursor_cloud"),
-        runId: z.string().optional().describe("Cursor run ID when agent=cursor_cloud"),
-        prUrl: z.string().optional().describe("Draft PR URL when agent=cursor_cloud and auto_create_pr=true")
+        fixId: z.string(),
+        status: z.string()
       }
     },
     async (args, extra) => {
@@ -658,31 +763,20 @@ function createMushiServer(config) {
         } catch {
         }
       }
-      const resolvedAgent = args.agent ?? (args.backend !== "default" ? args.backend : void 0);
-      const data = await apiCall(
-        "/v1/admin/fixes/dispatch",
-        {
-          method: "POST",
-          headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
-          body: JSON.stringify({
-            reportId: args.reportId,
-            agent: resolvedAgent,
-            inventoryActionNodeId: args.inventoryActionNodeId,
-            ...args.cursorModel ? { cursorModel: args.cursorModel } : {},
-            ...projectId ? { projectId } : {}
-          })
-        }
-      );
-      return jsonResult({
-        fixId: data.fixId ?? "",
-        ...data.status ? { status: data.status } : {},
-        ...data.agentId ? { agentId: data.agentId } : {},
-        ...data.runId ? { runId: data.runId } : {},
-        ...data.prUrl ? { prUrl: data.prUrl } : {}
+      const data = await apiCall("/v1/admin/fixes/dispatch", {
+        method: "POST",
+        headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
+        body: JSON.stringify({
+          reportId: args.reportId,
+          agent: args.agent,
+          inventoryActionNodeId: args.inventoryActionNodeId,
+          ...projectId ? { projectId } : {}
+        })
       });
+      return jsonResult(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "trigger_judge",
     {
       title: titleOf("trigger_judge"),
@@ -704,7 +798,7 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "test_gen_from_report",
     {
       title: titleOf("test_gen_from_report"),
@@ -725,7 +819,7 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  registerScopedTool(
+  server.registerTool(
     "transition_status",
     {
       title: titleOf("transition_status"),
@@ -745,6 +839,26 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
+  server.registerTool(
+    "setup_repo_for_mushi",
+    {
+      title: titleOf("setup_repo_for_mushi"),
+      description: descOf("setup_repo_for_mushi"),
+      annotations: annotationsFor("setup_repo_for_mushi"),
+      inputSchema: {
+        projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
+      }
+    },
+    async (args) => {
+      const pid = args.projectId ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for setup_repo_for_mushi");
+      const data = await apiCall(`/v1/admin/projects/${pid}/repo/bootstrap`, {
+        method: "POST",
+        body: JSON.stringify({})
+      });
+      return jsonText(data);
+    }
+  );
   server.resource(
     "project_stats",
     "project://stats",
@@ -769,17 +883,15 @@ function createMushiServer(config) {
       contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
     })
   );
-  registerScopedTool(
+  const rewardsMeta = (name) => annotationsFor(name);
+  server.tool(
     "list_top_contributors",
+    rewardsMeta("list_top_contributors").title,
     {
-      title: titleOf("list_top_contributors"),
-      description: descOf("list_top_contributors"),
-      inputSchema: {
-        limit: z.number().int().min(1).max(100).optional().default(10).describe("Max rows to return (default 10, max 100)"),
-        range: z.enum(["30d", "90d", "all"]).optional().default("30d").describe("Time window for points calculation")
-      },
-      annotations: annotationsFor("list_top_contributors")
+      limit: z.number().int().min(1).max(100).optional().default(10).describe("Max rows to return (default 10, max 100)"),
+      range: z.enum(["30d", "90d", "all"]).optional().default("30d").describe("Time window for points calculation")
     },
+    rewardsMeta("list_top_contributors"),
     async ({ limit, range }) => ({
       content: [{
         type: "text",
@@ -791,18 +903,15 @@ function createMushiServer(config) {
       }]
     })
   );
-  registerScopedTool(
+  server.tool(
     "award_bonus_points",
+    rewardsMeta("award_bonus_points").title,
     {
-      title: titleOf("award_bonus_points"),
-      description: descOf("award_bonus_points"),
-      inputSchema: {
-        external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
-        points: z.number().int().min(1).max(5e4).describe("Bonus points to award (max 50,000 per call)"),
-        reason: z.string().max(200).describe("Human-readable reason, logged to end_user_activity")
-      },
-      annotations: annotationsFor("award_bonus_points")
+      external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
+      points: z.number().int().min(1).max(5e4).describe("Bonus points to award (max 50,000 per call)"),
+      reason: z.string().max(200).describe("Human-readable reason, logged to end_user_activity")
     },
+    rewardsMeta("award_bonus_points"),
     async ({ external_user_id, points, reason }) => ({
       content: [{
         type: "text",
@@ -818,18 +927,15 @@ function createMushiServer(config) {
       }]
     })
   );
-  registerScopedTool(
+  server.tool(
     "set_tier",
+    rewardsMeta("set_tier").title,
     {
-      title: titleOf("set_tier"),
-      description: descOf("set_tier"),
-      inputSchema: {
-        external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
-        tier_slug: z.string().describe('Tier slug to assign, e.g. "champion", "contributor", "explorer"'),
-        reason: z.string().max(200).optional().describe("Optional reason for manual override")
-      },
-      annotations: annotationsFor("set_tier")
+      external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
+      tier_slug: z.string().describe('Tier slug to assign, e.g. "champion", "contributor", "explorer"'),
+      reason: z.string().max(200).optional().describe("Optional reason for manual override")
     },
+    rewardsMeta("set_tier"),
     async ({ external_user_id, tier_slug, reason }) => ({
       content: [{
         type: "text",
@@ -845,6 +951,34 @@ function createMushiServer(config) {
       }]
     })
   );
+  server.resource(
+    "privacy_status",
+    "privacy://status",
+    {
+      description: "Returns the privacy posture for this project: storage region, LLM provider, whether BYOK is configured, data retention window, and last audit timestamp."
+    },
+    async () => ({
+      contents: [{
+        uri: "privacy://status",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/privacy/status"), null, 2)
+      }]
+    })
+  );
+  server.resource(
+    "evolution_history",
+    "evolution://history",
+    {
+      description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling."
+    },
+    async () => ({
+      contents: [{
+        uri: "evolution://history",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/evolution/history"), null, 2)
+      }]
+    })
+  );
   server.resource(
     "project_integration_health",
     "project://integration-health",
@@ -945,6 +1079,186 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
       }]
     })
   );
+  server.registerTool(
+    "map_user_stories",
+    {
+      title: titleOf("map_user_stories", TDD_TOOL_CATALOG),
+      description: descOf("map_user_stories", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("map_user_stories", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id to map stories for"),
+        baseUrl: z.string().url().describe("Live app URL to crawl"),
+        maxPages: z.number().int().min(1).max(50).optional().describe("Max pages to crawl (default 20)"),
+        provider: z.enum(["firecrawl", "browserbase"]).optional().describe("Crawl provider (default: firecrawl)"),
+        cursorCloudRefine: z.boolean().optional().describe("Dispatch Cursor Cloud agent to refine and open a PR")
+      }
+    },
+    async ({ projectId: projectId2, baseUrl, maxPages, provider, cursorCloudRefine }) => {
+      if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
+      const data = await apiCall(
+        `/v1/admin/inventory/${projectId2}/map-from-live`,
+        { method: "POST", body: JSON.stringify({ base_url: baseUrl, max_pages: maxPages, provider, cursor_cloud_refine: cursorCloudRefine }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_map_run_status",
+    {
+      title: titleOf("get_map_run_status", TDD_TOOL_CATALOG),
+      description: descOf("get_map_run_status", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("get_map_run_status", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(`/v1/admin/inventory/${projectId2}/map-runs`);
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "generate_tdd_from_story",
+    {
+      title: titleOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
+      description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        storyNodeId: z.string().describe("User story id slug from the accepted inventory"),
+        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Gate mode for the generated test (default: review)"),
+        baseUrl: z.string().url().optional().describe("Override the app base URL"),
+        openPr: z.boolean().optional().describe("Open a draft GitHub PR (default: true)")
+      }
+    },
+    async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
+      if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
+      const data = await apiCall(
+        `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
+        { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "improve_qa_story",
+    {
+      title: titleOf("improve_qa_story", TDD_TOOL_CATALOG),
+      description: descOf("improve_qa_story", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("improve_qa_story", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().optional().describe("Project id (omit to run across all projects)")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(
+        "/v1/admin/pdca/improve-qa-stories",
+        { method: "POST", body: JSON.stringify({ project_id: projectId2 }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "run_qa_story",
+    {
+      title: titleOf("run_qa_story", TDD_TOOL_CATALOG),
+      description: descOf("run_qa_story", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("run_qa_story", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        qaStoryId: z.string().describe("qa_story id to run")
+      }
+    },
+    async ({ projectId: projectId2, qaStoryId }) => {
+      const data = await apiCall(
+        `/v1/admin/projects/${projectId2}/qa-stories/${qaStoryId}/run`,
+        { method: "POST" }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_byok_keys",
+    {
+      title: titleOf("list_byok_keys", TDD_TOOL_CATALOG),
+      description: descOf("list_byok_keys", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("list_byok_keys", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(`/v1/admin/byok/keys?project_id=${encodeURIComponent(projectId2)}`);
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "add_byok_key",
+    {
+      title: titleOf("add_byok_key", TDD_TOOL_CATALOG),
+      description: descOf("add_byok_key", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("add_byok_key", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor"]).describe("Provider slug"),
+        key: z.string().min(10).describe("The API key value to add"),
+        label: z.string().optional().describe("Human-readable label for this key"),
+        priority: z.number().int().min(1).max(999).optional().describe("Priority for ordering (lower = higher priority)")
+      }
+    },
+    async ({ projectId: projectId2, provider, key, label, priority }) => {
+      const data = await apiCall(
+        "/v1/admin/byok/keys",
+        { method: "POST", body: JSON.stringify({ project_id: projectId2, provider_slug: provider, key, label, priority }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_pending_review_stories",
+    {
+      title: titleOf("list_pending_review_stories", TDD_TOOL_CATALOG),
+      description: descOf("list_pending_review_stories", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("list_pending_review_stories", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(`/v1/admin/inventory/${projectId2}/stories/pending-review`);
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "approve_qa_story",
+    {
+      title: titleOf("approve_qa_story", TDD_TOOL_CATALOG),
+      description: descOf("approve_qa_story", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("approve_qa_story", TDD_TOOL_CATALOG),
+      inputSchema: {
+        projectId: z.string().describe("Project id"),
+        qaStoryId: z.string().describe("QA story id to approve or reject"),
+        status: z.enum(["approved", "rejected"]).describe("New approval status")
+      }
+    },
+    async ({ projectId: projectId2, qaStoryId, status }) => {
+      const data = await apiCall(
+        `/v1/admin/inventory/${projectId2}/stories/${qaStoryId}/approval`,
+        { method: "PATCH", body: JSON.stringify({ status }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  const grantedScopes = config.scopes;
+  if (grantedScopes !== void 0) {
+    const toolRegistry = server._registeredTools;
+    const allSpecs = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+    for (const spec of allSpecs) {
+      if (!grantedScopes.includes(spec.scope)) {
+        toolRegistry[spec.name]?.remove();
+      }
+    }
+  }
   return server;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -23,18 +23,30 @@
     "CODE_OF_CONDUCT.md",
     "SECURITY.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "clean:types": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "test:smoke": "node scripts/smoke-stdio.mjs",
+    "test:localhost": "node scripts/localhost-e2e.mjs",
+    "demo": "node scripts/demo-terminal-config.mjs",
+    "inspector": "npx --yes @modelcontextprotocol/inspector@latest node ./dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.2",
-    "@mushi-mushi/core": "^1.5.0"
+    "@mushi-mushi/core": "workspace:^",
+    "zod": "^4.4.2"
   },
   "devDependencies": {
+    "@mushi-mushi/eslint-config": "workspace:*",
     "@types/node": "^22.19.17",
     "eslint": "^10.3.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "@mushi-mushi/eslint-config": "0.0.0"
+    "vitest": "^4.1.5"
   },
   "repository": {
     "type": "git",
@@ -73,17 +85,5 @@
   ],
   "engines": {
     "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsup",
-    "clean:types": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "dev": "tsup --watch",
-    "lint": "eslint src/",
-    "test": "vitest run",
-    "test:smoke": "node scripts/smoke-stdio.mjs",
-    "test:localhost": "node scripts/localhost-e2e.mjs",
-    "demo": "node scripts/demo-terminal-config.mjs",
-    "inspector": "npx --yes @modelcontextprotocol/inspector@latest node ./dist/index.js",
-    "typecheck": "tsc --noEmit"
   }
-}
+}