@mushi-mushi/mcp 0.2.1 → 0.3.1

package/README.md

@@ -52,35 +52,245 @@ The server speaks stdio MCP transport by default — your client launches it as
 
 ## Tools
 
+### Read
+
 | Tool | What it does |
 |---|---|
 | `get_recent_reports` | Fetch the N most recent reports, with optional `status` / `category` / `severity` filters |
 | `get_report_detail` | Full payload for a single report — description, console logs, network requests, screenshot URL, classification result, fix history |
-| `search_reports` | Keyword + semantic search across reports for the configured project |
+| `search_reports` | Semantic + keyword search (server-side pgvector; falls back to keyword match when embeddings aren't available) |
+| `get_similar_bugs` | Embedding-nearest neighbours for a component, page, or description |
+| `get_fix_context` | One-shot brief for a coding agent: report + repro + root-cause + ontology tags |
+| `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 |
+
+### Write / agentic
+
+| Tool | What it does |
+|---|---|
+| `submit_fix_result` | Record a fix outcome (branch, PR, files, lines) from an external agent |
+| `dispatch_fix` | Kick off the agentic fix orchestrator for a report — returns a `fix_attempt` id |
+| `trigger_judge` | Run the Sonnet-as-Judge over a batch of classified reports |
+| `transition_status` | Move a report between workflow states (enforces the same rules as the UI) |
+| `run_nl_query` | Natural-language → read-only SQL against your project data (60/hour rate-limited) |
 
 > Need a tool that isn't here? Open an issue at [github.com/kensaurus/mushi-mushi/issues](https://github.com/kensaurus/mushi-mushi/issues) and tag it `mcp`.
 
+### Tool annotations — what MCP clients see before invoking
+
+Every tool is registered via `server.registerTool()` with MCP 2025-10 **tool annotations** so clients (Cursor, Claude Desktop, Continue, Cline, Zed) can render a proper "is this safe to auto-invoke?" UI without calling the tool first. The annotations come from a single source of truth — `src/catalog.ts` — mirrored into the admin console (`apps/admin/src/lib/mcpCatalog.ts`) and guarded against drift by `scripts/check-mcp-catalog-sync.mjs`.
+
+| Annotation | Meaning | Example |
+|---|---|---|
+| `readOnlyHint: true` | Safe to loop on — never mutates state | `get_recent_reports`, every `project://` resource |
+| `destructiveHint: true` | Mutates project state; client should confirm | `dispatch_fix`, `transition_status` |
+| `idempotentHint: true` | Repeated calls produce the same effect | `transition_status`, `submit_fix_result` |
+| `openWorldHint: true` | Reaches out to your Mushi deployment (not a pure local function) | Every tool in this server |
+
+The same catalog entries power the `/mcp` beginner console in the admin app — so the tool catalog the agent sees and the tool catalog the human operator reads can never disagree.
+
+### Progress notifications on long-running tools
+
+`dispatch_fix` emits an MCP `notifications/progress` event the moment the orchestrator accepts the request, so clients that support progress (Cursor, Claude Desktop) can render a live "Dispatching fix…" indicator instead of freezing until the HTTP round-trip returns. The notification mirrors the `ProgressToken` the client passed in `_meta.progressToken`; clients that don't pass one get the normal non-streaming response, unchanged.
+
 ## Resources
 
 | URI | Returns |
 |---|---|
-| `project://settings` | Project config (name, autofix settings, plugins enabled, ontology) |
 | `project://stats` | Counts of new / classified / fixed reports + last 7-day trend |
+| `project://settings` | Project config — autofix agent, plugins enabled, ontology, LLM budgets |
+| `project://dashboard` | PDCA health snapshot — stage counts, bottleneck, recent activity (the same payload the admin console polls every 15 s) |
+
+## Prompts
+
+Named templates the MCP client surfaces in its slash-menu. Each one bakes in the house voice ("lead with the fix, skip the preamble") so agents produce consistent outputs across editors.
+
+| Prompt | When to use |
+|---|---|
+| `summarize_report_for_fix` | Before asking the agent to write the patch — produces a one-line root cause, smallest file set, repro steps, and blast-radius warnings |
+| `explain_judge_result` | After the judge scores a fix — turns the raw scores into ship / iterate / dismiss guidance |
+| `triage_next_steps` | "What should I focus on right now?" — five-item markdown list drawn from the dashboard + recent classified queue |
 
 ## Environment variables
 
 | Variable | Required | Default | Notes |
 |---|---|---|---|
-| `MUSHI_API_KEY` | yes | — | Project API key. Get one from the admin console → Settings → API keys. |
-| `MUSHI_PROJECT_ID` | yes | — | Found in the admin console URL or Settings page. |
-| `MUSHI_API_ENDPOINT` | no | `https://api.mushimushi.dev` | Override only if you self-host. |
+| `MUSHI_API_KEY` | yes | — | Project API key with `mcp:read` or `mcp:write` scope. Mint one in the admin console → **Projects** (the one-time reveal card has a **Copy as `.env.local`** tab). |
+| `MUSHI_PROJECT_ID` | yes | — | UUID from the admin console URL (`/projects/<uuid>/...`) or the reveal card. |
+| `MUSHI_API_ENDPOINT` | no | `https://api.mushimushi.dev` | Override only if you self-host. Localhost value: `http://localhost:54321/functions/v1/api`. |
+
+### Storing the key in `.env.local`
+
+The MCP binary reads these three vars from `process.env` on spawn — that means **anywhere you normally put env vars works**. The zero-friction path:
+
+1. In the admin console, mint a key and pick **Copy as `.env.local`** on the reveal card. You get a pre-formatted block:
+
+   ```bash
+   # Mushi MCP — drop into .env.local (gitignored). The MCP binary picks these up on spawn.
+   MUSHI_API_ENDPOINT=https://api.mushimushi.dev
+   MUSHI_PROJECT_ID=<your-uuid>
+   MUSHI_API_KEY=mushi_live_…
+   ```
+
+2. Paste it into your repo's `.env.local` (already gitignored by every Vite / Next.js / Node project scaffold). Confirm `.env.local` is in `.gitignore` if you're in an unusual setup.
+
+3. Tell your MCP client to inherit the shell env. For Cursor, the simplest form:
+
+   ```json
+   {
+     "mcpServers": {
+       "mushi-mushi": {
+         "command": "npx",
+         "args": ["-y", "@mushi-mushi/mcp@latest"]
+       }
+     }
+   }
+   ```
+
+   Cursor spawns the subprocess with the parent shell's env, so as long as you ran Cursor from a terminal that has `.env.local` sourced (or you're using `direnv` / `dotenv-cli`), the three vars are already in place. If you prefer to inline them — Cursor / Claude Desktop both support an `env` block in `mcp.json` — use the **Copy as `.cursor/mcp.json`** tab on the reveal card, which hard-codes the three values into the JSON for you.
+
+4. **Never** commit `.env.local`, and **never** paste a key into a repo-tracked `.cursor/mcp.json`. If you accidentally do, rotate the key from the admin console — the denormalised owner binding is rebuilt automatically on rotation.
+
+## API key scopes
+
+The admin routes the MCP server hits enforce per-key scopes. When you mint a key, pick the smallest scope that works for your agent workflow:
+
+| Scope | Grants | Use for |
+|---|---|---|
+| `report:write` | SDK ingest only (`/v1/reports`, `/v1/notifications`). **No admin access.** | Your app's runtime Mushi SDK — never give this to an MCP client. |
+| `mcp:read` | Every MCP read tool (`get_recent_reports`, `search_reports`, `get_fix_context`, `get_fix_timeline`, `get_blast_radius`, `get_knowledge_graph`) and every `project://*` resource. | Safe default for agents that only *read* from Mushi. |
+| `mcp:write` | Everything `mcp:read` grants **plus** mutating tools (`dispatch_fix`, `submit_fix_result`, `trigger_judge`, `transition_status`, `run_nl_query`). | Agents that should act on bugs (open PRs, judge, transition status). |
+
+The middleware replies **403 `INSUFFICIENT_SCOPE`** with a human-readable message if your key is missing a required scope — no silent failures.
+
+## Is this actually useful? — honest answer
+
+The short version: **yes, but only for teams that already fix bugs in an AI-augmented editor.** If your team still opens bugs exclusively in Jira and writes patches longhand, this server is solving a problem you don't have yet. Use the SDK + Discord webhook and come back later.
+
+For teams that do live in Cursor / Claude Code / Continue / Cline / Zed / Windsurf, the wins are concrete:
+
+| Use case | What it replaces | Why MCP wins |
+|---|---|---|
+| **"What should I triage right now?"** | Flipping to the admin tab, squinting at the dashboard, copying a report URL into chat | `triage_next_steps` prompt reads the live dashboard and gives the agent a five-item plan grounded in today's numbers — zero context-switch |
+| **"Fix this bug"** (from an agent) | Copy-pasting the Sentry issue body, guessing at the blast radius, hoping the agent knows which files to touch | `get_fix_context` returns a pre-baked brief (root cause + smallest file set + repro + ontology tags) over a standardised MCP transport every client supports |
+| **Cross-IDE parity** | Shipping a Cursor plugin AND a VS Code extension AND a JetBrains plugin | Ship **one** MCP server; every MCP-compatible editor picks it up. Cursor, Claude Desktop, Continue, Cline, Zed, Windsurf all already speak the protocol |
+| **Scoped automation** | Giving the agent a full admin token or writing a brittle REST wrapper | `mcp:read` vs `mcp:write` scopes are enforced at the edge function. The agent can safely loop on reads; writes require the stricter key. No bespoke ACLs |
+| **Natural-language data questions** | Opening the admin `/query` page, writing SQL by hand | `run_nl_query` — ask the agent "how many critical reports landed this week by component?" and it goes through the same NL→SQL pipeline the admin UI uses, rate-limited to 60/hour |
+| **Ad-hoc dashboards inside chat** | Refreshing the admin tab every 15 s during a release | `project://dashboard` resource returns the live PDCA snapshot; clients can re-read the URI whenever the conversation needs fresh numbers |
+
+### Are we using the full power of MCP?
+
+Honest scorecard against the MCP 2025-10 spec:
+
+- ✅ **Tools, resources, prompts** — all three primitives advertised.
+- ✅ **Tool annotations** (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) — every tool, every run.
+- ✅ **Progress notifications** — wired on `dispatch_fix` (the one genuinely long-running call). Sends `notifications/progress` the moment the orchestrator accepts the job.
+- ✅ **Scope-aware errors** — `[INSUFFICIENT_SCOPE]` surfaces verbatim so agents don't silently retry.
+- ✅ **Stdio transport** — default for local editor integration.
+- ⏳ **Resource subscriptions / `notifications/resources/list_changed`** — the spec supports live-updating resources (e.g. dashboard numbers that push rather than poll). Worth adding once Cursor + Claude Desktop both ship client support (currently patchy).
+- ⏳ **Sampling / elicitation** — letting the server ask the client to run an LLM call (e.g. to draft a commit message from the fix context). Not yet wired; would let us move some orchestrator LLM spend from server-side to the user's own subscription.
+- ⏳ **Streamable HTTP transport** — the spec's alternative to stdio for remote hosting. Relevant if we ever host the MCP server on behalf of customers; irrelevant for the local-install path that 95% of users want.
+
+If you want a feature from the "⏳" column, open an issue — we're holding them back on "MCP client support has shipped in ≥2 major clients", not on implementation effort.
+
+## Admin console: `/mcp` page
+
+The admin app ships a beginner-friendly `/mcp` page (sidebar → **Act → MCP**) that mirrors this README for non-CLI users:
+
+- **Connection status strip** — live-reads the active project's keys and tells you whether you have `mcp:read` / `mcp:write`, linking to the mint form if not.
+- **Install block** — toggles between `.cursor/mcp.json` and `.env.local` output, pre-filled with the active project's id and a `MUSHI_API_KEY` placeholder.
+- **Use-cases grid** — the same honest table above, but clickable so you can jump from a use case straight to the relevant tool in the catalog.
+- **Full tool / resource / prompt catalog** — rendered from the same `catalog.ts` the MCP server registers from, so the human doc and the machine-readable server contract cannot drift.
+
+The page is the recommended first stop for a new team member — it takes about 60 seconds to go from "I have a Mushi account" to "Cursor is calling `get_recent_reports` for me". The source of truth lives at `apps/admin/src/pages/McpPage.tsx`.
 
 ## Security
 
 - The server runs locally; your API key never leaves your machine except in calls to your configured `MUSHI_API_ENDPOINT`.
-- Use a **scoped** API key with read-only or read-write scope — never paste a service-role key.
+- **Scope keys tightly.** Give MCP the smallest scope that works — `mcp:read` is fine for 90% of agent loops.
+- Never paste a service-role key or a `report:write` SDK key — the former bypasses RLS, the latter is rejected by admin routes anyway.
+- Rotate keys from the admin console if a laptop is lost — the denormalised owner binding is rebuilt automatically on rotation.
 - The server logs to stderr; redirect to a file if you need an audit trail.
 
+## Testing locally
+
+Three layers of testing, each solving a different problem.
+
+### Layer 1 — In-process integration tests (fastest, no subprocess)
+
+Real `Client ↔ Server` handshake over `InMemoryTransport` with a mocked `fetch`. Catches protocol regressions in under a second.
+
+```bash
+pnpm --filter @mushi-mushi/mcp test
+# 18/18 pass — handshake, tool contracts, envelope unwrapping, scope errors, annotation contract
+```
+
+### Layer 2 — Stdio smoke test (verifies the built bin boots)
+
+Spawns `dist/index.js` with a dummy unreachable endpoint and confirms it advertises the expected tools/resources/prompts over stdio. Good CI gate before publishing.
+
+```bash
+pnpm --filter @mushi-mushi/mcp build
+pnpm --filter @mushi-mushi/mcp test:smoke
+# OK — 13 tools, 3 resources, 3 prompts
+```
+
+### Layer 3 — Full localhost E2E (real binary + real backend behaviour)
+
+Boots a tiny `node:http` mock of `/v1/admin/*`, spawns the real MCP binary pointed at it, and runs a real `StdioClientTransport` client through every tool + resource + a scope-denial path. This is the closest you can get to a production handshake without running Supabase Edge Functions.
+
+```bash
+pnpm --filter @mushi-mushi/mcp build
+node packages/mcp/scripts/localhost-e2e.mjs
+# 27/27 assertions — every tool, every resource, scope denial surfaced correctly
+```
+
+The harness is also the quickest way to iterate on new tools: extend the `FIXTURES` + the route switch in `scripts/localhost-e2e.mjs`, rebuild, rerun. No migrations, no Supabase boot time, no DB state.
+
+## Configuring against your own localhost
+
+When you're ready to wire the MCP into your local Mushi Mushi stack (i.e. `pnpm dev` is running the admin console + local Supabase), use these endpoints:
+
+| Env var | Localhost value | Notes |
+|---|---|---|
+| `MUSHI_API_ENDPOINT` | `http://localhost:54321/functions/v1/api` | Default Supabase CLI port; the `/api` suffix is the Hono `basePath`. |
+| `MUSHI_API_KEY` | the key you minted (see below) | Must have `mcp:read` or `mcp:write` scope. |
+| `MUSHI_PROJECT_ID` | the UUID from the admin URL | `/projects/<uuid>` in the admin console. |
+
+### Minting a localhost key
+
+1. Start the stack: `pnpm dev` (admin on `:6464`, Supabase on `:54321`).
+2. Sign in and open **Settings → API keys**.
+3. Click **New key**, pick **MCP read** or **MCP read-write** (the scope picker on the "New key" form), and copy the plain-text key that appears once — it's not retrievable later.
+4. The admin console URL is `http://localhost:6464/projects/<uuid>/...`; the `<uuid>` is your `MUSHI_PROJECT_ID`.
+
+### Pointing Cursor/Claude Desktop at localhost
+
+Replace the public endpoint block in your client's MCP config with the three env vars above. For Cursor, this lives in `.cursor/mcp.json` at your repo root:
+
+```json
+{
+  "mcpServers": {
+    "mushi-mushi-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/mushi-mushi/packages/mcp/dist/index.js"],
+      "env": {
+        "MUSHI_API_ENDPOINT": "http://localhost:54321/functions/v1/api",
+        "MUSHI_API_KEY": "mushi_live_abc…",
+        "MUSHI_PROJECT_ID": "00000000-0000-0000-0000-000000000000"
+      }
+    }
+  }
+}
+```
+
+Rebuild the package (`pnpm --filter @mushi-mushi/mcp build`) after any MCP source change — Cursor re-spawns the subprocess on config reload but doesn't recompile for you.
+
+### Sanity check: did it connect?
+
+In Cursor chat, type `/` — you should see the Mushi Mushi slash-prompts (`/summarize_report_for_fix`, `/explain_judge_result`, `/triage_next_steps`). Or ask the agent directly: _"Use the Mushi MCP to list my recent reports"_. If scope is wrong you'll see the `[INSUFFICIENT_SCOPE]` error text verbatim — rotate the key with the right scope and retry.
+
 ## See also
 
 - [V5.3 whitepaper §2.10](../../MushiMushi_Whitepaper_V5.md) — the agentic fix architecture this server feeds into.

package/dist/index.js

@@ -1,191 +1,597 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
+import { createRequire } from "module";
 import { createLogger } from "@mushi-mushi/core";
-var log = createLogger({ scope: "mushi:mcp", level: "info" });
-var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "https://api.mushimushi.dev";
-var API_KEY = process.env.MUSHI_API_KEY ?? "";
-var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
-async function apiCall(path, options) {
-  const res = await fetch(`${API_ENDPOINT}${path}`, {
-    ...options,
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${API_KEY}`,
-      "X-Mushi-Api-Key": API_KEY,
-      "X-Mushi-Project": PROJECT_ID,
-      ...options?.headers ?? {}
-    }
-  });
-  if (!res.ok) {
-    throw new Error(`Mushi API error: ${res.status} ${await res.text()}`);
-  }
-  return res.json();
-}
-var server = new McpServer({
-  name: "mushi-mushi",
-  version: "0.0.1"
-});
-server.tool(
-  "get_recent_reports",
-  "List recent bug reports with optional filters",
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/catalog.ts
+var TOOL_CATALOG = [
   {
-    status: z.string().optional().describe("Filter by status: new, classified, grouped, fixing, fixed, dismissed"),
-    category: z.string().optional().describe("Filter by category: bug, slow, visual, confusing, other"),
-    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)")
+    name: "get_recent_reports",
+    title: "Recent bug reports",
+    description: "List recent bug reports with optional filters (status / category / severity). Use this to survey what the triage queue looks like right now.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What landed in my triage queue today?"
   },
-  async (args) => {
-    const params = new URLSearchParams();
-    if (args.status) params.set("status", args.status);
-    if (args.category) params.set("category", args.category);
-    if (args.severity) params.set("severity", args.severity);
-    params.set("limit", String(args.limit ?? 20));
-    const data = await apiCall(`/v1/admin/reports?${params}`);
-    return {
-      content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }]
-    };
-  }
-);
-server.tool(
-  "get_report_detail",
-  "Get full details for a single bug report including classification, logs, and environment",
   {
-    reportId: z.string().describe("The report UUID")
+    name: "get_report_detail",
+    title: "Report detail",
+    description: "Full payload for a single report \u2014 description, console logs, network requests, screenshot URL, classification, fix history.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Show me everything you know about this report."
   },
-  async (args) => {
-    const data = await apiCall(`/v1/admin/reports/${args.reportId}`);
-    return {
-      content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }]
-    };
-  }
-);
-server.tool(
-  "search_reports",
-  "Search reports by keyword in description or summary",
   {
-    query: z.string().describe("Search query text"),
-    limit: z.number().optional().describe("Max results (default 10)")
+    name: "search_reports",
+    title: "Search reports",
+    description: "Semantic + keyword search over reports. Uses pgvector similarity server-side \u2014 falls back to description/summary substring only if embeddings are unavailable for the project.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: 'Find reports mentioning "checkout flakiness".'
   },
-  async (args) => {
-    const data = await apiCall(`/v1/admin/reports?limit=${args.limit ?? 10}`);
-    const q = args.query.toLowerCase();
-    const filtered = data.data.reports.filter((r) => {
-      const desc = (r.description ?? "").toLowerCase();
-      const summary = (r.summary ?? "").toLowerCase();
-      return desc.includes(q) || summary.includes(q);
-    });
-    return {
-      content: [{ type: "text", text: JSON.stringify({ results: filtered, total: filtered.length }, null, 2) }]
-    };
-  }
-);
-server.tool(
-  "get_fix_context",
-  "Get all context an agent needs to fix a bug: report, classification, repro steps, relevant code, graph context",
   {
-    reportId: z.string().describe("The report UUID to fix")
+    name: "get_similar_bugs",
+    title: "Similar bugs",
+    description: 'Find bugs related to a component, page, or description via pgvector nearest-neighbour search. Same backend as search_reports but tuned for "have we seen this before?".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Have we seen a bug like this before?"
   },
-  async (args) => {
-    const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
-    return {
-      content: [{
-        type: "text",
-        text: JSON.stringify({
-          report: report.data,
-          reproductionSteps: report.data.reproduction_steps ?? [],
-          component: report.data.component,
-          rootCause: report.data.stage2_analysis?.rootCause,
-          bugOntologyTags: report.data.bug_ontology_tags
-        }, null, 2)
-      }]
-    };
-  }
-);
-server.tool(
-  "submit_fix_result",
-  "Agent reports fix outcome \u2014 branch, PR URL, files changed",
   {
-    reportId: z.string().describe("The report UUID"),
-    branch: z.string().describe("Git branch name"),
-    prUrl: z.string().optional().describe("GitHub PR URL"),
-    filesChanged: z.array(z.string()).describe("Files modified"),
-    linesChanged: z.number().describe("Total lines changed"),
-    summary: z.string().describe("Fix summary")
+    name: "get_fix_context",
+    title: "Fix context bundle",
+    description: "Bundle the full context an agent needs to fix a bug: report detail, reproduction steps, component, root cause, ontology tags. One call instead of several.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Give me everything I need to fix this in one payload."
   },
-  async (args) => {
-    const data = await apiCall("/v1/admin/fixes", {
-      method: "POST",
-      body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
-    });
-    await apiCall(`/v1/admin/fixes/${data.data.fixId}`, {
-      method: "PATCH",
-      body: JSON.stringify({
-        status: "completed",
-        branch: args.branch,
-        pr_url: args.prUrl,
-        files_changed: args.filesChanged,
-        lines_changed: args.linesChanged,
-        summary: args.summary,
-        completed_at: (/* @__PURE__ */ new Date()).toISOString()
-      })
-    });
-    return {
-      content: [{ type: "text", text: JSON.stringify({ ok: true, fixId: data.data.fixId }) }]
-    };
-  }
-);
-server.tool(
-  "get_similar_bugs",
-  "Find related bugs via knowledge graph or keyword search",
   {
-    query: z.string().describe("Component name, page, or bug description"),
-    limit: z.number().optional().describe("Max results (default 5)")
+    name: "get_fix_timeline",
+    title: "Fix timeline",
+    description: 'Ordered timeline of a fix attempt \u2014 dispatched \u2192 started \u2192 branch \u2192 commit \u2192 PR opened \u2192 CI \u2192 completed/failed. Use this to debug "why did this fix fail?".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Why did this fix attempt fail \u2014 show me every step."
   },
-  async (args) => {
-    const data = await apiCall(`/v1/admin/reports?limit=${args.limit ?? 5}`);
-    const q = args.query.toLowerCase();
-    const similar = data.data.reports.filter((r) => {
-      const text = `${r.summary ?? ""} ${r.component ?? ""} ${r.description ?? ""}`.toLowerCase();
-      return text.includes(q);
-    });
-    return {
-      content: [{ type: "text", text: JSON.stringify({ similar, total: similar.length }, null, 2) }]
-    };
-  }
-);
-server.tool(
-  "get_blast_radius",
-  "Graph traversal showing affected areas for a given bug group",
   {
-    nodeId: z.string().describe("Graph node UUID")
+    name: "get_blast_radius",
+    title: "Blast radius",
+    description: "Graph traversal showing other components / pages a bug group touches. Use before dispatching a fix so the agent can scope its changes.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What else might break if I change this component?"
+  },
+  {
+    name: "get_knowledge_graph",
+    title: "Knowledge graph traversal",
+    description: "Traverse the knowledge graph from a seed component or page. Returns nodes + edges within a depth budget (max 4 hops).",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Show me how this component connects to the rest of the app."
+  },
+  {
+    name: "run_nl_query",
+    title: "Ask your data (NL \u2192 SQL)",
+    description: "Natural-language question \u2192 SQL query run against your project data. Read-only, 60/hour rate-limited, no privileged schemas.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Which components had the most critical bugs this week?"
+  },
+  // --- Write / agentic ----------------------------------------------------
+  {
+    name: "submit_fix_result",
+    title: "Record a fix outcome",
+    description: "Record a fix outcome (branch, PR, files, lines) from an external agent. Creates a fix_attempt then patches it to completed.",
+    scope: "mcp:write",
+    // Not idempotent: re-running creates a second fix_attempt row.
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "I just opened a PR \u2014 log it against the report."
   },
-  async (args) => {
-    const data = await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`);
+  {
+    name: "dispatch_fix",
+    title: "Dispatch Mushi fix agent",
+    description: "Dispatch the Mushi agentic fix orchestrator for a classified report. Returns a fix_attempt id; poll get_fix_timeline for progress.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "Let the in-repo agent attempt this fix for me."
+  },
+  {
+    name: "trigger_judge",
+    title: "Run Sonnet-as-Judge",
+    description: "Run the Sonnet-as-Judge over a batch of classified reports. Returns a batch id; results land in judge_results.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    useCase: "Grade the latest batch of fixes before I ship."
+  },
+  {
+    name: "transition_status",
+    title: "Move report between states",
+    description: "Move a report between workflow states (new \u2192 classified \u2192 grouped \u2192 fixing \u2192 fixed \u2192 dismissed). Enforces the same transition rules as the admin UI.",
+    scope: "mcp:write",
+    // Transitioning to `dismissed` is destructive by intent — it removes the
+    // report from triage queues. Flag the whole tool as destructive so the
+    // client prompts the user on every call.
+    hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
+    useCase: "Dismiss this duplicate / mark it fixed."
+  }
+];
+
+// src/server.ts
+var MushiApiError = class extends Error {
+  constructor(status, code, message) {
+    super(`[${code}] ${message}`);
+    this.status = status;
+    this.code = code;
+    this.name = "MushiApiError";
+  }
+  status;
+  code;
+};
+function createMushiServer(config) {
+  const { version, apiEndpoint, apiKey, projectId } = config;
+  const doFetch = config.fetch ?? globalThis.fetch;
+  async function apiCall(path, options) {
+    const res = await doFetch(`${apiEndpoint}${path}`, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
+        // still send it for endpoints still behind plain `jwtAuth` (legacy)
+        // and for transparent proxies that strip X-Mushi-* headers.
+        "Authorization": `Bearer ${apiKey}`,
+        "X-Mushi-Api-Key": apiKey,
+        ...projectId ? { "X-Mushi-Project": projectId } : {},
+        ...options?.headers ?? {}
+      }
+    });
+    const text = await res.text();
+    let body = null;
+    if (text) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = { raw: text };
+      }
+    }
+    if (!res.ok) {
+      const envelope2 = body;
+      const code = envelope2?.error?.code ?? `HTTP_${res.status}`;
+      const message = envelope2?.error?.message ?? text.slice(0, 500) ?? `Request failed with ${res.status}`;
+      throw new MushiApiError(res.status, code, message);
+    }
+    const envelope = body;
+    if (envelope && typeof envelope === "object" && "ok" in envelope) {
+      if (!envelope.ok) {
+        const code = envelope.error?.code ?? "API_ERROR";
+        const message = envelope.error?.message ?? "API returned ok=false";
+        throw new MushiApiError(res.status, code, message);
+      }
+      return envelope.data ?? {};
+    }
+    return body;
+  }
+  function jsonText(value) {
     return {
-      content: [{ type: "text", text: JSON.stringify(data.data, null, 2) }]
+      content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
     };
   }
-);
-server.resource(
-  "project_stats",
-  "project://stats",
-  { description: "Report counts, category breakdown, severity distribution" },
-  async () => {
-    const data = await apiCall("/v1/admin/stats");
-    return {
-      contents: [{ uri: "project://stats", mimeType: "application/json", text: JSON.stringify(data.data, null, 2) }]
+  const server = new McpServer({
+    name: "mushi-mushi",
+    version
+  });
+  function annotationsFor(name) {
+    const spec = TOOL_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,
+      readOnlyHint: spec.hints.readOnly
     };
+    if (spec.hints.destructive !== void 0) a.destructiveHint = spec.hints.destructive;
+    if (spec.hints.idempotent !== void 0) a.idempotentHint = spec.hints.idempotent;
+    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);
+    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);
+    if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
+    return spec.title;
   }
-);
+  server.registerTool(
+    "get_recent_reports",
+    {
+      title: titleOf("get_recent_reports"),
+      description: descOf("get_recent_reports"),
+      annotations: annotationsFor("get_recent_reports"),
+      inputSchema: {
+        status: z.string().optional().describe("Filter by status: new, classified, grouped, fixing, fixed, dismissed"),
+        category: z.string().optional().describe("Filter by category: bug, slow, visual, confusing, other"),
+        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)")
+      }
+    },
+    async (args) => {
+      const params = new URLSearchParams();
+      if (args.status) params.set("status", args.status);
+      if (args.category) params.set("category", args.category);
+      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 jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_report_detail",
+    {
+      title: titleOf("get_report_detail"),
+      description: descOf("get_report_detail"),
+      annotations: annotationsFor("get_report_detail"),
+      inputSchema: { reportId: z.string().describe("The report UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}`))
+  );
+  server.registerTool(
+    "search_reports",
+    {
+      title: titleOf("search_reports"),
+      description: descOf("search_reports"),
+      annotations: annotationsFor("search_reports"),
+      inputSchema: {
+        query: z.string().describe("Natural-language search text or component path"),
+        limit: z.number().optional().describe("Max results (default 10, max 50)"),
+        threshold: z.number().optional().describe("Similarity threshold 0..1, default 0.2")
+      }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/reports/similarity", {
+        method: "POST",
+        body: JSON.stringify({
+          query: args.query,
+          k: Math.min(args.limit ?? 10, 50),
+          threshold: args.threshold ?? 0.2,
+          ...projectId ? { projectId } : {}
+        })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_similar_bugs",
+    {
+      title: titleOf("get_similar_bugs"),
+      description: descOf("get_similar_bugs"),
+      annotations: annotationsFor("get_similar_bugs"),
+      inputSchema: {
+        query: z.string().describe("Component name, page path, or bug description"),
+        limit: z.number().optional().describe("Max results (default 5, max 20)")
+      }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/reports/similarity", {
+        method: "POST",
+        body: JSON.stringify({
+          query: args.query,
+          k: Math.min(args.limit ?? 5, 20),
+          threshold: 0.3,
+          ...projectId ? { projectId } : {}
+        })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_fix_context",
+    {
+      title: titleOf("get_fix_context"),
+      description: descOf("get_fix_context"),
+      annotations: annotationsFor("get_fix_context"),
+      inputSchema: { reportId: z.string().describe("The report UUID to fix") }
+    },
+    async (args) => {
+      const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      return jsonText({
+        report,
+        reproductionSteps: report.reproduction_steps ?? [],
+        component: report.component,
+        rootCause: report.stage2_analysis?.rootCause,
+        bugOntologyTags: report.bug_ontology_tags
+      });
+    }
+  );
+  server.registerTool(
+    "get_fix_timeline",
+    {
+      title: titleOf("get_fix_timeline"),
+      description: descOf("get_fix_timeline"),
+      annotations: annotationsFor("get_fix_timeline"),
+      inputSchema: { fixId: z.string().describe("fix_attempt UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`))
+  );
+  server.registerTool(
+    "get_blast_radius",
+    {
+      title: titleOf("get_blast_radius"),
+      description: descOf("get_blast_radius"),
+      annotations: annotationsFor("get_blast_radius"),
+      inputSchema: { nodeId: z.string().describe("Graph node UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`))
+  );
+  server.registerTool(
+    "get_knowledge_graph",
+    {
+      title: titleOf("get_knowledge_graph"),
+      description: descOf("get_knowledge_graph"),
+      annotations: annotationsFor("get_knowledge_graph"),
+      inputSchema: {
+        seed: z.string().describe("Starting node id or label"),
+        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+      }
+    },
+    async (args) => {
+      const params = new URLSearchParams({
+        seed: args.seed,
+        depth: String(Math.min(args.depth ?? 2, 4))
+      });
+      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+    }
+  );
+  server.registerTool(
+    "submit_fix_result",
+    {
+      title: titleOf("submit_fix_result"),
+      description: descOf("submit_fix_result"),
+      annotations: annotationsFor("submit_fix_result"),
+      inputSchema: {
+        reportId: z.string().describe("The report UUID"),
+        branch: z.string().describe("Git branch name"),
+        prUrl: z.string().optional().describe("GitHub PR URL"),
+        filesChanged: z.array(z.string()).describe("Files modified"),
+        linesChanged: z.number().describe("Total lines changed"),
+        summary: z.string().describe("Fix summary")
+      }
+    },
+    async (args) => {
+      const created = await apiCall("/v1/admin/fixes", {
+        method: "POST",
+        body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
+      });
+      await apiCall(`/v1/admin/fixes/${created.fixId}`, {
+        method: "PATCH",
+        body: JSON.stringify({
+          status: "completed",
+          branch: args.branch,
+          pr_url: args.prUrl,
+          files_changed: args.filesChanged,
+          lines_changed: args.linesChanged,
+          summary: args.summary,
+          completed_at: (/* @__PURE__ */ new Date()).toISOString()
+        })
+      });
+      return jsonText({ ok: true, fixId: created.fixId });
+    }
+  );
+  server.registerTool(
+    "dispatch_fix",
+    {
+      title: titleOf("dispatch_fix"),
+      description: descOf("dispatch_fix"),
+      annotations: annotationsFor("dispatch_fix"),
+      inputSchema: {
+        reportId: z.string().describe("Report UUID to fix"),
+        agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter")
+      }
+    },
+    async (args, extra) => {
+      if (extra?.sendNotification && extra?._meta?.progressToken) {
+        try {
+          await extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+              progressToken: extra._meta.progressToken,
+              progress: 0,
+              total: 100,
+              message: "Dispatching Mushi fix orchestrator\u2026"
+            }
+          });
+        } catch {
+        }
+      }
+      const data = await apiCall("/v1/admin/fixes/dispatch", {
+        method: "POST",
+        body: JSON.stringify({
+          reportId: args.reportId,
+          agent: args.agent,
+          ...projectId ? { projectId } : {}
+        })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "trigger_judge",
+    {
+      title: titleOf("trigger_judge"),
+      description: descOf("trigger_judge"),
+      annotations: annotationsFor("trigger_judge"),
+      inputSchema: {
+        limit: z.number().optional().describe("Max reports to judge in this batch (default 25, max 100)"),
+        projectId: z.string().optional().describe("Restrict to one project when the API key owns multiple")
+      }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/judge/run", {
+        method: "POST",
+        body: JSON.stringify({
+          limit: Math.min(args.limit ?? 25, 100),
+          projectId: args.projectId ?? projectId ?? void 0
+        })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "transition_status",
+    {
+      title: titleOf("transition_status"),
+      description: descOf("transition_status"),
+      annotations: annotationsFor("transition_status"),
+      inputSchema: {
+        reportId: z.string().describe("Report UUID"),
+        status: z.enum(["pending", "classified", "grouped", "fixing", "fixed", "dismissed"]).describe("Target status"),
+        reason: z.string().optional().describe("Reason for the transition (audit trail)")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/reports/${args.reportId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status: args.status, reason: args.reason })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "run_nl_query",
+    {
+      title: titleOf("run_nl_query"),
+      description: descOf("run_nl_query"),
+      annotations: annotationsFor("run_nl_query"),
+      inputSchema: { question: z.string().describe('Question in plain English, e.g. "Which components had the most critical bugs this week?"') }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/query", {
+        method: "POST",
+        body: JSON.stringify({ question: args.question })
+      });
+      return jsonText(data);
+    }
+  );
+  server.resource(
+    "project_stats",
+    "project://stats",
+    { description: "Report counts, category breakdown, severity distribution" },
+    async () => ({
+      contents: [{ uri: "project://stats", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/stats"), null, 2) }]
+    })
+  );
+  server.resource(
+    "project_settings",
+    "project://settings",
+    { description: "Project configuration \u2014 autofix agent, plugins enabled, ontology, LLM budgets" },
+    async () => ({
+      contents: [{ uri: "project://settings", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/settings"), null, 2) }]
+    })
+  );
+  server.resource(
+    "project_dashboard",
+    "project://dashboard",
+    { description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls)" },
+    async () => ({
+      contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
+    })
+  );
+  server.prompt(
+    "summarize_report_for_fix",
+    "Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. Use before asking an agent to write the patch.",
+    { reportId: z.string().describe("The report UUID to summarize") },
+    ({ reportId }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a senior engineer preparing a fix plan. Use the Mushi MCP tools to:
+1. Call get_fix_context for reportId "${reportId}".
+2. Call get_blast_radius if the report has a component node id.
+3. Call get_similar_bugs with the component or summary as the query.
+
+Then produce a markdown fix plan with exactly these sections:
+- One-line root cause
+- Files likely to change (smallest set that fixes the root cause)
+- Reproduction steps (numbered, \u22645)
+- Blast-radius warnings (what else might break)
+- Confidence (low/medium/high) with a one-line justification
+
+Lead with the fix. Skip the preamble.`
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "explain_judge_result",
+    "Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. Use after a fix attempt has been judged.",
+    { fixId: z.string().describe("The fix_attempt UUID to explain") },
+    ({ fixId }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a release engineer. Use the Mushi MCP tools:
+1. Call get_fix_timeline for fixId "${fixId}" to see the full PDCA journey.
+
+Then write a short verdict in this format:
+- **Recommendation:** ship / iterate / dismiss
+- **Why:** 1\u20132 sentences referencing the judge scores and CI signal
+- **If iterate:** bullet list of the smallest next patch
+
+No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "triage_next_steps",
+    'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
+    {},
+    () => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a tech lead looking at the Mushi cockpit. Use the MCP tools:
+1. Read the project://dashboard resource for the PDCA snapshot.
+2. Call get_recent_reports with status="classified", limit=10.
+
+Then output exactly 5 bullets, in priority order, each formatted as:
+\`**Action** \u2014 why it matters \u2014 suggested tool call\`
+
+Prefer items that are bottlenecks or critical severity. Skip filler.`
+        }
+      }]
+    })
+  );
+  return server;
+}
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var VERSION = require2("../package.json").version;
+var log = createLogger({ scope: "mushi:mcp", level: "info" });
+var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "https://api.mushimushi.dev";
+var API_KEY = process.env.MUSHI_API_KEY ?? "";
+var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
 async function main() {
   if (!API_KEY) {
     log.fatal("MUSHI_API_KEY environment variable is required");
     process.exit(1);
   }
+  log.info("Starting Mushi MCP server", { version: VERSION, endpoint: API_ENDPOINT, hasProjectId: !!PROJECT_ID });
+  const server = createMushiServer({
+    version: VERSION,
+    apiEndpoint: API_ENDPOINT,
+    apiKey: API_KEY,
+    projectId: PROJECT_ID || void 0
+  });
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -23,7 +23,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6",
-    "@mushi-mushi/core": "^0.2.1"
+    "@mushi-mushi/core": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -62,9 +62,13 @@
   ],
   "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",
     "typecheck": "tsc --noEmit"
   }
 }