npm - @mushi-mushi/mcp - Versions diffs - 0.24.3 → 0.24.5 - Mend

@mushi-mushi/mcp 0.24.3 → 0.24.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +45 -443
package/dist/catalog.js +1 -1
package/dist/{chunk-3IVSUYFV.js → chunk-V3M4GZBV.js} +2 -2
package/dist/clients.d.ts +1 -1
package/dist/clients.js +1 -1
package/dist/index.js +96 -11
package/dist/server.d.ts +7 -1
package/dist/server.js +33 -8
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -7,52 +7,22 @@
 [![Try the demo — no signup](https://img.shields.io/badge/Try%20the%20demo-no%20signup-E34234)](https://kensaur.us/mushi-mushi/docs/connect)
 [![npm](https://img.shields.io/npm/v/@mushi-mushi/mcp?color=cb3837)](https://www.npmjs.com/package/@mushi-mushi/mcp)
-[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi into Cursor, Claude Code, and any MCP client. Pull fix context, review bugs, and dispatch fixes without a second LLM vendor key.
+The [Model Context Protocol](https://modelcontextprotocol.io/) server for [Mushi Mushi](https://github.com/kensaurus/mushi-mushi). It lets Cursor, Claude Code, VS Code or any MCP client read your app's bug reports, get a plain-English diagnosis with a fix to start from, and dispatch or merge fixes. Your editor's own model does the work, so you need no second LLM key.
-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
+```mermaid
+flowchart LR
+    A["Bug reports<br/>in Mushi"] --> B["This MCP server"] --> C["Your editor<br/>'what's broken in prod?'"] --> D["Fix: you, or a<br/>draft PR from an agent"]
 ```
-That command reads CLI config at **`~/.config/mushi/config.json`** (legacy `~/.mushirc` auto-migrates), writes `.cursor/mcp.json` with the `mushi-<slug>` 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** (`@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.
 ## Quick start
-### 0. One-click: "Add to Cursor" deeplink
-The Mushi admin console (**Admin → MCP → Setup tab**) generates a one-click deeplink that opens Cursor's "Install MCP server?" dialog with your project ID and a freshly-minted `mcp:write` key already embedded:
-```
-cursor://anysphere.cursor-deeplink/mcp/install?name=mushi-<project>&config=<base64>
-```
-Click **"⚡ Add to Cursor"** (or **"Add to VS Code"**); Cursor prompts you to confirm, then writes the server block into your global `mcp.json` automatically. No copy-pasting.
-> **Security note:** The deeplink mints a dedicated `mcp:write` key (or `mcp:read` for read-only), separate from your app's SDK key. Your SDK key (the `report:write`-scoped key your app sends bug reports with) should never carry `mcp:write`; it would expose admin-level triage and fix dispatch to anyone who extracted it from your browser bundle. The deeplink mint enforces this separation automatically. See [API key scopes](#api-key-scopes) below.
-### 1. One-liner CLI (recommended for first-time setup)
 ```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
+npx mushi-mushi setup --ide cursor   # or: claude, continue, zed
 ```
-### 2. With Claude Desktop (manual)
+Restart the editor and ask *"what's broken in prod?"*. For Cursor and Claude, `setup` writes the hosted server entry: the editor opens a browser sign-in on first use, and no API key is stored on disk. Pass `--stdio` for a local server, or `--with-rules` to also write the lesson-library rules file. You can also use the one-click **Add to Cursor** button on the [connect page](https://kensaur.us/mushi-mushi/docs/connect).
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+### Manual setup (any MCP client)
 ```json
 {
@@ -62,436 +32,68 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
       "args": ["-y", "@mushi-mushi/mcp@latest"],
       "env": {
         "MUSHI_API_KEY": "mushi_xxxxxxxxxxxxxxxxxxxx",
-        "MUSHI_PROJECT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-        "MUSHI_API_ENDPOINT": "https://<your-ref>.supabase.co/functions/v1/api"
+        "MUSHI_PROJECT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       }
     }
   }
 }
 ```
-Restart Claude Desktop. You should see a hammer icon in the chat input; click it to see the Mushi Mushi tools.
-> **Where do I find these values?**
-> - **`MUSHI_API_KEY`**: [Admin → Connect](https://kensaur.us/mushi-mushi/admin/connect) or **MCP** setup; mint an `mcp:read` / `mcp:write` key. This is **not** the SDK ingest key from **Setup → Verify** (`report:write`) and **not** a BYOK key from **Settings → API Keys**.
-> - **`MUSHI_PROJECT_ID`**: [Admin console](https://kensaur.us/mushi-mushi/projects) → click your project → copy the UUID below the project name (e.g. `542b34e0-019e-41fe-b900-7b637717bb86`)
-> - **`MUSHI_API_ENDPOINT`**: Shown when you mint the MCP key, or use your project's API base (`https://<ref>.supabase.co/functions/v1/api`)
->
-> Or visit **Admin → MCP** in the console for a one-click pre-filled config snippet.
-### 3. With Cursor (manual)
-In Cursor settings, open **MCP** → **Add new MCP server** and paste:
-```bash
-npx -y @mushi-mushi/mcp@latest
-```
-Then set the same three environment variables:
 | Variable | Where to find it |
-|---|---|
-| `MUSHI_API_KEY` | **Connect** or **MCP** tab: mint `mcp:read` / `mcp:write` (not Setup → Verify ingest key; not Settings → BYOK) |
-| `MUSHI_PROJECT_ID` | Admin console → Projects → click project → UUID below the name |
-| `MUSHI_API_ENDPOINT` | Shown at key mint, or your Supabase `.../functions/v1/api` base |
-Without `MUSHI_PROJECT_ID` the server starts but scoped tools return an empty result with a message pointing you here.
-### 4. From the command line
-```bash
-MUSHI_API_KEY=mushi_xxxxxxxxxxxxxxxxxxxx \
-MUSHI_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
-npx -y @mushi-mushi/mcp@latest
-```
-The server speaks stdio MCP transport by default; your client launches it as a subprocess.
-### 5. Hosted Streamable HTTP (no subprocess)
-The Mushi backend now exposes the same tool catalog over the **Streamable HTTP** transport (dual-era: MCP 2024-11-05 … 2025-11-25 legacy and the current 2026-07-28 revision) at `/functions/v1/mcp`. Use this when you want to skip the local subprocess; typical for OpenAI Agents SDK, ChatGPT Agent, hosted CrewAI, or any orchestrator that talks remote MCP:
-```jsonc
-// .cursor/mcp.json — example (hosted HTTP)
-{
-  "mcpServers": {
-    "mushi-mushi-hosted": {
-      "type": "http",
-      "url": "https://<your-ref>.supabase.co/functions/v1/mcp",
-      "headers": {
-        "Authorization": "Bearer mushi_xxxxxxxxxxxxxxxxxxxx",
-        "X-Mushi-Api-Key": "mushi_xxxxxxxxxxxxxxxxxxxx",
-        "X-Mushi-Project-Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-      }
-    }
-  }
-}
-```
-> **Cursor icon:** HTTP MCP URLs on `*.supabase.co` often show the **Supabase favicon** in Cursor settings; not a Mushi bug. Use **stdio** (`command` + `npx @mushi-mushi/mcp`) for the red 虫 stamp, or set `"icon": "https://kensaur.us/mushi-mushi/docs/integrations/mushi-mark-512.png"` in your server block. The hosted endpoint also emits MCP `serverInfo.icons` and serves inline SVG at `?icon=1`.
-### Feature groups (`?features=` / `MUSHI_FEATURES`)
-Full catalog is **117 tools** (stdio / `MUSHI_FEATURES=all`). The hosted HTTP
-endpoint exposes a leaner subset filtered by feature groups (see
-`mcp-hosted-tool-manifest.json`). New installs now default to the lean
-`triage,fixes,inventory,setup,docs` set automatically (stdio: when
-`MUSHI_FEATURES` is unset; HTTP: pass the same `?features=` on the URL). To
-change the surface:
-- **Stdio:** `MUSHI_FEATURES=all` for the full catalog, or a CSV like `MUSHI_FEATURES=triage,qa,skills`
-- **HTTP:** `?features=all` or `?features=triage,qa,skills` on the MCP URL
-Renamed tools (`inventory_get` → `get_inventory`, `inventory_diff` →
-`diff_inventory`, `inventory_findings` → `list_gate_findings`, `fix_suggest` →
-`suggest_fix`, `graph_neighborhood` → `get_graph_neighborhood`,
-`graph_node_status` → `get_graph_node`) and the consolidated setup tooling
-(`setup_check` / `ingest_setup_check` / `diagnose_connection` → `diagnose_setup`;
-`get_activation_status` → `activation_status`; `get_reporter_thread` →
-`get_report_timeline`) are documented in the changelog; update calls to the new
-names.
-New unified tools: `diagnose_setup` (replaces the setup trilogy), `search_mushi_docs` (keyword doc search).
-Append `?read_only=1` to the URL to hide write tools (Supabase-parity mode).
-## Programmatic imports
-For custom MCP hosts or tests:
-| Subpath | Exports |
 | --- | --- |
-| `@mushi-mushi/mcp/catalog` | `TOOL_CATALOG`, scopes, tool specs |
-| `@mushi-mushi/mcp/server` | `createMushiServer()` |
-| `@mushi-mushi/mcp/branding` | Icons and server metadata |
-| `@mushi-mushi/mcp/feature-groups` | `MUSHI_FEATURES` filtering |
-## Cursor config hygiene
-1. **One global MCP config**; keep `mushi` in `~/.cursor/mcp.json` only. Do **not** duplicate `mushi` / `mushi-stdio` in per-project `.cursor/mcp.json` (prevents connection storms). Project repos may ship `{}` or a comment pointing to the global file.
-2. **Windows paths**; use forward slashes in JSON (`C:/Users/...`) or escaped backslashes (`C:\\Users\\...`). Raw `\f`, `\n`, `\t` in paths corrupt JSON.
-3. **Multi-project**; either one HTTP server per project (distinct server name + `X-Mushi-Project-Id`) or one stdio server and pass `projectId` on each tool call.
-Tool parameters are camelCase (`projectId`, `reportId`, `includeRaw`). The snake_case spelling of any of them (`project_id`) is accepted too, on both transports, so older prompts and configs keep working.
-4. **After editing global config**; fully restart Cursor (MCP panel must reload).
-| Header | Role |
-|--------|------|
-| `Authorization: Bearer <key>` | Auth (optional duplicate of API key) |
-| `X-Mushi-Api-Key` | Auth (preferred for MCP clients) |
-| `X-Mushi-Project-Id` | **Project scope**: required for API-key callers |
-~~`X-Mushi-Project`~~ is deprecated for project UUID (collision with legacy slug header).
-The endpoint accepts JSON-RPC 2.0 over POST (returns `application/json` or `text/event-stream` per content negotiation), opens an SSE stream on GET for server-pushed notifications, and accepts DELETE for session termination. Auth is the same dual-mode API-key / JWT used everywhere else on `/v1/admin/*`.
-## 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` | 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 |
-| `diagnose_setup` | Setup health in one call: `mode=full` (default) runs ingest + dispatch preflight, `mode=ingest` / `mode=dispatch` narrow it. Returns the single best next action. Run first when a user says setup is broken |
-| `check_sdk_version` | Compare a published `@mushi-mushi/*` pin to `GET /v1/sdk/latest-version`. Returns `{ package, current, latest, outdated }` and, when outdated, Sentry-style `suggestedActions` (max 1). Does not bump the pin. |
-| `activation_status` | Unified activation posture for the active project: required steps, SDK heartbeat, dispatch preflight, and the next best action |
-| `query_funnel` | Ordered funnel over `Mushi.track()` events (2–8 steps, per-step window, optional breakdown). Answers "where do users drop off?" from `GET /v1/admin/events/funnel` |
-| `get_product_events_summary` | Event names, counts, distinct users and daily volume for the trailing window — call first to discover event names |
-| `get_user_paths` | Most common events users fired right after a given event ("what did they do next?") from `GET /v1/admin/events/paths` |
-| `get_report_timeline` | Ordered report timeline: the reporter/admin comment thread (including verify/reopen signals) plus fix, QA, and status lanes. Use when triaging whether an end user still sees a bug as unfixed |
-| `list_projects` | Discover all Mushi projects accessible to this API key. Returns project id, name, and created date |
-| `get_project_context` | Rich context snapshot: SDK heartbeat, ingest status, autofix readiness, and open report counts |
-| `get_pipeline_logs` | Recent log entries from fix-worker, pipeline, and QA story runner: filterable by service, level, time, and limit |
-| `get_report_evidence` | Focused evidence package for a report: screenshot URL, console logs, network excerpts, environment, and user comments (lighter than `get_report_detail`) |
-| `triage_issue` | **Primary triage entry point**: combines report detail, evidence, similar bugs, fix context, blast radius, pipeline logs, and recommended next actions in one packet |
-| `query_lessons` | Token-budget retrieval of relevant learning rules for a code diff |
-| `list_lessons` | List promoted learning rules (lessons) for the current project |
-### 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) |
-### Codebase (indexed repos)
-When codebase indexing is enabled on a project, these tools ground on `project_codebase_files` (+ wiki chunks when configured):
-| Tool | Scope | Purpose |
-|------|-------|---------|
-| `ask_codebase` | write | Plain-English Q&A with file:line citations |
-| `get_file_summary` | read | Lazy plain-English file/symbol summary |
-| `get_codebase_tour` | read | Dependency-ordered onboarding tour |
-| `search_codebase` | read | Semantic (or scoped) embedding search |
-| `get_codebase_domains` | read | Business domain / flow map |
-| `analyze_codebase_impact` | read | Diff impact (paths, last push, compare, fix PR) |
-| `analyze_wiki_knowledge` | read | Wiki/docs knowledge graph |
-| `get_repo_digest` | read | Paste-ready repo digest (tree + files) at a pinned commit, scoped to a folder or a bug; default feature set, no index needed |
-> 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 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
+| `MUSHI_API_KEY` | Console → **Connect** or **MCP**: mint an `mcp:read` or `mcp:write` key. Not the SDK key from Setup → Verify, and not an AI key from Settings |
+| `MUSHI_PROJECT_ID` | Console → Projects → the UUID under your project's name |
+| `MUSHI_API_ENDPOINT` | Optional. Only for self-hosting, e.g. `http://localhost:54321/functions/v1/api` |
+| `MUSHI_FEATURES` | Optional. Tool groups to expose (see below) |
-Full list (8). See also the generated catalog at
-[kensaur.us/mushi-mushi/docs/sdks/mcp-tools](https://kensaur.us/mushi-mushi/docs/sdks/mcp-tools).
+Claude Desktop does not expand `${VAR}` references in this file; Cursor and VS Code expand `${env:MUSHI_API_KEY}` and Claude Code expands `${MUSHI_API_KEY}`. Keep the key out of any `mcp.json` you commit.
-| URI | Returns |
-|---|---|
-| `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) |
-| `privacy://status` | Privacy / PII scrubber status for the project |
-| `evolution://history` | Evolution / PDCA history snapshot |
-| `mushi://activation` | Activation / connection status for the project |
-| `project://integration-health` | Integration health probes (Slack, Sentry, GitHub, …) |
-| `inventory://current` | Current inventory snapshot |
+## What your editor gets
-## 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 |
-| `mushi_setup` | Guided first-time MCP / SDK setup checklist |
-## Environment variables
-| Variable | Required | Default | Notes |
-|---|---|---|---|
-| `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://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api` | Override only if you self-host. Localhost: `http://localhost:54321/functions/v1/api`. |
-| `MUSHI_MCP_SENTRY_DSN` | no | — | Reports this server's own errors to your Sentry project. Needs `@sentry/node` installed next to the server (an optional peer, not installed by default): `npx -p @sentry/node -p @mushi-mushi/mcp mushi-mcp`. |
-If a client passes a variable reference through unexpanded (the server receives the literal text `${MUSHI_API_KEY}`), the server treats it as unset: it falls back to the `mushi login` config, or serves setup mode and prints which client syntax to use. Claude Desktop expands no variables; Cursor and VS Code expand `${env:MUSHI_API_KEY}`; Claude Code expands `${MUSHI_API_KEY}`.
-### 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://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api
-   MUSHI_PROJECT_ID=<your-uuid>
-   MUSHI_API_KEY=mushi_…
-   ```
-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.
-## When MCP helps (and when it doesn't)
-Useful if you 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 live in Cursor / Claude Code / Continue / Cline / Zed / Windsurf:
-| 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 |
-### MCP spec coverage
-| Status | Capability |
+| Start here | What it does |
 | --- | --- |
-| Shipped | Tools, resources, prompts; tool annotations; progress on `dispatch_fix`; scope-aware errors; stdio + Streamable HTTP; `outputSchema` / `structuredContent` on key tools; inventory action anchors on `dispatch_fix` / `get_fix_context` |
-| Waiting on clients | Resource subscriptions / `list_changed` push; sampling / elicitation |
-Detail and tool tables: [docs `/sdks/mcp`](https://kensaur.us/mushi-mushi/docs/sdks/mcp) and the generated [MCP tools reference](https://kensaur.us/mushi-mushi/docs/sdks/mcp-tools) page. Open an issue for a waiting-on-clients row once ≥2 major clients ship support.
-## Admin console: `/mcp` page
-The admin app ships an `/mcp` page (sidebar → **Act → MCP**) with connection status, install snippets, the use-case table above (clickable into the catalog), and the full tool / resource / prompt list from the same `catalog.ts` the server registers.
-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`.
-- **Scope keys tightly.** Give MCP the smallest scope that works; `mcp:read` is fine for 90% of agent loops.
-- **Keep your SDK key (`report:write`) separate from your MCP key.** Your app's Mushi SDK key is embedded in client-side code (e.g. `NEXT_PUBLIC_MUSHI_API_KEY`) and should carry only `report:write` scope. This scope is intentionally rejected by every admin route; so even if extracted from a browser bundle, it cannot triage, dispatch fixes, or mutate report status. Mint a dedicated `mcp:write` key for Cursor/Claude (use the **"⚡ Add to Cursor"** deeplink on the `/mcp` console page; it mints one automatically). If you discover your public SDK key carries `mcp:write`, rotate it immediately.
-- Never paste a service-role key; it bypasses RLS on every table.
-- 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
-# 49/49 pass; handshake, tool contracts, envelope unwrapping, scope errors, annotation contract, outputSchema, catalog parity
-```
-### 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; prints live tool/resource/prompt counts from the catalog
-# (see packages/mcp/src/catalog.ts — currently 117 tools / 8 resources / 4 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.
+| `triage_next_steps` | What needs attention right now, from the live queue |
+| `get_fix_context` | One brief for a report: root cause, repro, the smallest set of files |
+| `triage_issue` | Everything about one report: evidence, similar bugs, blast radius, logs, next actions |
+| `dispatch_fix` / `merge_fix` | Have an agent open a draft PR, then merge it and close the report |
+| `diagnose_setup` | Explains a broken install and the one next step |
+| `search_mushi_docs` | Answers setup and API questions from the docs |
-```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.
+The full catalog has 117 tools, plus 8 resources (`project://dashboard`, `project://stats`, …) and 4 prompts (`summarize_report_for_fix`, `triage_next_steps`, …). Every tool carries read-only and destructive hints, so your editor can ask before it changes anything. Full list: [MCP tool reference](https://kensaur.us/mushi-mushi/docs/sdks/mcp-tools).
-## Configuring against your own localhost
+**Tool groups.** New installs get a lean default: `triage`, `fixes`, `inventory`, `setup`, `docs`. Turn on more with `MUSHI_FEATURES=triage,qa,codebase` (stdio) or `?features=…` on the hosted URL, or everything with `all`. Groups: `qa`, `skills`, `codebase`, `rewards`, `admin`, `audit`, `usage`. Add `?read_only=1` to the hosted URL to hide every write tool.
-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:
+## Keys and safety
-| 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. |
+| Scope | Can do | Give it to |
+| --- | --- | --- |
+| `report:write` | Send reports only. No admin access | Your app's SDK. Never an MCP client |
+| `mcp:read` | Every read tool and resource | Most agent loops |
+| `mcp:write` | Reads plus `dispatch_fix`, `merge_fix`, `transition_status` and other changes | Agents that should act on bugs |
-### Minting a localhost key
+A key without the needed scope gets a clear `INSUFFICIENT_SCOPE` error, never a silent failure. Your SDK key ships in your app's bundle, so it must never carry `mcp:write`; the console mints MCP keys separately. Never use a Supabase service-role key. If a laptop is lost, rotate the key in the console.
-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`.
+## Troubleshooting
-### Pointing Cursor/Claude Desktop at localhost
+- **No tools showing?** Check the MCP panel for a green dot, then fully restart the editor after any config change.
+- **Keep one config.** Put the Mushi entry in your global `~/.cursor/mcp.json` only; a second copy in a project file can cause connection storms.
+- **Windows paths** in JSON need forward slashes (`C:/Users/...`) or escaped backslashes.
+- **Still stuck?** Ask your editor to run `diagnose_setup`, or run `mushi doctor --mcp`.
-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:
+## Programmatic use
-```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_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.
-## Debug MCP logs in Cursor
-If tools are not showing up or returning unexpected errors:
-1. **Check the Cursor MCP logs**: Cursor → Help → Toggle Developer Tools → Console. Filter by `mushi`.
-2. **Verify the server started**: In the MCP panel (Cursor → Settings → MCP), look for a green dot next to the Mushi server.
-3. **Check scope errors**: A `INSUFFICIENT_SCOPE` response means your API key lacks the required scope; mint a new key with `mcp:read` (or `mcp:write` for mutating tools).
-4. **Run the health check**: `/test-mushi-mcp` command or call `list_projects`; a clean response confirms auth is working.
-5. **Restart Cursor**: After changing environment variables or `mcp.json`, restart Cursor to pick up the new config.
-## Mushi vs Sentry MCP
-| | Sentry MCP | Mushi MCP |
-|--|-----------|-----------|
-| Signal source | Thrown exceptions | User-felt bugs (rage-click, console errors, network failures flagged by real users) |
-| Evidence | Stack traces, breadcrumbs | Screenshots, console logs, network excerpts, user comments, replay pointers |
-| Triage tool | `sentry_get_issue` | `triage_issue` (evidence + similar bugs + blast radius + logs + recommended actions) |
-| Fix dispatch | — | `dispatch_fix` → draft GitHub PR → human review |
-| QA coverage | — | QA story runner, PDCA improvement loop |
-Both are complementary; use Sentry for exception noise, Mushi for "the user says it's broken" signal.
+| Import | Exports |
+| --- | --- |
+| `@mushi-mushi/mcp/server` | `createMushiServer()` for a custom host |
+| `@mushi-mushi/mcp/catalog` | `TOOL_CATALOG`, scopes and tool specs |
+| `@mushi-mushi/mcp/feature-groups` | Feature-group filtering |
+| `@mushi-mushi/mcp/clients` | The supported editors and how each one installs |
+| `@mushi-mushi/mcp/branding` | Icons and server metadata |
-## See also
+## Learn more
-- [Fix orchestrator](https://kensaur.us/mushi-mushi/docs/concepts/fix-orchestrator); the agentic fix architecture this server feeds into.
-- [MCP tool reference](https://kensaur.us/mushi-mushi/docs/sdks/mcp-tools); every tool's parameters, generated from the catalog.
-- [`@mushi-mushi/agents`](https://www.npmjs.com/package/@mushi-mushi/agents); orchestrator that consumes MCP-exposed fix workers.
+[MCP guide](https://kensaur.us/mushi-mushi/docs/sdks/mcp) · [MCP quickstart](https://kensaur.us/mushi-mushi/docs/quickstart/mcp) · [The incident loop](https://kensaur.us/mushi-mushi/docs/quickstart/incident-loop) · [Fix orchestrator](https://kensaur.us/mushi-mushi/docs/concepts/fix-orchestrator)
 ## License
 MIT
-<!-- mushi-readme-stats-footer -->
----
-<sub>Monorepo scale (July 2026): 64 edge functions · 422 SQL migrations · 13 outbound plugins · 11 inbound adapters · 19 pipeline agents. 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/catalog.js CHANGED Viewed

@@ -8,7 +8,7 @@ import {
   TOOL_CATALOG,
   USE_MUSHI_INTENTS,
   routeUseMushiIntent
-} from "./chunk-3IVSUYFV.js";
+} from "./chunk-V3M4GZBV.js";
 export {
   ALL_SCOPES,
   CODEBASE_TOOL_CATALOG,

package/dist/{chunk-3IVSUYFV.js → chunk-V3M4GZBV.js} RENAMED Viewed

@@ -820,7 +820,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "list_byok_keys",
     title: "List your API key pool",
-    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | firecrawl | browserbase | cursor | supabase). Returns pooled { keys: [{ id, provider_slug, label, priority, status, cooldown_until, test_status, key_hint, base_url, last_tested_at, last_used_at }] } plus read-only { legacyKeys } metadata for credentials saved before the pooled lifecycle \u2014 never the raw secret. Read-only. Use to see which keys are validated, active, pending, legacy, or rate-limited; use add_byok_key to add one.",
+    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | openrouter | firecrawl | browserbase | cursor | supabase). Returns pooled { keys: [{ id, provider_slug, label, priority, status, cooldown_until, test_status, key_hint, base_url, last_tested_at, last_used_at }] } plus read-only { legacyKeys } metadata for credentials saved before the pooled lifecycle \u2014 never the raw secret. Read-only. Use to see which keys are validated, active, pending, legacy, or rate-limited; use add_byok_key to add one.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which API keys are active and which are rate-limited?"
@@ -828,7 +828,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "add_byok_key",
     title: "Add an API key",
-    description: "Add and immediately validate a BYOK API key for anthropic | openai | firecrawl | browserbase | cursor | supabase (a scoped, read-only Supabase access token, checked against the linked supabase_project_ref). The raw key is stored encrypted in Supabase Vault and never returned; failed probes remain quarantined. Optional baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. Write; NOT idempotent.",
+    description: "Add and immediately validate a BYOK API key for anthropic | openai | openrouter | firecrawl | browserbase | cursor | supabase (a scoped, read-only Supabase access token, checked against the linked supabase_project_ref). The raw key is stored encrypted in Supabase Vault and never returned; failed probes remain quarantined. Optional baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. Write; NOT idempotent.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Add a backup Anthropic key to the pool."

package/dist/clients.d.ts CHANGED Viewed

@@ -46,7 +46,7 @@ import { FeatureGroup } from './feature-groups.js';
  * editor launch. Synced to package.json by `scripts/sync-mcp-pin.mjs` — never
  * hand-edit the version.
  */
-declare const MCP_PIN_SPEC = "@mushi-mushi/mcp@0.24.3";
+declare const MCP_PIN_SPEC = "@mushi-mushi/mcp@0.24.5";
 interface StdioConfig {
     command: string;
     args: string[];

package/dist/clients.js CHANGED Viewed

@@ -8,7 +8,7 @@ import {
 } from "./chunk-F65T4IGT.js";
 // src/clients.ts
-var MCP_PIN_SPEC = "@mushi-mushi/mcp@0.24.3";
+var MCP_PIN_SPEC = "@mushi-mushi/mcp@0.24.5";
 var PIN_SPEC_RE = /^@mushi-mushi\/mcp@\d+\.\d+\.\d+$/;
 function pinOf(pinSpec) {
   return pinSpec && PIN_SPEC_RE.test(pinSpec) ? pinSpec : MCP_PIN_SPEC;

package/dist/index.js CHANGED Viewed

@@ -812,7 +812,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "list_byok_keys",
     title: "List your API key pool",
-    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | firecrawl | browserbase | cursor | supabase). Returns pooled { keys: [{ id, provider_slug, label, priority, status, cooldown_until, test_status, key_hint, base_url, last_tested_at, last_used_at }] } plus read-only { legacyKeys } metadata for credentials saved before the pooled lifecycle \u2014 never the raw secret. Read-only. Use to see which keys are validated, active, pending, legacy, or rate-limited; use add_byok_key to add one.",
+    description: "List the project's BYOK API keys grouped by provider (anthropic | openai | openrouter | firecrawl | browserbase | cursor | supabase). Returns pooled { keys: [{ id, provider_slug, label, priority, status, cooldown_until, test_status, key_hint, base_url, last_tested_at, last_used_at }] } plus read-only { legacyKeys } metadata for credentials saved before the pooled lifecycle \u2014 never the raw secret. Read-only. Use to see which keys are validated, active, pending, legacy, or rate-limited; use add_byok_key to add one.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which API keys are active and which are rate-limited?"
@@ -820,7 +820,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "add_byok_key",
     title: "Add an API key",
-    description: "Add and immediately validate a BYOK API key for anthropic | openai | firecrawl | browserbase | cursor | supabase (a scoped, read-only Supabase access token, checked against the linked supabase_project_ref). The raw key is stored encrypted in Supabase Vault and never returned; failed probes remain quarantined. Optional baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. Write; NOT idempotent.",
+    description: "Add and immediately validate a BYOK API key for anthropic | openai | openrouter | firecrawl | browserbase | cursor | supabase (a scoped, read-only Supabase access token, checked against the linked supabase_project_ref). The raw key is stored encrypted in Supabase Vault and never returned; failed probes remain quarantined. Optional baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. Write; NOT idempotent.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Add a backup Anthropic key to the pool."
@@ -1674,7 +1674,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/admin/inventory",
     markdown: "admin/inventory.md",
     keywords: ["admin", "inventory", "user", "stories"],
-    headings: ["What you see", "Run gates / Run crawler from a row", "SDK-driven discovery", "Surface mode in the graph", "Five gates", "Synthetic monitor", "Spec traceability \u2014 every fix carries the originating Action", "See also"],
+    headings: ["What you see", "Run gates / Run crawler", "SDK-driven discovery", "Surface mode in the graph", "Five gates", "Synthetic monitor", "Spec traceability \u2014 every fix carries the originating Action", "See also"],
     excerpt: "The User stories page manages your inventory.yaml \u2014 every page, action and story your app should have \u2014 and shows which of them the gates cover."
   },
   {
@@ -1929,6 +1929,15 @@ var MUSHI_DOCS_INDEX = [
     headings: ["Providers", "Configuring a custom bucket", "Required IAM permissions (S3)", "Required R2 permissions", "Required GCS permissions", "Data residency", "Related pages"],
     excerpt: "The Storage page chooses where Mushi keeps report attachments and recordings \u2014 managed storage, or your own bucket for residency or cost."
   },
+  {
+    title: "Team",
+    url: docUrl("/admin/team"),
+    route: "/admin/team",
+    markdown: "admin/team.md",
+    keywords: ["admin", "team"],
+    headings: [],
+    excerpt: "The Team page in the Mushi console brings members, billing, AI spend, audit log, single sign-on, compliance and storage together as views of one page."
+  },
   {
     title: "Teams and Members",
     url: docUrl("/admin/teams"),
@@ -1947,6 +1956,15 @@ var MUSHI_DOCS_INDEX = [
     headings: ["Metrics row", "User directory", "User detail drawer", "API", "Related pages"],
     excerpt: "The Users page is an operator-only directory of every Mushi account with plan, MRR and churn; other visitors see a not-found page instead."
   },
+  {
+    title: "UX runs",
+    url: docUrl("/admin/ux-runs"),
+    route: "/admin/ux-runs",
+    markdown: "admin/ux-runs.md",
+    keywords: ["admin", "ux-runs", "runs", "ux"],
+    headings: ["Run in the cloud", "What you see", "File as bug", "Where the changes are"],
+    excerpt: "Each screen your coding agent worked on in a mushi ux run, with its plan, every attempt, before and after screenshots, and what was kept."
+  },
   {
     title: "Voice intake",
     url: docUrl("/admin/voice"),
@@ -3123,8 +3141,8 @@ var MUSHI_DOCS_INDEX = [
     route: "/security/byok",
     markdown: "security/byok.md",
     keywords: ["security", "byok", "bring-your-own-key"],
-    headings: ["Setup", "What uses the key", "Audit trail", "Rotation", "Langfuse trace attribution"],
-    excerpt: "Use your own Anthropic or OpenAI API key for a Mushi project, so every classification, judge and fix run bills to your provider account."
+    headings: ["Setup", "What uses the key", "OpenRouter", "Audit trail", "Rotation", "Langfuse trace attribution"],
+    excerpt: "Use your own Anthropic, OpenAI or OpenRouter key for a Mushi project, so every diagnosis, fix and grading run bills to your provider account."
   },
   {
     title: "Data residency",
@@ -6693,7 +6711,7 @@ Be specific. No generic advice.`
       annotations: annotationsFor("add_byok_key", TDD_TOOL_CATALOG),
       inputSchema: z.object({
         projectId: z.string().describe("Project id"),
-        provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor", "supabase"]).describe("Provider slug"),
+        provider: z.enum(["anthropic", "openai", "openrouter", "firecrawl", "browserbase", "cursor", "supabase"]).describe("Provider slug"),
         key: z.string().min(8).max(4096).describe("The API key value to add"),
         label: z.string().optional().describe("Human-readable label for this key"),
         priority: z.number().int().min(0).max(1e4).optional().describe("Priority for ordering (lower = higher priority)"),
@@ -7523,7 +7541,7 @@ function createSetupModeServer(config) {
     features: "all",
     ...config.fetch ? { fetch: config.fetch } : {},
     ...config.timeoutMs ? { timeoutMs: config.timeoutMs } : {},
-    instructions: "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
+    instructions: config.reason === "sdk-key" ? "Mushi is running in setup mode: the configured API key is an SDK key (report:write). It can send bug reports but not read them, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for how to mint an MCP key (mcp:read), then restart the MCP server." : "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
   });
   const internals = server;
   for (const [name, tool] of Object.entries(internals._registeredTools)) {
@@ -7538,7 +7556,8 @@ function createSetupModeServer(config) {
   }
   const spec = TOOL_CATALOG.find((t) => t.name === "diagnose_setup");
   if (!spec) throw new Error("[mushi-mcp] diagnose_setup is missing from TOOL_CATALOG");
-  const nextAction = "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
+  const sdkKey = config.reason === "sdk-key";
+  const nextAction = sdkKey ? `Mint an MCP key in the console (${MUSHI_CONSOLE_URL}/mcp \u2192 "Mint mcp:read key") or run \`mushi login\`, put it in MUSHI_API_KEY for this server, then restart it.` : "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
   server.registerTool(
     "diagnose_setup",
     {
@@ -7560,7 +7579,12 @@ function createSetupModeServer(config) {
         ready: false,
         mode: "setup",
         steps: [
-          {
+          sdkKey ? {
+            label: "MCP server key can read reports (mcp:read)",
+            complete: false,
+            required: true,
+            hint: `${nextAction} The SDK key (report:write) belongs in your app; MCP and the CLI need a key with mcp:read, or mcp:write to also triage and dispatch fixes.`
+          } : {
             label: "MCP server has an API key",
             complete: false,
             required: true,
@@ -7577,6 +7601,50 @@ function createSetupModeServer(config) {
   return server;
 }
+// src/key-scopes.ts
+async function fetchKeyScopes(opts) {
+  const doFetch = opts.fetch ?? fetch;
+  try {
+    const res = await doFetch(`${opts.apiEndpoint.replace(/\/+$/, "")}/v1/sync/whoami`, {
+      headers: {
+        "X-Mushi-Api-Key": opts.apiKey,
+        ...opts.projectId ? { "X-Mushi-Project-Id": opts.projectId } : {}
+      },
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 5e3)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const scopes = body?.data?.scopes;
+    if (!Array.isArray(scopes)) return null;
+    return scopes.filter((s) => typeof s === "string");
+  } catch {
+    return null;
+  }
+}
+function decideScopes(keyScopes, configured) {
+  if (keyScopes === null) return { kind: "serve", scopes: configured };
+  const granted = /* @__PURE__ */ new Set();
+  if (keyScopes.includes("mcp:write")) {
+    granted.add("mcp:read");
+    granted.add("mcp:write");
+  } else if (keyScopes.includes("mcp:read")) {
+    granted.add("mcp:read");
+  }
+  if (granted.size === 0) return { kind: "sdk-key", keyScopes };
+  return { kind: "serve", scopes: configured.filter((s) => granted.has(s)) };
+}
+function sdkKeyReport(keyScopes, consoleUrl) {
+  const held = keyScopes.length > 0 ? keyScopes.join(", ") : "none";
+  return [
+    "",
+    `[mushi-mcp] This API key has scopes: ${held}. It can send bug reports (the SDK key) but not read them,`,
+    "            so the MCP tools would all be refused. Serving setup mode.",
+    `            Fix: mint an MCP key in the console (${consoleUrl}/mcp \u2192 "Mint mcp:read key"),`,
+    "            or run `mushi login`, then put it in MUSHI_API_KEY for this server and restart it.",
+    ""
+  ].join("\n");
+}
 // src/inventory-poll.ts
 function startInventoryPoll(options) {
   const doFetch = options.fetch ?? globalThis.fetch;
@@ -7836,6 +7904,23 @@ async function main() {
       );
     }
   }
+  let scopes = SCOPES;
+  if (!SCOPES_RAW) {
+    const keyScopes = await fetchKeyScopes({ apiEndpoint: API_ENDPOINT, apiKey: API_KEY, projectId: PROJECT_ID || void 0 });
+    const decision = decideScopes(keyScopes, SCOPES);
+    if (decision.kind === "sdk-key") {
+      const report = sdkKeyReport(decision.keyScopes, MUSHI_CONSOLE_URL);
+      process.stderr.write(report);
+      log.warn("The API key has no MCP scope (mcp:read / mcp:write) \u2014 serving setup mode.", {
+        keyScopes: decision.keyScopes.join(",")
+      });
+      serveUntilClosed(serveStdio(() => createSetupModeServer({ version: VERSION, missingKeyReport: report, reason: "sdk-key" }), {
+        onerror: (err) => log.error("stdio transport error", { err: String(err) })
+      }));
+      return;
+    }
+    scopes = decision.scopes;
+  }
   const mode = PROJECT_ID ? "single-project" : "account";
   if (!PROJECT_ID) {
     log.info(
@@ -7847,7 +7932,7 @@ async function main() {
     mode,
     endpoint: API_ENDPOINT,
     hasProjectId: !!PROJECT_ID,
-    scopes: SCOPES.join(",")
+    scopes: scopes.join(",")
   });
   let server;
   const handle = serveStdio(
@@ -7857,7 +7942,7 @@ async function main() {
         apiEndpoint: API_ENDPOINT,
         apiKey: API_KEY,
         projectId: PROJECT_ID || void 0,
-        scopes: SCOPES,
+        scopes,
         features: FEATURES
       });
       log.debug("[mushi-mcp] server instance created", { era: ctx.era });

package/dist/server.d.ts CHANGED Viewed

@@ -63,10 +63,16 @@ interface MushiServerConfig {
 declare function createMushiServer(config: MushiServerConfig): McpServer;
 /** Tools that work before an API key exists: they read only the public docs. */
 declare const SETUP_MODE_TOOLS: readonly ["search_mushi_docs", "get_mushi_doc", "diagnose_setup"];
+declare const MUSHI_CONSOLE_URL = "https://kensaur.us/mushi-mushi/admin";
 interface SetupModeServerConfig {
     version: string;
     /** Why there is no key, as printed to stderr (sources checked, config path). */
     missingKeyReport: string;
+    /**
+     * `missing-key` (default): no key reached the server. `sdk-key`: a valid
+     * key without mcp:read or mcp:write, such as the report:write SDK key.
+     */
+    reason?: 'missing-key' | 'sdk-key';
     fetch?: typeof fetch;
     timeoutMs?: number;
 }
@@ -78,4 +84,4 @@ interface SetupModeServerConfig {
  */
 declare function createSetupModeServer(config: SetupModeServerConfig): McpServer;
-export { MushiApiError, type MushiServerConfig, SETUP_MODE_TOOLS, type SetupModeServerConfig, createMushiServer, createSetupModeServer, resolveTimeoutMsFromEnv };
+export { MUSHI_CONSOLE_URL, MushiApiError, type MushiServerConfig, SETUP_MODE_TOOLS, type SetupModeServerConfig, createMushiServer, createSetupModeServer, resolveTimeoutMsFromEnv };

package/dist/server.js CHANGED Viewed

@@ -4,7 +4,7 @@ import {
   TDD_TOOL_CATALOG,
   TOOL_CATALOG,
   routeUseMushiIntent
-} from "./chunk-3IVSUYFV.js";
+} from "./chunk-V3M4GZBV.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-FJRPC4VR.js";
@@ -284,7 +284,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/admin/inventory",
     markdown: "admin/inventory.md",
     keywords: ["admin", "inventory", "user", "stories"],
-    headings: ["What you see", "Run gates / Run crawler from a row", "SDK-driven discovery", "Surface mode in the graph", "Five gates", "Synthetic monitor", "Spec traceability \u2014 every fix carries the originating Action", "See also"],
+    headings: ["What you see", "Run gates / Run crawler", "SDK-driven discovery", "Surface mode in the graph", "Five gates", "Synthetic monitor", "Spec traceability \u2014 every fix carries the originating Action", "See also"],
     excerpt: "The User stories page manages your inventory.yaml \u2014 every page, action and story your app should have \u2014 and shows which of them the gates cover."
   },
   {
@@ -539,6 +539,15 @@ var MUSHI_DOCS_INDEX = [
     headings: ["Providers", "Configuring a custom bucket", "Required IAM permissions (S3)", "Required R2 permissions", "Required GCS permissions", "Data residency", "Related pages"],
     excerpt: "The Storage page chooses where Mushi keeps report attachments and recordings \u2014 managed storage, or your own bucket for residency or cost."
   },
+  {
+    title: "Team",
+    url: docUrl("/admin/team"),
+    route: "/admin/team",
+    markdown: "admin/team.md",
+    keywords: ["admin", "team"],
+    headings: [],
+    excerpt: "The Team page in the Mushi console brings members, billing, AI spend, audit log, single sign-on, compliance and storage together as views of one page."
+  },
   {
     title: "Teams and Members",
     url: docUrl("/admin/teams"),
@@ -557,6 +566,15 @@ var MUSHI_DOCS_INDEX = [
     headings: ["Metrics row", "User directory", "User detail drawer", "API", "Related pages"],
     excerpt: "The Users page is an operator-only directory of every Mushi account with plan, MRR and churn; other visitors see a not-found page instead."
   },
+  {
+    title: "UX runs",
+    url: docUrl("/admin/ux-runs"),
+    route: "/admin/ux-runs",
+    markdown: "admin/ux-runs.md",
+    keywords: ["admin", "ux-runs", "runs", "ux"],
+    headings: ["Run in the cloud", "What you see", "File as bug", "Where the changes are"],
+    excerpt: "Each screen your coding agent worked on in a mushi ux run, with its plan, every attempt, before and after screenshots, and what was kept."
+  },
   {
     title: "Voice intake",
     url: docUrl("/admin/voice"),
@@ -1733,8 +1751,8 @@ var MUSHI_DOCS_INDEX = [
     route: "/security/byok",
     markdown: "security/byok.md",
     keywords: ["security", "byok", "bring-your-own-key"],
-    headings: ["Setup", "What uses the key", "Audit trail", "Rotation", "Langfuse trace attribution"],
-    excerpt: "Use your own Anthropic or OpenAI API key for a Mushi project, so every classification, judge and fix run bills to your provider account."
+    headings: ["Setup", "What uses the key", "OpenRouter", "Audit trail", "Rotation", "Langfuse trace attribution"],
+    excerpt: "Use your own Anthropic, OpenAI or OpenRouter key for a Mushi project, so every diagnosis, fix and grading run bills to your provider account."
   },
   {
     title: "Data residency",
@@ -5369,7 +5387,7 @@ Be specific. No generic advice.`
       annotations: annotationsFor("add_byok_key", TDD_TOOL_CATALOG),
       inputSchema: z.object({
         projectId: z.string().describe("Project id"),
-        provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor", "supabase"]).describe("Provider slug"),
+        provider: z.enum(["anthropic", "openai", "openrouter", "firecrawl", "browserbase", "cursor", "supabase"]).describe("Provider slug"),
         key: z.string().min(8).max(4096).describe("The API key value to add"),
         label: z.string().optional().describe("Human-readable label for this key"),
         priority: z.number().int().min(0).max(1e4).optional().describe("Priority for ordering (lower = higher priority)"),
@@ -6199,7 +6217,7 @@ function createSetupModeServer(config) {
     features: "all",
     ...config.fetch ? { fetch: config.fetch } : {},
     ...config.timeoutMs ? { timeoutMs: config.timeoutMs } : {},
-    instructions: "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
+    instructions: config.reason === "sdk-key" ? "Mushi is running in setup mode: the configured API key is an SDK key (report:write). It can send bug reports but not read them, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for how to mint an MCP key (mcp:read), then restart the MCP server." : "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
   });
   const internals = server;
   for (const [name, tool] of Object.entries(internals._registeredTools)) {
@@ -6214,7 +6232,8 @@ function createSetupModeServer(config) {
   }
   const spec = TOOL_CATALOG.find((t) => t.name === "diagnose_setup");
   if (!spec) throw new Error("[mushi-mcp] diagnose_setup is missing from TOOL_CATALOG");
-  const nextAction = "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
+  const sdkKey = config.reason === "sdk-key";
+  const nextAction = sdkKey ? `Mint an MCP key in the console (${MUSHI_CONSOLE_URL}/mcp \u2192 "Mint mcp:read key") or run \`mushi login\`, put it in MUSHI_API_KEY for this server, then restart it.` : "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
   server.registerTool(
     "diagnose_setup",
     {
@@ -6236,7 +6255,12 @@ function createSetupModeServer(config) {
         ready: false,
         mode: "setup",
         steps: [
-          {
+          sdkKey ? {
+            label: "MCP server key can read reports (mcp:read)",
+            complete: false,
+            required: true,
+            hint: `${nextAction} The SDK key (report:write) belongs in your app; MCP and the CLI need a key with mcp:read, or mcp:write to also triage and dispatch fixes.`
+          } : {
             label: "MCP server has an API key",
             complete: false,
             required: true,
@@ -6253,6 +6277,7 @@ function createSetupModeServer(config) {
   return server;
 }
 export {
+  MUSHI_CONSOLE_URL,
   MushiApiError,
   SETUP_MODE_TOOLS,
   createMushiServer,

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
   "mcpName": "io.github.kensaurus/mushi-mushi",
-  "version": "0.24.3",
+  "version": "0.24.5",
   "license": "MIT",
   "description": "MCP server for Cursor, Claude Code and Copilot. The bug mediator for AI-built apps: plain-English diagnosis + a ready fix, in your editor.",
   "type": "module",
@@ -45,7 +45,7 @@
     "@modelcontextprotocol/core": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
-    "@mushi-mushi/core": "^1.31.0"
+    "@mushi-mushi/core": "^1.32.0"
   },
   "peerDependencies": {
     "@sentry/node": "^10.57.0"