@mushi-mushi/mcp 0.9.0 → 0.10.1

package/README.md

@@ -1,4 +1,4 @@
-# mushi-mcp
+# @mushi-mushi/mcp
 
 > **Sentry sees what code throws. Mushi sees what users feel — and closes the loop with AI.**
 
@@ -20,7 +20,7 @@ That command reads `~/.mushirc`, writes `.cursor/mcp.json` with the `mushi` serv
 
 > **What this is, and what it isn't**
 >
-> - **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.
+> - **This package** (`@mushi-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. Always install it by its scoped name (`npx -y @mushi-mushi/mcp@latest`) — the bare `mushi-mcp` name was never published to npm.
 > - **`@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.
 
@@ -130,6 +130,8 @@ The endpoint accepts JSON-RPC 2.0 over POST (returns `application/json` or `text
 | `get_fix_timeline` | Ordered timeline of a fix attempt (dispatched → started → branch → commit → PR → CI → completed/failed) |
 | `get_blast_radius` | Graph traversal showing other components a bug group touches |
 | `get_knowledge_graph` | Traverse the knowledge graph from a seed component or page |
+| `setup_check` | The 4 **dispatch-readiness** checks (GitHub repo, codebase indexed, Anthropic key, autofix enabled) — run before `dispatch_fix` |
+| `ingest_setup_check` | The 4 **required ingest** checks (project, active API key, SDK heartbeat, first report) + `last_sdk_seen_at` diagnostics — run after wiring env vars to confirm the SDK is reporting |
 
 ### Write / agentic
 
@@ -366,3 +368,9 @@ In Cursor chat, type `/` — you should see the Mushi Mushi slash-prompts (`/sum
 ## License
 
 MIT
+
+
+<!-- mushi-readme-stats-footer -->
+---
+
+<sub>Monorepo scale (June 2026): 43 edge functions · 234 SQL migrations · 13 outbound plugins · 11 inbound adapters. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>

package/dist/index.js

@@ -133,10 +133,18 @@ var TOOL_CATALOG = [
   {
     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.",
+    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. For SDK ingest health (API key \u2192 heartbeat \u2192 first report), call ingest_setup_check instead.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "Is this project ready to auto-fix bugs? What is blocking me?"
+    useCase: "Is this project ready to auto-fix bugs? What is blocking dispatch?"
+  },
+  {
+    name: "ingest_setup_check",
+    title: "Ingest setup check",
+    description: "Run the 4 **required ingest** checks for the project tied to this API key: project exists, active API key, SDK heartbeat (or real report), and at least one ingested report. Returns per-step pass/fail plus last_sdk_seen_at and endpoint host diagnostics. Use after wiring env vars or pasting the SDK snippet to confirm the banner will work.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is the SDK installed and ingesting reports? Why is my banner still missing?"
   },
   // --- Write / agentic ----------------------------------------------------
   {
@@ -217,6 +225,88 @@ var TOOL_CATALOG = [
     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."
+  },
+  {
+    name: "reply_to_reporter",
+    title: "Reply to a reporter",
+    description: "Send a visible message to the end-user who filed a bug report. The reply appears in the in-app Mushi widget as an admin comment and creates an unread notification badge so the reporter sees it immediately. Use this to answer questions, request reproduction steps, or confirm a fix \u2014 without leaving the Cursor IDE.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: false },
+    useCase: "Reply to a reporter asking for more info or confirming a fix."
+  }
+];
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -292,8 +382,9 @@ function createMushiServer(config) {
     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,
@@ -304,13 +395,13 @@ 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;
   }
@@ -621,6 +712,36 @@ function createMushiServer(config) {
       });
     }
   );
+  server.registerTool(
+    "ingest_setup_check",
+    {
+      title: titleOf("ingest_setup_check"),
+      description: descOf("ingest_setup_check"),
+      annotations: annotationsFor("ingest_setup_check"),
+      inputSchema: {}
+    },
+    async () => {
+      const data = await apiCall("/v1/sync/ingest-setup");
+      const failed = data.steps.filter((s) => s.required && !s.complete);
+      const summary = data.ready ? `Ingest setup complete (${data.required_complete}/${data.required_total}) for ${data.project_name}.` : `Ingest incomplete (${data.required_complete}/${data.required_total}) \u2014 still need: ${failed.map((s) => s.label).join(", ")}.`;
+      return jsonText({
+        ready: data.ready,
+        projectId: data.project_id,
+        projectName: data.project_name,
+        requiredComplete: data.required_complete,
+        requiredTotal: data.required_total,
+        steps: data.steps.map((s) => ({
+          id: s.id,
+          label: s.label,
+          passed: s.complete,
+          required: s.required,
+          hint: s.hint
+        })),
+        diagnostic: data.diagnostic ?? null,
+        summary
+      });
+    }
+  );
   server.registerTool(
     "submit_fix_result",
     {
@@ -1004,10 +1125,204 @@ 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) }] };
+    }
+  );
+  server.registerTool(
+    "reply_to_reporter",
+    {
+      title: titleOf("reply_to_reporter", TDD_TOOL_CATALOG),
+      description: descOf("reply_to_reporter", TDD_TOOL_CATALOG),
+      annotations: annotationsFor("reply_to_reporter", TDD_TOOL_CATALOG),
+      inputSchema: {
+        reportId: z.string().describe("Report id to reply to"),
+        message: z.string().min(1).max(1e4).describe("Message text to send to the reporter"),
+        authorName: z.string().optional().describe('Display name for the admin sender (default: "Mushi Admin")')
+      }
+    },
+    async ({ reportId, message, authorName }) => {
+      const data = await apiCall(
+        `/v1/sync/reports/${reportId}/reply`,
+        {
+          method: "POST",
+          body: JSON.stringify({ message, author_name: authorName })
+        }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
   const grantedScopes = config.scopes;
   if (grantedScopes !== void 0) {
     const toolRegistry = server._registeredTools;
-    for (const spec of TOOL_CATALOG) {
+    const allSpecs = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+    for (const spec of allSpecs) {
       if (!grantedScopes.includes(spec.scope)) {
         toolRegistry[spec.name]?.remove();
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -23,30 +23,18 @@
     "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",
-    "@mushi-mushi/core": "workspace:^",
+    "@mushi-mushi/core": "^1.7.5",
     "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"
+    "vitest": "^4.1.5",
+    "@mushi-mushi/eslint-config": "0.0.0"
   },
   "repository": {
     "type": "git",
@@ -85,5 +73,17 @@
   ],
   "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"
   }
-}
+}