@mushi-mushi/mcp 0.15.0 → 0.16.1

package/CONTRIBUTING.md

@@ -58,12 +58,12 @@ packages/
   react-native/  React Native SDK (MIT)
   cli/           CLI tool (MIT)
   mcp/           MCP server for coding agents (MIT)
-  server/        Supabase Edge Functions (BSL)
-  agents/        Agentic fix pipeline (BSL)
-  verify/        Fix verification (BSL)
+  server/        Supabase Edge Functions (AGPLv3)
+  agents/        Agentic fix pipeline (AGPLv3)
+  verify/        Fix verification (AGPLv3)
 apps/
   admin/         Admin dashboard (React + Tailwind)
-  docs/          Documentation site (planned)
+  docs/          Documentation site (Nextra — apps/docs)
 tooling/
   eslint-config/ Shared ESLint flat config
   tsconfig/      Shared TypeScript configs
@@ -81,6 +81,30 @@ tooling/
    ```
 6. Open a pull request
 
+### Documentation (docs-as-code)
+
+If your PR changes **user-visible SDK or CLI behavior**, update docs in the **same PR**:
+
+| Surface | When to update |
+| --- | --- |
+| `packages/*/README.md` | npm-facing install/API/config changes for that package |
+| `apps/docs/content/**/*.mdx` | Long-form guides, quickstarts, admin console docs |
+| Root `README.md` | Marketing stats only when counts change — run `pnpm check:docs-stats` |
+
+Guardrails (run locally before pushing):
+
+```bash
+pnpm check:docs-stats          # root README stat badges
+pnpm check:sdk-version-matrix  # apps/docs/content/sdks/index.mdx versions
+pnpm check:internal-doc-links  # dead /foo links in MDX
+pnpm check:onboarding-drift    # phantom MCP env vars / stale tool names
+pnpm check:bundle-docs         # @mushi-mushi/web size-limit vs README
+pnpm gen:llms-txt              # regenerate apps/docs/public/llms.txt after nav changes
+pnpm gen:mcp-tools-doc         # regenerate sdks/mcp-tools.generated.mdx from catalog.ts
+```
+
+README changes on npm packages only appear on [npmjs.com](https://www.npmjs.com) after the next **Changesets publish**.
+
 ## Changesets
 
 We use [Changesets](https://github.com/changesets/changesets) for versioning. If your PR modifies a published package (`core`, `web`, `react`, `vue`, `svelte`, `angular`, `react-native`, `cli`, `mcp`), add a changeset:
@@ -93,13 +117,30 @@ Select the affected packages, the semver bump type, and write a summary. The cha
 
 ## Release flow
 
-Releases are fully automated. Maintainers don't run `npm publish` by hand.
+Releases are fully automated once the version PR is merged. Maintainers don't run
+`npm publish` by hand for routine bumps. See **[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)**
+for the full production runbook (edge functions, admin SPA, docs site, migrations).
 
 1. PRs land on `master` with one or more changeset files in `.changeset/`.
-2. `release.yml` runs on every push to `master`. It opens (or updates) a `chore: version packages` PR that bumps every affected `package.json`, rolls up the changelogs, and deletes the consumed changesets.
-3. Merging that "Version Packages" PR re-fires `release.yml`. The publish step authenticates to npm via **OpenID Connect (OIDC) Trusted Publishers** — no long-lived `NPM_TOKEN` is exchanged — and every tarball ships with a **Sigstore provenance attestation** uploaded to the public transparency log.
+   Orphaned changesets (only ignored packages) fail `pnpm check:changeset-orphans`.
+2. `release.yml` runs on every push to `master`. It opens (or updates) a
+   **`chore: version packages`** PR on `changeset-release/master` that bumps
+   affected `package.json` files, rolls up changelogs, and deletes consumed
+   changesets.
+3. **Wait for CI on the version PR.** If checks don't appear (bot-branch
+   suppression), push an empty commit to `changeset-release/master`. If
+   `check:sdk-version-matrix` fails, run `pnpm gen:sdk-version-matrix` on that
+   branch and commit `apps/docs/content/sdks/index.mdx`.
+4. Merge the version PR. The publish step uses **OIDC Trusted Publishers** +
+   Sigstore provenance (with `NPM_TOKEN` only for brand-new package bootstrap).
+5. **Manually dispatch Release** unless a run starts within ~2 minutes:
+   **Actions → Release → Run workflow → `master`**. Squash-merges attributed to
+   `github-actions[bot]` usually suppress the auto `push` trigger — manual
+   dispatch is the normal path, not a fallback of last resort.
 
-If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
+```bash
+gh workflow run release.yml --ref master
+```
 
 ### Adding a brand-new publishable package
 
@@ -146,7 +187,7 @@ chore: bump dependencies
 ## License
 
 - SDK packages are MIT — your contributions will be MIT-licensed
-- Server/agents/verify are BSL 1.1 — contributions to those packages fall under BSL
+- Server/agents/verify are AGPLv3 — contributions to those packages fall under AGPLv3
 
 ## Questions?
 

package/README.md

@@ -1,13 +1,8 @@
 # @mushi-mushi/mcp
 
-> **Sentry sees what code throws. Mushi sees what users feel — and closes the loop with AI.**
+> **Your AI wrote it. Mushi tells you why it broke.**
 
-[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi's **evolution loop** into your AI coding agent. The loop is already running in your Mushi project:
-
-```
-User feels a bug → Mushi captures it → AI triages → AI opens a PR
-→ QA verifies → Judge scores → Lesson library remembers → next agent is smarter
-```
+[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi into Cursor, Claude Code, and any MCP client. Pull fix context, run triage, and dispatch fixes without a second LLM vendor key.
 
 Wire it into Cursor, Claude Code, or any MCP client in one command:
 
@@ -16,7 +11,7 @@ npx mushi-mushi setup --ide cursor
 # or: npx mushi-mushi setup --ide claude
 ```
 
-That command reads `~/.mushirc`, writes `.cursor/mcp.json` with the `mushi` server block, and prints "Done — restart Cursor and ask: `list mushi tools`". No copy-pasting environment variables.
+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.
 
 ### Codebase Understand tools (indexed repos)
 
@@ -146,7 +141,7 @@ The Mushi backend now exposes the same tool catalog over the **Streamable HTTP**
 
 ### Feature groups (`?features=` / `MUSHI_FEATURES`)
 
-Full catalog is **72 tools** (64 core + 8 project-context tools). New installs default to a lean set via:
+Full catalog is **71 tools**. New installs default to a lean set via:
 
 - **Stdio:** `MUSHI_FEATURES=triage,fixes,inventory,setup,docs`
 - **HTTP:** `?features=triage,fixes,inventory,setup,docs` on the MCP URL
@@ -157,6 +152,17 @@ New unified tools: `diagnose_setup` (replaces setup trilogy), `search_mushi_docs
 
 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.

package/dist/catalog.js

@@ -5,7 +5,7 @@ import {
   RESOURCE_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-FD6GVGQS.js";
+} from "./chunk-UYZEIJ5G.js";
 export {
   ALL_SCOPES,
   CODEBASE_TOOL_CATALOG,

package/dist/{chunk-FD6GVGQS.js → chunk-UYZEIJ5G.js}

@@ -44,7 +44,7 @@ var TOOL_CATALOG = [
   {
     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.",
+    description: "Bundle the full context an agent needs to fix a bug: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, reproduction steps, component, root cause, and ontology tags. One call instead of several. No second LLM key needed.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me everything I need to fix this in one payload."
@@ -274,7 +274,7 @@ var TOOL_CATALOG = [
   {
     name: "list_projects",
     title: "List accessible projects",
-    description: `List the Mushi projects accessible to this API key. For project-scoped keys (the typical case), returns a single-item list with the bound project's id, name, created_at. Use this when MUSHI_PROJECT_ID is not configured \u2014 call list_projects first, then pass the id to other tools. Multi-project note: each Mushi project uses its own API key. To connect multiple projects, run "Add to Cursor" in the Mushi console for each project \u2014 each deeplink creates a uniquely-named MCP server entry (mushi-{slug}-{id}). You can then call list_projects on each named server to confirm which project it serves.`,
+    description: "List all Mushi projects accessible to this API key. For project-scoped keys returns a single-item list; for org-scoped keys (account mode) returns every project owned by this account. Call this first when MUSHI_PROJECT_ID is not configured \u2014 use the returned id with subsequent tool calls. If multiple projects are returned, pass the target projectId explicitly to project-scoped tools. Multi-project tip: run `mushi setup --all-projects` in your terminal to create one named MCP server entry per project in .cursor/mcp.json.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which projects can I access with this API key?"
@@ -282,7 +282,7 @@ var TOOL_CATALOG = [
   {
     name: "get_account_overview",
     title: "Account overview \u2014 all projects",
-    description: "Return a summary of every Mushi project accessible to this API key, including report counts, SDK heartbeat status, and the last ingest timestamp for each. For project-scoped keys this is a one-item list; for future org-level keys it lists every project. Also includes a hint explaining how to connect additional projects to your IDE. Call this at the start of a multi-repo or multi-app triage session to orient yourself.",
+    description: "Return an enriched summary of every Mushi project accessible to this API key: id, name, recent report count (last 30 days), number of connected MCP keys, and last-seen heartbeat timestamp. For project-scoped keys this is a one-item list; for org-scoped (account) keys it lists every owned project. Also includes toolCount, resourceCount, promptCount so agents know how many tools are available. Call this at the start of a multi-repo or multi-app triage session to orient yourself.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me all my Mushi projects and their health at a glance."

package/dist/index.js

@@ -51,7 +51,7 @@ var TOOL_CATALOG = [
   {
     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.",
+    description: "Bundle the full context an agent needs to fix a bug: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, reproduction steps, component, root cause, and ontology tags. One call instead of several. No second LLM key needed.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me everything I need to fix this in one payload."
@@ -281,7 +281,7 @@ var TOOL_CATALOG = [
   {
     name: "list_projects",
     title: "List accessible projects",
-    description: `List the Mushi projects accessible to this API key. For project-scoped keys (the typical case), returns a single-item list with the bound project's id, name, created_at. Use this when MUSHI_PROJECT_ID is not configured \u2014 call list_projects first, then pass the id to other tools. Multi-project note: each Mushi project uses its own API key. To connect multiple projects, run "Add to Cursor" in the Mushi console for each project \u2014 each deeplink creates a uniquely-named MCP server entry (mushi-{slug}-{id}). You can then call list_projects on each named server to confirm which project it serves.`,
+    description: "List all Mushi projects accessible to this API key. For project-scoped keys returns a single-item list; for org-scoped keys (account mode) returns every project owned by this account. Call this first when MUSHI_PROJECT_ID is not configured \u2014 use the returned id with subsequent tool calls. If multiple projects are returned, pass the target projectId explicitly to project-scoped tools. Multi-project tip: run `mushi setup --all-projects` in your terminal to create one named MCP server entry per project in .cursor/mcp.json.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which projects can I access with this API key?"
@@ -289,7 +289,7 @@ var TOOL_CATALOG = [
   {
     name: "get_account_overview",
     title: "Account overview \u2014 all projects",
-    description: "Return a summary of every Mushi project accessible to this API key, including report counts, SDK heartbeat status, and the last ingest timestamp for each. For project-scoped keys this is a one-item list; for future org-level keys it lists every project. Also includes a hint explaining how to connect additional projects to your IDE. Call this at the start of a multi-repo or multi-app triage session to orient yourself.",
+    description: "Return an enriched summary of every Mushi project accessible to this API key: id, name, recent report count (last 30 days), number of connected MCP keys, and last-seen heartbeat timestamp. For project-scoped keys this is a one-item list; for org-scoped (account) keys it lists every owned project. Also includes toolCount, resourceCount, promptCount so agents know how many tools are available. Call this at the start of a multi-repo or multi-app triage session to orient yourself.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me all my Mushi projects and their health at a glance."
@@ -749,14 +749,26 @@ var MUSHI_DOCS_INDEX = [
   {
     title: "MCP setup",
     path: `${BASE}/guides/mcp-setup`,
-    keywords: ["mcp", "cursor", "api key", "stdio", "http"],
-    excerpt: "Wire Mushi MCP into Cursor, Claude, or any MCP client."
+    keywords: ["mcp", "cursor", "api key", "stdio", "http", "multi-project", "account mode", "install", "setup", "deeplink"],
+    excerpt: "Wire Mushi MCP into Cursor, Claude, or any MCP client. Supports per-project and account-level keys."
   },
   {
     title: "API key scopes",
     path: `${BASE}/guides/api-keys`,
-    keywords: ["api key", "mcp:read", "mcp:write", "scopes", "security"],
-    excerpt: "Separate SDK ingest keys from MCP read/write keys."
+    keywords: ["api key", "mcp:read", "mcp:write", "scopes", "security", "account key", "org-scoped", "multi-project"],
+    excerpt: "Separate SDK ingest keys from MCP read/write keys. Mint an org-scoped account key for multi-project access."
+  },
+  {
+    title: "Account key (org-scoped)",
+    path: `${BASE}/guides/mcp-setup`,
+    keywords: ["account key", "org-scoped", "multi-project", "MUSHI_PROJECT_ID", "all projects", "mint-org-key", "get_account_overview"],
+    excerpt: "Mint one org-scoped key that covers all your projects; no MUSHI_PROJECT_ID needed. The agent calls get_account_overview to discover projects."
+  },
+  {
+    title: "Cursor MCP troubleshooting",
+    path: `${BASE}/guides/mcp-setup`,
+    keywords: ["cursor", "mcp.json", "red badge", "transport error", "stdout", "stderr", "json-rpc", "INVALID_TOKEN", "syntax helper", "diagnose_connection"],
+    excerpt: "Cursor stdio MCP requires stdout to contain only JSON-RPC. Use the console syntax helper, restart Cursor MCP, then run diagnose_connection."
   },
   {
     title: "Judge loop",
@@ -848,7 +860,8 @@ function createMushiServer(config) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const apiLog = createLogger({
     scope: "mushi:mcp:api",
-    level: process.env.MUSHI_LOG_LEVEL ?? "info"
+    level: process.env.MUSHI_LOG_LEVEL ?? "info",
+    destination: "stderr"
   });
   if (config.scopes !== void 0 && config.scopes.length === 0) {
     return new McpServer({
@@ -907,6 +920,38 @@ function createMushiServer(config) {
     apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
     return body;
   }
+  async function resolveProjectId(explicitId) {
+    if (explicitId) return explicitId;
+    if (projectId) return projectId;
+    try {
+      const data = await apiCall(
+        "/v1/admin/mcp/account-overview"
+      );
+      if (data.total === 1 && data.projects[0]) {
+        return data.projects[0].id;
+      }
+      if (data.total === 0) {
+        throw new MushiApiError(
+          400,
+          "NO_ACCESSIBLE_PROJECTS",
+          "This API key has no accessible projects. Mint an API key on a project in the admin console."
+        );
+      }
+      const projectList = data.projects.map((p) => `${p.name ?? "unnamed"} (${p.id})`).join(", ");
+      throw new MushiApiError(
+        400,
+        "PROJECT_ID_REQUIRED",
+        `Multiple projects are accessible with this key: ${projectList}. Pass projectId explicitly to target a specific project, or set MUSHI_PROJECT_ID in your MCP env config.`
+      );
+    } catch (err) {
+      if (err instanceof MushiApiError) throw err;
+      throw new MushiApiError(
+        400,
+        "MISSING_PROJECT_ID",
+        "projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly."
+      );
+    }
+  }
   function jsonText(value) {
     return {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -974,8 +1019,8 @@ function createMushiServer(config) {
       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 pid = args.project_id ?? projectId;
-      const extraHeaders = pid && pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
       const data = await apiCall(`/v1/admin/reports?${params}`, {
         headers: extraHeaders
       });
@@ -1086,6 +1131,7 @@ function createMushiServer(config) {
       inputSchema: { reportId: z.string().describe("The report UUID to fix") },
       outputSchema: {
         report: z.unknown(),
+        fixPrompt: z.unknown(),
         reproductionSteps: z.unknown(),
         component: z.unknown(),
         rootCause: z.unknown(),
@@ -1096,6 +1142,10 @@ function createMushiServer(config) {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       return jsonResult({
         report,
+        // Paste-ready fix prompt composed server-side by composeFixPacket()
+        // (diagnosis + repro + suggested fix + relevant code + blast radius).
+        // Hand this straight to the editing agent — no second LLM key needed.
+        fixPrompt: report.fix_packet ?? null,
         reproductionSteps: report.reproduction_steps ?? [],
         component: report.component,
         rootCause: report.stage2_analysis?.rootCause,
@@ -1436,6 +1486,7 @@ function createMushiServer(config) {
         dispatchReady: z.boolean(),
         endpoint: z.string().nullable(),
         projectId: z.string().nullable(),
+        accessibleProjectCount: z.number().nullable(),
         issues: z.array(z.unknown()),
         nextAction: z.string(),
         summary: z.string()
@@ -1450,13 +1501,6 @@ function createMushiServer(config) {
           fix: "Run `mushi connect` to write MUSHI_API_KEY into .cursor/mcp.json, then restart the MCP server."
         });
       }
-      if (!projectId) {
-        issues.push({
-          check: "mcp_project_id",
-          detail: "No projectId configured on the MCP server",
-          fix: "Add MUSHI_PROJECT_ID to .cursor/mcp.json (copy UUID from console \u2192 Projects)."
-        });
-      }
       if (!apiEndpoint) {
         issues.push({
           check: "mcp_endpoint",
@@ -1488,6 +1532,21 @@ function createMushiServer(config) {
       }
       let ingestReady = false;
       let dispatchReady = false;
+      let accessibleProjectCount = null;
+      if (!projectId && healthOk) {
+        try {
+          const overview = await apiCall("/v1/admin/mcp/account-overview");
+          accessibleProjectCount = overview.total;
+          if (overview.total === 0) {
+            issues.push({
+              check: "no_accessible_projects",
+              detail: "API key has no accessible projects",
+              fix: "Mint an API key on a project (console \u2192 Projects \u2192 API Keys) or add MUSHI_PROJECT_ID to restrict to a single project."
+            });
+          }
+        } catch {
+        }
+      }
       try {
         const ingest = await apiCall("/v1/sync/ingest-setup");
         ingestReady = ingest.ready;
@@ -1530,6 +1589,7 @@ function createMushiServer(config) {
         dispatchReady,
         endpoint: apiEndpoint ?? null,
         projectId: projectId ?? null,
+        accessibleProjectCount,
         issues,
         nextAction,
         summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
@@ -1595,16 +1655,24 @@ function createMushiServer(config) {
       inputSchema: {},
       outputSchema: {
         projects: z.array(z.unknown()),
+        total: z.number(),
         active_project_id: z.string().nullable(),
+        toolCount: z.number().optional(),
+        resourceCount: z.number().optional(),
+        promptCount: z.number().optional(),
         multi_project_hint: z.string()
       }
     },
     async () => {
-      const data = await apiCall("/v1/admin/mcp/projects");
+      const data = await apiCall("/v1/admin/mcp/account-overview");
       const projects = Array.isArray(data?.projects) ? data.projects : [];
       return jsonResult({
         projects,
+        total: data?.total ?? projects.length,
         active_project_id: projectId ?? null,
+        toolCount: data?.toolCount,
+        resourceCount: data?.resourceCount,
+        promptCount: data?.promptCount,
         multi_project_hint: projects.length <= 1 ? 'You are currently connected to one project. To connect additional Mushi projects, open the Mushi console \u2192 switch to each project \u2192 MCP \u2192 Setup \u2192 "\u26A1 Add to Cursor". Each click adds a uniquely-named entry (mushi-{name}-{id}) to your global ~/.cursor/mcp.json so you can triage reports across all your apps from a single Cursor session.' : `You have access to ${projects.length} projects. To connect any unconnected project, open the Mushi console \u2192 switch to that project \u2192 MCP \u2192 Setup \u2192 "\u26A1 Add to Cursor".`
       });
     }
@@ -2956,9 +3024,14 @@ Be specific. No generic advice.`
 }
 
 // src/index.ts
+var _writeStderr = (...args) => process.stderr.write(
+  args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") + "\n"
+);
+console.log = _writeStderr;
+console.warn = _writeStderr;
 var require2 = createRequire(import.meta.url);
 var VERSION = require2("../package.json").version;
-var log = createLogger2({ scope: "mushi:mcp", level: "info" });
+var log = createLogger2({ scope: "mushi:mcp", level: "info", destination: "stderr" });
 var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "";
 var API_KEY = process.env.MUSHI_API_KEY ?? "";
 var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
@@ -2976,13 +3049,15 @@ async function main() {
       "[mushi-mcp] MUSHI_API_ENDPOINT is not set. All tool calls will fail.\nSet MUSHI_API_ENDPOINT to your Supabase edge function URL, e.g. https://xyz.supabase.co/functions/v1/api"
     );
   }
+  const mode = PROJECT_ID ? "single-project" : "account";
   if (!PROJECT_ID) {
-    console.error(
-      "[mushi-mcp] MUSHI_PROJECT_ID is not set.\n\nTools that scope to a project (get_recent_reports, get_report_detail,\nsearch_reports, etc.) will require you to pass projectId explicitly on\nevery call. To set it once and never pass it again:\n\n  1. Open the Mushi admin console \u2192 Projects\n     https://kensaur.us/mushi-mushi/projects\n  2. Click your project \u2014 copy the UUID below the project name.\n  3. Add it to your MCP env config:\n       MUSHI_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n\nOr visit Admin \u2192 MCP for a pre-filled config snippet with your actual UUID."
+    log.info(
+      "[mushi-mcp] Running in account mode (no MUSHI_PROJECT_ID set). Project-scoped tools accept an explicit projectId argument. Run `get_account_overview` to see accessible projects."
     );
   }
   log.info("Starting Mushi MCP server", {
     version: VERSION,
+    mode,
     endpoint: API_ENDPOINT || "(unset)",
     hasProjectId: !!PROJECT_ID,
     scopes: SCOPES.join(",")

package/dist/server.js

@@ -2,7 +2,7 @@ import {
   CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-FD6GVGQS.js";
+} from "./chunk-UYZEIJ5G.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EHB2BGWX.js";
@@ -27,14 +27,26 @@ var MUSHI_DOCS_INDEX = [
   {
     title: "MCP setup",
     path: `${BASE}/guides/mcp-setup`,
-    keywords: ["mcp", "cursor", "api key", "stdio", "http"],
-    excerpt: "Wire Mushi MCP into Cursor, Claude, or any MCP client."
+    keywords: ["mcp", "cursor", "api key", "stdio", "http", "multi-project", "account mode", "install", "setup", "deeplink"],
+    excerpt: "Wire Mushi MCP into Cursor, Claude, or any MCP client. Supports per-project and account-level keys."
   },
   {
     title: "API key scopes",
     path: `${BASE}/guides/api-keys`,
-    keywords: ["api key", "mcp:read", "mcp:write", "scopes", "security"],
-    excerpt: "Separate SDK ingest keys from MCP read/write keys."
+    keywords: ["api key", "mcp:read", "mcp:write", "scopes", "security", "account key", "org-scoped", "multi-project"],
+    excerpt: "Separate SDK ingest keys from MCP read/write keys. Mint an org-scoped account key for multi-project access."
+  },
+  {
+    title: "Account key (org-scoped)",
+    path: `${BASE}/guides/mcp-setup`,
+    keywords: ["account key", "org-scoped", "multi-project", "MUSHI_PROJECT_ID", "all projects", "mint-org-key", "get_account_overview"],
+    excerpt: "Mint one org-scoped key that covers all your projects; no MUSHI_PROJECT_ID needed. The agent calls get_account_overview to discover projects."
+  },
+  {
+    title: "Cursor MCP troubleshooting",
+    path: `${BASE}/guides/mcp-setup`,
+    keywords: ["cursor", "mcp.json", "red badge", "transport error", "stdout", "stderr", "json-rpc", "INVALID_TOKEN", "syntax helper", "diagnose_connection"],
+    excerpt: "Cursor stdio MCP requires stdout to contain only JSON-RPC. Use the console syntax helper, restart Cursor MCP, then run diagnose_connection."
   },
   {
     title: "Judge loop",
@@ -126,7 +138,8 @@ function createMushiServer(config) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const apiLog = createLogger({
     scope: "mushi:mcp:api",
-    level: process.env.MUSHI_LOG_LEVEL ?? "info"
+    level: process.env.MUSHI_LOG_LEVEL ?? "info",
+    destination: "stderr"
   });
   if (config.scopes !== void 0 && config.scopes.length === 0) {
     return new McpServer({
@@ -185,6 +198,38 @@ function createMushiServer(config) {
     apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
     return body;
   }
+  async function resolveProjectId(explicitId) {
+    if (explicitId) return explicitId;
+    if (projectId) return projectId;
+    try {
+      const data = await apiCall(
+        "/v1/admin/mcp/account-overview"
+      );
+      if (data.total === 1 && data.projects[0]) {
+        return data.projects[0].id;
+      }
+      if (data.total === 0) {
+        throw new MushiApiError(
+          400,
+          "NO_ACCESSIBLE_PROJECTS",
+          "This API key has no accessible projects. Mint an API key on a project in the admin console."
+        );
+      }
+      const projectList = data.projects.map((p) => `${p.name ?? "unnamed"} (${p.id})`).join(", ");
+      throw new MushiApiError(
+        400,
+        "PROJECT_ID_REQUIRED",
+        `Multiple projects are accessible with this key: ${projectList}. Pass projectId explicitly to target a specific project, or set MUSHI_PROJECT_ID in your MCP env config.`
+      );
+    } catch (err) {
+      if (err instanceof MushiApiError) throw err;
+      throw new MushiApiError(
+        400,
+        "MISSING_PROJECT_ID",
+        "projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly."
+      );
+    }
+  }
   function jsonText(value) {
     return {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -252,8 +297,8 @@ function createMushiServer(config) {
       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 pid = args.project_id ?? projectId;
-      const extraHeaders = pid && pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
       const data = await apiCall(`/v1/admin/reports?${params}`, {
         headers: extraHeaders
       });
@@ -364,6 +409,7 @@ function createMushiServer(config) {
       inputSchema: { reportId: z.string().describe("The report UUID to fix") },
       outputSchema: {
         report: z.unknown(),
+        fixPrompt: z.unknown(),
         reproductionSteps: z.unknown(),
         component: z.unknown(),
         rootCause: z.unknown(),
@@ -374,6 +420,10 @@ function createMushiServer(config) {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       return jsonResult({
         report,
+        // Paste-ready fix prompt composed server-side by composeFixPacket()
+        // (diagnosis + repro + suggested fix + relevant code + blast radius).
+        // Hand this straight to the editing agent — no second LLM key needed.
+        fixPrompt: report.fix_packet ?? null,
         reproductionSteps: report.reproduction_steps ?? [],
         component: report.component,
         rootCause: report.stage2_analysis?.rootCause,
@@ -714,6 +764,7 @@ function createMushiServer(config) {
         dispatchReady: z.boolean(),
         endpoint: z.string().nullable(),
         projectId: z.string().nullable(),
+        accessibleProjectCount: z.number().nullable(),
         issues: z.array(z.unknown()),
         nextAction: z.string(),
         summary: z.string()
@@ -728,13 +779,6 @@ function createMushiServer(config) {
           fix: "Run `mushi connect` to write MUSHI_API_KEY into .cursor/mcp.json, then restart the MCP server."
         });
       }
-      if (!projectId) {
-        issues.push({
-          check: "mcp_project_id",
-          detail: "No projectId configured on the MCP server",
-          fix: "Add MUSHI_PROJECT_ID to .cursor/mcp.json (copy UUID from console \u2192 Projects)."
-        });
-      }
       if (!apiEndpoint) {
         issues.push({
           check: "mcp_endpoint",
@@ -766,6 +810,21 @@ function createMushiServer(config) {
       }
       let ingestReady = false;
       let dispatchReady = false;
+      let accessibleProjectCount = null;
+      if (!projectId && healthOk) {
+        try {
+          const overview = await apiCall("/v1/admin/mcp/account-overview");
+          accessibleProjectCount = overview.total;
+          if (overview.total === 0) {
+            issues.push({
+              check: "no_accessible_projects",
+              detail: "API key has no accessible projects",
+              fix: "Mint an API key on a project (console \u2192 Projects \u2192 API Keys) or add MUSHI_PROJECT_ID to restrict to a single project."
+            });
+          }
+        } catch {
+        }
+      }
       try {
         const ingest = await apiCall("/v1/sync/ingest-setup");
         ingestReady = ingest.ready;
@@ -808,6 +867,7 @@ function createMushiServer(config) {
         dispatchReady,
         endpoint: apiEndpoint ?? null,
         projectId: projectId ?? null,
+        accessibleProjectCount,
         issues,
         nextAction,
         summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
@@ -873,16 +933,24 @@ function createMushiServer(config) {
       inputSchema: {},
       outputSchema: {
         projects: z.array(z.unknown()),
+        total: z.number(),
         active_project_id: z.string().nullable(),
+        toolCount: z.number().optional(),
+        resourceCount: z.number().optional(),
+        promptCount: z.number().optional(),
         multi_project_hint: z.string()
       }
     },
     async () => {
-      const data = await apiCall("/v1/admin/mcp/projects");
+      const data = await apiCall("/v1/admin/mcp/account-overview");
       const projects = Array.isArray(data?.projects) ? data.projects : [];
       return jsonResult({
         projects,
+        total: data?.total ?? projects.length,
         active_project_id: projectId ?? null,
+        toolCount: data?.toolCount,
+        resourceCount: data?.resourceCount,
+        promptCount: data?.promptCount,
         multi_project_hint: projects.length <= 1 ? 'You are currently connected to one project. To connect additional Mushi projects, open the Mushi console \u2192 switch to each project \u2192 MCP \u2192 Setup \u2192 "\u26A1 Add to Cursor". Each click adds a uniquely-named entry (mushi-{name}-{id}) to your global ~/.cursor/mcp.json so you can triage reports across all your apps from a single Cursor session.' : `You have access to ${projects.length} projects. To connect any unconnected project, open the Mushi console \u2192 switch to that project \u2192 MCP \u2192 Setup \u2192 "\u26A1 Add to Cursor".`
       });
     }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.15.0",
+  "mcpName": "io.github.kensaurus/mushi-mushi",
+  "version": "0.16.1",
   "license": "MIT",
   "description": "MCP server for Mushi Mushi — triage user-felt bugs, pull evidence (screenshots, console logs, network requests), check blast radius, and dispatch fix PRs, all from your AI coding agent",
   "type": "module",
@@ -42,7 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.2",
-    "@mushi-mushi/core": "^1.14.0"
+    "@mushi-mushi/core": "^1.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",