@mushi-mushi/mcp 0.16.2 → 0.17.1

package/README.md

@@ -2,7 +2,12 @@
 
 > **Your AI wrote it. Mushi tells you why it broke.**
 
-[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.
+[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-0098FF)](https://kensaur.us/mushi-mushi/docs/connect)
+[![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-007ACC?logo=visualstudiocode&logoColor=white)](https://kensaur.us/mushi-mushi/docs/connect)
+[![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.
 
 Wire it into Cursor, Claude Code, or any MCP client in one command:
 
@@ -259,7 +264,7 @@ Named templates the MCP client surfaces in its slash-menu. Each one bakes in the
 |---|---|---|---|
 | `MUSHI_API_KEY` | yes | — | Project API key with `mcp:read` or `mcp:write` scope. Mint one in the admin console → **Projects** (the one-time reveal card has a **Copy as `.env.local`** tab). |
 | `MUSHI_PROJECT_ID` | yes | — | UUID from the admin console URL (`/projects/<uuid>/...`) or the reveal card. |
-| `MUSHI_API_ENDPOINT` | no | `https://api.mushimushi.dev` | Override only if you self-host. Localhost value: `http://localhost:54321/functions/v1/api`. |
+| `MUSHI_API_ENDPOINT` | no | `https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api` | Override only if you self-host. Localhost: `http://localhost:54321/functions/v1/api`. |
 
 ### Storing the key in `.env.local`
 
@@ -269,7 +274,7 @@ The MCP binary reads these three vars from `process.env` on spawn — that means
 
    ```bash
    # Mushi MCP — drop into .env.local (gitignored). The MCP binary picks these up on spawn.
-   MUSHI_API_ENDPOINT=https://api.mushimushi.dev
+   MUSHI_API_ENDPOINT=https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api
    MUSHI_PROJECT_ID=<your-uuid>
    MUSHI_API_KEY=mushi_live_…
    ```
@@ -459,6 +464,7 @@ Both are complementary — use Sentry for exception noise, Mushi for "the user s
 
 ## See also
 
+- [GTM distribution runbook](../../docs/marketing/GTM-DISTRIBUTION.md) — MCP registry, Glama, Connect, cursor.directory, release checklist.
 - [V5.3 whitepaper §2.10](../../MushiMushi_Whitepaper_V5.md) — the agentic fix architecture this server feeds into.
 - [`@mushi-mushi/agents`](../agents/README.md) — orchestrator that consumes MCP-exposed fix workers.
 
@@ -470,4 +476,4 @@ MIT
 <!-- mushi-readme-stats-footer -->
 ---
 
-<sub>Monorepo scale (June 2026): 47 edge functions · 256 SQL migrations · 13 outbound plugins · 11 inbound adapters · 18 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>
+<sub>Monorepo scale (June 2026): 51 edge functions · 298 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/branding.js

@@ -5,7 +5,7 @@ import {
   MUSHI_SERVER_METADATA,
   MUSHI_WEBSITE_URL,
   mcpIconUrl
-} from "./chunk-EHB2BGWX.js";
+} from "./chunk-EANW5YTI.js";
 export {
   MUSHI_ICON_PNG_URL,
   MUSHI_ICON_SVG_URL,

package/dist/catalog.js

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

package/dist/{chunk-MM3IMFM4.js → chunk-7UOTJ2LI.js}

@@ -4,10 +4,10 @@ var TOOL_CATALOG = [
   {
     name: "get_recent_reports",
     title: "Recent bug reports",
-    description: "List recent bug reports with optional filters (status / category / severity). Use this to survey what the triage queue looks like right now.",
+    description: "List recent bug reports with optional filters (status / category / severity). Use this to see what is waiting in your reports inbox right now.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "What landed in my triage queue today?"
+    useCase: "What landed in my bug queue today?"
   },
   {
     name: "get_report_detail",
@@ -134,7 +134,7 @@ var TOOL_CATALOG = [
   {
     name: "setup_check",
     title: "Dispatch preflight check",
-    description: "[Deprecated \u2014 use diagnose_setup with mode=dispatch or diagnose_connection.] Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, Anthropic BYOK key present, autofix enabled). Also returns the target repo URL when GitHub is connected.",
+    description: "[Deprecated \u2014 use diagnose_setup with mode=dispatch or diagnose_connection.] Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, your Anthropic API key present, autofix enabled). Also returns the target repo URL when GitHub is connected.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Is this project ready to auto-fix bugs? What is blocking dispatch?"
@@ -184,7 +184,7 @@ var TOOL_CATALOG = [
   {
     name: "dispatch_fix",
     title: "Dispatch Mushi fix agent",
-    description: 'Dispatch the Mushi agentic fix orchestrator for a classified report. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR. Returns a fix_attempt id; poll get_fix_timeline for progress.',
+    description: 'Start the Mushi fix agent for a classified report. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR. Returns a fix_attempt id; poll get_fix_timeline for progress.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Let the in-repo agent attempt this fix for me (or: dispatch a Cursor Cloud Agent)."
@@ -200,7 +200,7 @@ var TOOL_CATALOG = [
   {
     name: "test_gen_from_report",
     title: "Generate Playwright test from report",
-    description: "POST to inventory test-gen: uses the project BYOK LLM to author a Playwright spec from a classified report and opens a draft PR (internal service orchestration). Requires inventory_v2 + GitHub + LLM keys.",
+    description: "Generate a Playwright spec from a classified report using your project LLM key and open a draft PR. Requires inventory_v2 + GitHub + LLM keys.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Turn this regression report into an E2E test PR."
@@ -232,7 +232,7 @@ var TOOL_CATALOG = [
   {
     name: "reopen_report",
     title: "Reopen report (operator)",
-    description: "Move a report to reopened for regression triage.",
+    description: "Move a report to reopened for regression review.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Reopen a regression the reporter flagged as not fixed."
@@ -290,10 +290,10 @@ var TOOL_CATALOG = [
   {
     name: "get_project_context",
     title: "Project context snapshot",
-    description: "Return a rich context snapshot for a project: name, repo URL, SDK heartbeat, ingest status, open report count, autofix readiness, BYOK LLM config, plan tier, and active integration health. Equivalent to a merged preflight + activation + settings read. Agents should call this at the start of a triage session to orient themselves.",
+    description: "Return a rich context snapshot for a project: name, repo URL, SDK heartbeat, ingest status, open report count, autofix readiness, your LLM key config, plan tier, and active integration health. Equivalent to a merged preflight + activation + settings read. Agents should call this at the start of a review session to orient themselves.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "Give me a status overview of this project before I start triaging."
+    useCase: "Give me a status overview of this project before I start reviewing bugs."
   },
   {
     name: "get_pipeline_logs",
@@ -314,7 +314,7 @@ var TOOL_CATALOG = [
   {
     name: "triage_issue",
     title: "Triage issue end-to-end",
-    description: 'Read-only orchestration tool: combines report detail, evidence, similar bugs, fix context, blast radius, and recent pipeline logs for a report into a single structured triage packet. Returns a prioritised list of recommended next actions (investigate, dispatch_fix, group_with, dismiss). Equivalent to a Sentry "Analyze with Seer" flow grounded in user-felt reports. Pass report_id to kick off triage. Call this before dispatch_fix.',
+    description: 'Read-only combined tool: merges report detail, evidence, similar bugs, fix context, blast radius, and recent pipeline logs for a report into a single structured review packet. Returns a prioritised list of recommended next actions (investigate, dispatch_fix, group_with, dismiss). Equivalent to a Sentry "Analyze with Seer" flow grounded in user-felt reports. Pass report_id to kick off review. Call this before dispatch_fix.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Analyze this bug report end-to-end and tell me what to do."
@@ -341,8 +341,8 @@ var RESOURCE_CATALOG = [
   {
     name: "project_dashboard",
     uri: "project://dashboard",
-    title: "PDCA dashboard snapshot",
-    description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls).",
+    title: "Loop dashboard snapshot",
+    description: "Loop health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls).",
     scope: "mcp:read"
   },
   {
@@ -363,14 +363,14 @@ var RESOURCE_CATALOG = [
     name: "privacy_status",
     uri: "privacy://status",
     title: "Privacy posture",
-    description: "Returns the privacy posture for this project: storage region, LLM provider, whether BYOK is configured, data retention window, and last audit timestamp. Agents should read this before dispatching a fix to confirm that client data stays within the expected boundary. Reads as project data does not leave the project's own LLM account when byok_configured=true.",
+    description: "Returns the privacy posture for this project: storage region, LLM provider, whether your own LLM key is configured, data retention window, and last audit timestamp. Agents should read this before dispatching a fix to confirm that client data stays within the expected boundary. Reads as project data does not leave the project's own LLM account when byok_configured=true.",
     scope: "mcp:read"
   },
   {
     name: "evolution_history",
     uri: "evolution://history",
     title: "Evolution history",
-    description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling (flat scores, same bugs re-appearing). Use before triage to understand which bug classes the loop has already learned to handle, and which still need human attention.",
+    description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling (flat scores, same bugs re-appearing). Use before review to understand which bug classes the loop has already learned to handle, and which still need human attention.",
     scope: "mcp:read"
   },
   {
@@ -384,7 +384,7 @@ var RESOURCE_CATALOG = [
     name: "project_integration_health",
     uri: "project://integration-health",
     title: "Integration health",
-    description: "Live health status of every configured BYOK channel (Sentry, GitHub, LangFuse, PagerDuty, \u2026). Orchestrators should check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run.",
+    description: "Live health status of every configured integration channel (Sentry, GitHub, LangFuse, PagerDuty, \u2026). Check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run.",
     scope: "mcp:read"
   },
   {
@@ -448,8 +448,8 @@ var TDD_TOOL_CATALOG = [
   },
   {
     name: "improve_qa_story",
-    title: "PDCA auto-improve a failing QA story",
-    description: "Trigger the PDCA improver for a specific project. Finds recently failed qa_story_runs and uses Claude to write improved test scripts. New tests are created with source=pdca and approval gated by the original story's automation_mode.",
+    title: "Auto-improve a failing QA story",
+    description: "Find recently failed qa_story_runs and use Claude to write improved test scripts. New tests are created with source=pdca and approval gated by the original story's automation_mode.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Fix my failing QA tests automatically."
@@ -464,16 +464,16 @@ var TDD_TOOL_CATALOG = [
   },
   {
     name: "list_byok_keys",
-    title: "List BYOK API key pool",
-    description: "List all BYOK API keys for the project, grouped by provider. Shows label, priority, status, and cooldown. Never returns the raw key value \u2014 only metadata. Use this to see which keys are active or exhausted.",
+    title: "List your API key pool",
+    description: "List all project API keys, grouped by provider. Shows label, priority, status, and cooldown. Never returns the raw key value \u2014 only metadata. Use this to see which keys are active or exhausted.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which API keys are active and which are rate-limited?"
   },
   {
     name: "add_byok_key",
-    title: "Add a BYOK API key",
-    description: "Add a new API key to the project's BYOK pool for a given provider (anthropic, openai, firecrawl, browserbase, cursor). Specify label and priority for ordering. The key is stored encrypted in Supabase Vault.",
+    title: "Add an API key",
+    description: "Add a new API key to the project pool for a given provider (anthropic, openai, firecrawl, browserbase, cursor). Specify label and priority for ordering. The key is stored encrypted in Supabase Vault.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Add a backup Anthropic key to the pool."
@@ -622,7 +622,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "ask_codebase",
     title: "Ask about the indexed codebase",
-    description: "Ask a plain-English question about the connected repo. Grounds on pgvector retrieval over project_codebase_files and returns an answer with file:line citations. Requires codebase indexing enabled and an Anthropic or OpenAI BYOK key.",
+    description: "Ask a plain-English question about the connected repo. Grounds on pgvector retrieval over project_codebase_files and returns an answer with file:line citations. Requires codebase indexing enabled and your Anthropic or OpenAI API key.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "How does authentication work in this repo?"

package/dist/{chunk-EHB2BGWX.js → chunk-EANW5YTI.js}

@@ -3,7 +3,9 @@ var MUSHI_WEBSITE_URL = "https://kensaur.us/mushi-mushi";
 var MUSHI_ICON_PNG_URL = `${MUSHI_WEBSITE_URL}/integrations/mushi-mark-512.png`;
 var MUSHI_ICON_SVG_URL = `${MUSHI_WEBSITE_URL}/favicon.svg`;
 function mcpIconUrl(mcpBaseUrl) {
-  const base = mcpBaseUrl.replace(/\/+$/, "");
+  let end = mcpBaseUrl.length;
+  while (end > 0 && mcpBaseUrl.charCodeAt(end - 1) === 47) end--;
+  const base = mcpBaseUrl.slice(0, end);
   return `${base}?icon=1`;
 }
 var MUSHI_SERVER_ICONS = [

package/dist/{chunk-ZX3XIJ7S.js → chunk-PW4AK6SV.js}

@@ -11,6 +11,7 @@ var FEATURE_GROUPS = [
   "audit",
   "docs",
   "usage",
+  "usage",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];

package/dist/clients.d.ts

@@ -0,0 +1,115 @@
+import { FeatureGroup } from './feature-groups.js';
+
+/**
+ * FILE: packages/mcp/src/clients.ts
+ * PURPOSE: Shared, pure (React-free) client registry + install-config builders for
+ *          every supported AI agent / IDE client.
+ *
+ * OVERVIEW:
+ * - Exports `MCP_CLIENTS: McpClientDef[]` — one entry per supported client.
+ * - Each entry carries metadata (id, label, method, transport) and a pure `build()`
+ *   function that returns the install artifact (deeplink URL, JSON config, or CLI command).
+ * - Both the admin console ConnectStudio and the public docs /connect landing consume
+ *   this module — the single source of truth so the two surfaces never drift.
+ *
+ * DEPENDENCIES:
+ * - feature-groups.ts  (DEFAULT_FEATURE_GROUPS, featuresQueryString, appendFeaturesToUrl)
+ * - branding.ts        (MUSHI_ICON_PNG_URL)
+ *
+ * USAGE:
+ *   import { MCP_CLIENTS } from '@mushi-mushi/mcp/clients'
+ *   const cursor = MCP_CLIENTS.find(c => c.id === 'cursor')!
+ *   const result = cursor.build({ projectId, projectName, apiKey, endpoint, mcpHttpUrl })
+ *   // result.kind === 'deeplink' → window.open(result.url)
+ *
+ * CLIENT INSTALL MATRIX (verified Jun 2026):
+ * - cursor / vscode / vscode-insiders  — one-click deeplink
+ * - windsurf                           — copy-config to ~/.codeium/windsurf/mcp_config.json
+ *                                        (uses `serverUrl`, NOT `url` — common footgun)
+ * - cline                              — copy-config to cline_mcp_settings.json
+ * - claude-code                        — CLI command: claude mcp add --transport http …
+ * - claude-desktop                     — copy-config to claude_desktop_config.json
+ * - zed                                — copy-config to ~/.config/zed/settings.json
+ * - any                                — hosted Streamable HTTP URL + Bearer key
+ *
+ * NOTES:
+ * - All builders are pure functions — no side-effects, no DOM, no React.
+ * - Cursor base64-encodes the config object without a `name` key in the payload.
+ * - VS Code includes `type:'stdio'` in the config and `name` as a separate query param.
+ * - Windsurf uses `serverUrl` for remote HTTP (NOT `url`) — encoding both would break it.
+ * - The `cliIde` field drives `mushi setup --ide <cliIde>` in the CLI lane.
+ */
+
+interface StdioConfig {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    icon?: string;
+}
+interface HttpConfig {
+    type: 'http';
+    url: string;
+    headers: Record<string, string>;
+    icon?: string;
+}
+type McpClientId = 'cursor' | 'vscode' | 'vscode-insiders' | 'windsurf' | 'cline' | 'claude-code' | 'claude-desktop' | 'zed' | 'any';
+/** The install method determines which UI treatment the console/docs page renders. */
+type McpInstallMethod = 'deeplink' | 'config-json' | 'cli-command' | 'remote-url';
+interface McpBuildInput {
+    /** Mushi project UUID — optional when building org-level configs. */
+    projectId?: string;
+    projectName: string;
+    apiKey: string;
+    /** Supabase edge function base URL (`MUSHI_API_ENDPOINT`). */
+    endpoint: string;
+    /** Hosted Streamable HTTP MCP URL (`RESOLVED_MCP_HTTP_URL`). */
+    mcpHttpUrl: string;
+    /**
+     * Restrict the exposed tool groups. Omitted → each client's existing default
+     * (the lean `DEFAULT_FEATURE_GROUPS` for stdio deeplinks; all tools for the
+     * config-json clients that historically set no `MUSHI_FEATURES`). The public
+     * keyless demo passes an explicit read-only subset here.
+     */
+    features?: readonly FeatureGroup[];
+    /**
+     * Hosted HTTP transport only: append `?read_only=1` so the server hides and
+     * blocks write tools regardless of key scope. Used by the public demo on top
+     * of an `mcp:read` key for defence in depth. No-op for stdio configs.
+     */
+    readOnly?: boolean;
+}
+type McpBuildResult = {
+    kind: 'deeplink';
+    url: string;
+} | {
+    kind: 'config';
+    filePath: string;
+    json: string;
+} | {
+    kind: 'command';
+    text: string;
+} | {
+    kind: 'remote-url';
+    url: string;
+    headerSnippet: string;
+};
+interface McpClientDef {
+    id: McpClientId;
+    label: string;
+    /** Short description shown in the client picker. */
+    description: string;
+    method: McpInstallMethod;
+    transport: 'stdio' | 'http';
+    /** Drives `mushi setup --ide <cliIde>` in the CLI lane. */
+    cliIde?: 'cursor' | 'claude' | 'continue' | 'zed';
+    build(input: McpBuildInput): McpBuildResult;
+}
+/** Build a stable, unique, human-readable MCP server slug for a project. */
+declare function projectServerName(projectId: string, projectName: string): string;
+declare function buildStdioConfigObj(projectId: string | undefined, apiKey: string, apiEndpoint: string, features?: readonly string[]): StdioConfig;
+declare function buildHttpConfigObj(projectId: string | undefined, apiKey: string, mcpHttpUrl: string, features?: readonly string[], readOnly?: boolean): HttpConfig;
+declare const MCP_CLIENTS: McpClientDef[];
+/** Look up a client by id — throws if not found. */
+declare function getMcpClient(id: McpClientId): McpClientDef;
+
+export { MCP_CLIENTS, type McpBuildInput, type McpBuildResult, type McpClientDef, type McpClientId, type McpInstallMethod, buildHttpConfigObj as buildRawHttpConfig, buildStdioConfigObj as buildRawStdioConfig, getMcpClient, projectServerName };

package/dist/clients.js

@@ -0,0 +1,271 @@
+import {
+  MUSHI_ICON_PNG_URL
+} from "./chunk-EANW5YTI.js";
+import {
+  DEFAULT_FEATURE_GROUPS,
+  appendFeaturesToUrl,
+  featuresQueryString
+} from "./chunk-PW4AK6SV.js";
+
+// src/clients.ts
+function projectServerName(projectId, projectName) {
+  const nameSlug = projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 22);
+  const idSuffix = projectId.replace(/-/g, "").slice(0, 6);
+  return `mushi-${nameSlug}-${idSuffix}`;
+}
+function buildStdioConfigObj(projectId, apiKey, apiEndpoint, features = DEFAULT_FEATURE_GROUPS) {
+  const env = {
+    MUSHI_API_ENDPOINT: apiEndpoint,
+    MUSHI_API_KEY: apiKey,
+    MUSHI_FEATURES: featuresQueryString(features)
+  };
+  if (projectId) env.MUSHI_PROJECT_ID = projectId;
+  return {
+    command: "npx",
+    args: ["-y", "@mushi-mushi/mcp@latest"],
+    env,
+    icon: MUSHI_ICON_PNG_URL
+  };
+}
+function withReadOnly(baseUrl, readOnly) {
+  if (!readOnly) return baseUrl;
+  const url = new URL(baseUrl);
+  url.searchParams.set("read_only", "1");
+  return url.toString();
+}
+function buildHttpConfigObj(projectId, apiKey, mcpHttpUrl, features = DEFAULT_FEATURE_GROUPS, readOnly = false) {
+  const url = withReadOnly(
+    appendFeaturesToUrl(mcpHttpUrl, features),
+    readOnly
+  );
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    "X-Mushi-Api-Key": apiKey
+  };
+  if (projectId) headers["X-Mushi-Project-Id"] = projectId;
+  return { type: "http", url, headers, icon: MUSHI_ICON_PNG_URL };
+}
+function encodeCursorDeeplink(name, config) {
+  const encoded = btoa(JSON.stringify(config));
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(name)}&config=${encodeURIComponent(encoded)}`;
+}
+function toVsCodeConfig(config) {
+  if ("type" in config && config.type === "http") return config;
+  return { type: "stdio", ...config };
+}
+function encodeVsCodeDeeplink(scheme, name, config) {
+  const withType = toVsCodeConfig(config);
+  return `${scheme}:mcp/install?name=${encodeURIComponent(name)}&config=${encodeURIComponent(JSON.stringify(withType))}`;
+}
+var MCP_CLIENTS = [
+  // ── Cursor ──────────────────────────────────────────────────────────────────
+  {
+    id: "cursor",
+    label: "Cursor",
+    description: "One-click install into your project's .cursor/mcp.json",
+    method: "deeplink",
+    transport: "stdio",
+    cliIde: "cursor",
+    build({ projectId, projectName, apiKey, endpoint, features }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const config = buildStdioConfigObj(projectId, apiKey, endpoint, features);
+      return { kind: "deeplink", url: encodeCursorDeeplink(name, config) };
+    }
+  },
+  // ── VS Code ──────────────────────────────────────────────────────────────────
+  {
+    id: "vscode",
+    label: "VS Code",
+    description: "One-click install via VS Code MCP extension",
+    method: "deeplink",
+    transport: "stdio",
+    build({ projectId, projectName, apiKey, endpoint, features }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const config = buildStdioConfigObj(projectId, apiKey, endpoint, features);
+      return { kind: "deeplink", url: encodeVsCodeDeeplink("vscode", name, config) };
+    }
+  },
+  // ── VS Code Insiders ─────────────────────────────────────────────────────────
+  {
+    id: "vscode-insiders",
+    label: "VS Code Insiders",
+    description: "One-click install via VS Code Insiders MCP extension",
+    method: "deeplink",
+    transport: "stdio",
+    build({ projectId, projectName, apiKey, endpoint, features }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const config = buildStdioConfigObj(projectId, apiKey, endpoint, features);
+      return { kind: "deeplink", url: encodeVsCodeDeeplink("vscode-insiders", name, config) };
+    }
+  },
+  // ── Windsurf ─────────────────────────────────────────────────────────────────
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    description: "Copy config into ~/.codeium/windsurf/mcp_config.json",
+    method: "config-json",
+    transport: "http",
+    build({ projectId, projectName, apiKey, mcpHttpUrl, features, readOnly }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const url = withReadOnly(
+        appendFeaturesToUrl(mcpHttpUrl, features ?? DEFAULT_FEATURE_GROUPS),
+        readOnly
+      );
+      const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        "X-Mushi-Api-Key": apiKey
+      };
+      if (projectId) headers["X-Mushi-Project-Id"] = projectId;
+      const windsurfConfig = { type: "http", serverUrl: url, headers };
+      const configJson = JSON.stringify(
+        { mcpServers: { [name]: windsurfConfig } },
+        null,
+        2
+      );
+      return {
+        kind: "config",
+        filePath: "~/.codeium/windsurf/mcp_config.json",
+        json: configJson
+      };
+    }
+  },
+  // ── Cline ────────────────────────────────────────────────────────────────────
+  {
+    id: "cline",
+    label: "Cline",
+    description: "Copy config into cline_mcp_settings.json",
+    method: "config-json",
+    transport: "stdio",
+    build({ projectId, projectName, apiKey, endpoint, features }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const env = {
+        MUSHI_API_ENDPOINT: endpoint,
+        MUSHI_API_KEY: apiKey
+      };
+      if (features) env.MUSHI_FEATURES = featuresQueryString(features);
+      if (projectId) env.MUSHI_PROJECT_ID = projectId;
+      const clineConfig = {
+        mcpServers: {
+          [name]: { command: "npx", args: ["-y", "@mushi-mushi/mcp@latest"], env }
+        }
+      };
+      return {
+        kind: "config",
+        // Cline stores config in the VS Code extension's globalStorage
+        filePath: "~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json",
+        json: JSON.stringify(clineConfig, null, 2)
+      };
+    }
+  },
+  // ── Claude Code ──────────────────────────────────────────────────────────────
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    description: "Add via claude CLI command (HTTP transport)",
+    method: "cli-command",
+    transport: "http",
+    cliIde: "claude",
+    build({ projectId, projectName, apiKey, mcpHttpUrl, features, readOnly }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const url = withReadOnly(
+        appendFeaturesToUrl(mcpHttpUrl, features ?? DEFAULT_FEATURE_GROUPS),
+        readOnly
+      );
+      const cmd = `claude mcp add --transport http ${name} "${url}" --header "Authorization: Bearer ${apiKey}"`;
+      return { kind: "command", text: cmd };
+    }
+  },
+  // ── Claude Desktop ───────────────────────────────────────────────────────────
+  {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    description: "Copy config into claude_desktop_config.json",
+    method: "config-json",
+    transport: "stdio",
+    build({ projectId, projectName, apiKey, endpoint, features }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const env = {
+        MUSHI_API_ENDPOINT: endpoint,
+        MUSHI_API_KEY: apiKey
+      };
+      if (features) env.MUSHI_FEATURES = featuresQueryString(features);
+      if (projectId) env.MUSHI_PROJECT_ID = projectId;
+      const desktopConfig = {
+        mcpServers: {
+          [name]: { command: "npx", args: ["-y", "@mushi-mushi/mcp@latest"], env }
+        }
+      };
+      return {
+        kind: "config",
+        filePath: "~/Library/Application Support/Claude/claude_desktop_config.json",
+        json: JSON.stringify(desktopConfig, null, 2)
+      };
+    }
+  },
+  // ── Zed ──────────────────────────────────────────────────────────────────────
+  {
+    id: "zed",
+    label: "Zed",
+    description: "Copy config into ~/.config/zed/settings.json",
+    method: "config-json",
+    transport: "stdio",
+    cliIde: "zed",
+    build({ projectId, projectName, apiKey, endpoint, features }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const env = {
+        MUSHI_API_ENDPOINT: endpoint,
+        MUSHI_API_KEY: apiKey
+      };
+      if (features) env.MUSHI_FEATURES = featuresQueryString(features);
+      if (projectId) env.MUSHI_PROJECT_ID = projectId;
+      const zedConfig = {
+        context_servers: {
+          [name]: {
+            command: {
+              path: "npx",
+              args: ["-y", "@mushi-mushi/mcp@latest"],
+              env
+            },
+            settings: {}
+          }
+        }
+      };
+      return {
+        kind: "config",
+        filePath: "~/.config/zed/settings.json",
+        json: JSON.stringify(zedConfig, null, 2)
+      };
+    }
+  },
+  // ── Any MCP client ───────────────────────────────────────────────────────────
+  {
+    id: "any",
+    label: "Any MCP client",
+    description: "Streamable HTTP URL \u2014 works with OpenClaw, Hermes, Gemini CLI, ChatGPT, and more",
+    method: "remote-url",
+    transport: "http",
+    build({ projectId, apiKey, mcpHttpUrl, features, readOnly }) {
+      const url = withReadOnly(
+        appendFeaturesToUrl(mcpHttpUrl, features ?? DEFAULT_FEATURE_GROUPS),
+        readOnly
+      );
+      const headerSnippet = [
+        `Authorization: Bearer ${apiKey}`,
+        projectId ? `X-Mushi-Project-Id: ${projectId}` : ""
+      ].filter(Boolean).join("\n");
+      return { kind: "remote-url", url, headerSnippet };
+    }
+  }
+];
+function getMcpClient(id) {
+  const client = MCP_CLIENTS.find((c) => c.id === id);
+  if (!client) throw new Error(`Unknown MCP client id: ${id}`);
+  return client;
+}
+export {
+  MCP_CLIENTS,
+  buildHttpConfigObj as buildRawHttpConfig,
+  buildStdioConfigObj as buildRawStdioConfig,
+  getMcpClient,
+  projectServerName
+};

package/dist/feature-groups.d.ts

@@ -4,7 +4,7 @@
  * When `features` is omitted → all tools (backward compatible).
  * New installs default to DEFAULT_FEATURE_GROUPS via deeplink / docs.
  */
-declare const FEATURE_GROUPS: readonly ["triage", "fixes", "inventory", "setup", "qa", "skills", "rewards", "admin", "audit", "docs", "usage", "legacy"];
+declare const FEATURE_GROUPS: readonly ["triage", "fixes", "inventory", "setup", "qa", "skills", "rewards", "admin", "audit", "docs", "usage", "usage", "legacy"];
 type FeatureGroup = (typeof FEATURE_GROUPS)[number];
 /** Lean default for new Cursor installs (~45 tools vs 70 full). */
 declare const DEFAULT_FEATURE_GROUPS: readonly FeatureGroup[];

package/dist/feature-groups.js

@@ -9,7 +9,7 @@ import {
   parseFeaturesCsv,
   parseFeaturesParam,
   toolMatchesFeatures
-} from "./chunk-ZX3XIJ7S.js";
+} from "./chunk-PW4AK6SV.js";
 export {
   ALL_FEATURE_GROUPS,
   DEFAULT_FEATURE_GROUPS,

package/dist/index.js

@@ -11,10 +11,10 @@ var TOOL_CATALOG = [
   {
     name: "get_recent_reports",
     title: "Recent bug reports",
-    description: "List recent bug reports with optional filters (status / category / severity). Use this to survey what the triage queue looks like right now.",
+    description: "List recent bug reports with optional filters (status / category / severity). Use this to see what is waiting in your reports inbox right now.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "What landed in my triage queue today?"
+    useCase: "What landed in my bug queue today?"
   },
   {
     name: "get_report_detail",
@@ -141,7 +141,7 @@ var TOOL_CATALOG = [
   {
     name: "setup_check",
     title: "Dispatch preflight check",
-    description: "[Deprecated \u2014 use diagnose_setup with mode=dispatch or diagnose_connection.] Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, Anthropic BYOK key present, autofix enabled). Also returns the target repo URL when GitHub is connected.",
+    description: "[Deprecated \u2014 use diagnose_setup with mode=dispatch or diagnose_connection.] Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, your Anthropic API key present, autofix enabled). Also returns the target repo URL when GitHub is connected.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Is this project ready to auto-fix bugs? What is blocking dispatch?"
@@ -191,7 +191,7 @@ var TOOL_CATALOG = [
   {
     name: "dispatch_fix",
     title: "Dispatch Mushi fix agent",
-    description: 'Dispatch the Mushi agentic fix orchestrator for a classified report. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR. Returns a fix_attempt id; poll get_fix_timeline for progress.',
+    description: 'Start the Mushi fix agent for a classified report. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR. Returns a fix_attempt id; poll get_fix_timeline for progress.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Let the in-repo agent attempt this fix for me (or: dispatch a Cursor Cloud Agent)."
@@ -207,7 +207,7 @@ var TOOL_CATALOG = [
   {
     name: "test_gen_from_report",
     title: "Generate Playwright test from report",
-    description: "POST to inventory test-gen: uses the project BYOK LLM to author a Playwright spec from a classified report and opens a draft PR (internal service orchestration). Requires inventory_v2 + GitHub + LLM keys.",
+    description: "Generate a Playwright spec from a classified report using your project LLM key and open a draft PR. Requires inventory_v2 + GitHub + LLM keys.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Turn this regression report into an E2E test PR."
@@ -239,7 +239,7 @@ var TOOL_CATALOG = [
   {
     name: "reopen_report",
     title: "Reopen report (operator)",
-    description: "Move a report to reopened for regression triage.",
+    description: "Move a report to reopened for regression review.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Reopen a regression the reporter flagged as not fixed."
@@ -297,10 +297,10 @@ var TOOL_CATALOG = [
   {
     name: "get_project_context",
     title: "Project context snapshot",
-    description: "Return a rich context snapshot for a project: name, repo URL, SDK heartbeat, ingest status, open report count, autofix readiness, BYOK LLM config, plan tier, and active integration health. Equivalent to a merged preflight + activation + settings read. Agents should call this at the start of a triage session to orient themselves.",
+    description: "Return a rich context snapshot for a project: name, repo URL, SDK heartbeat, ingest status, open report count, autofix readiness, your LLM key config, plan tier, and active integration health. Equivalent to a merged preflight + activation + settings read. Agents should call this at the start of a review session to orient themselves.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
-    useCase: "Give me a status overview of this project before I start triaging."
+    useCase: "Give me a status overview of this project before I start reviewing bugs."
   },
   {
     name: "get_pipeline_logs",
@@ -321,7 +321,7 @@ var TOOL_CATALOG = [
   {
     name: "triage_issue",
     title: "Triage issue end-to-end",
-    description: 'Read-only orchestration tool: combines report detail, evidence, similar bugs, fix context, blast radius, and recent pipeline logs for a report into a single structured triage packet. Returns a prioritised list of recommended next actions (investigate, dispatch_fix, group_with, dismiss). Equivalent to a Sentry "Analyze with Seer" flow grounded in user-felt reports. Pass report_id to kick off triage. Call this before dispatch_fix.',
+    description: 'Read-only combined tool: merges report detail, evidence, similar bugs, fix context, blast radius, and recent pipeline logs for a report into a single structured review packet. Returns a prioritised list of recommended next actions (investigate, dispatch_fix, group_with, dismiss). Equivalent to a Sentry "Analyze with Seer" flow grounded in user-felt reports. Pass report_id to kick off review. Call this before dispatch_fix.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Analyze this bug report end-to-end and tell me what to do."
@@ -371,8 +371,8 @@ var TDD_TOOL_CATALOG = [
   },
   {
     name: "improve_qa_story",
-    title: "PDCA auto-improve a failing QA story",
-    description: "Trigger the PDCA improver for a specific project. Finds recently failed qa_story_runs and uses Claude to write improved test scripts. New tests are created with source=pdca and approval gated by the original story's automation_mode.",
+    title: "Auto-improve a failing QA story",
+    description: "Find recently failed qa_story_runs and use Claude to write improved test scripts. New tests are created with source=pdca and approval gated by the original story's automation_mode.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Fix my failing QA tests automatically."
@@ -387,16 +387,16 @@ var TDD_TOOL_CATALOG = [
   },
   {
     name: "list_byok_keys",
-    title: "List BYOK API key pool",
-    description: "List all BYOK API keys for the project, grouped by provider. Shows label, priority, status, and cooldown. Never returns the raw key value \u2014 only metadata. Use this to see which keys are active or exhausted.",
+    title: "List your API key pool",
+    description: "List all project API keys, grouped by provider. Shows label, priority, status, and cooldown. Never returns the raw key value \u2014 only metadata. Use this to see which keys are active or exhausted.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which API keys are active and which are rate-limited?"
   },
   {
     name: "add_byok_key",
-    title: "Add a BYOK API key",
-    description: "Add a new API key to the project's BYOK pool for a given provider (anthropic, openai, firecrawl, browserbase, cursor). Specify label and priority for ordering. The key is stored encrypted in Supabase Vault.",
+    title: "Add an API key",
+    description: "Add a new API key to the project pool for a given provider (anthropic, openai, firecrawl, browserbase, cursor). Specify label and priority for ordering. The key is stored encrypted in Supabase Vault.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "Add a backup Anthropic key to the pool."
@@ -545,7 +545,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "ask_codebase",
     title: "Ask about the indexed codebase",
-    description: "Ask a plain-English question about the connected repo. Grounds on pgvector retrieval over project_codebase_files and returns an answer with file:line citations. Requires codebase indexing enabled and an Anthropic or OpenAI BYOK key.",
+    description: "Ask a plain-English question about the connected repo. Grounds on pgvector retrieval over project_codebase_files and returns an answer with file:line citations. Requires codebase indexing enabled and your Anthropic or OpenAI API key.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: "How does authentication work in this repo?"
@@ -613,6 +613,7 @@ var FEATURE_GROUPS = [
   "audit",
   "docs",
   "usage",
+  "usage",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];
@@ -857,6 +858,7 @@ function searchMushiDocs(query, limit = 8) {
 }
 
 // src/server.ts
+var NO_ARG_INPUT = {};
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -933,7 +935,16 @@ function createMushiServer(config) {
     return body;
   }
   async function resolveProjectId(explicitId) {
-    if (explicitId) return explicitId;
+    if (explicitId) {
+      if (projectId && explicitId !== projectId) {
+        throw new MushiApiError(
+          400,
+          "PROJECT_SCOPE_MISMATCH",
+          `This MCP entry is bound to project ${projectId}. Either pass projectId="${projectId}", add a second MCP server entry for ${explicitId} (Console \u2192 Connect \u2192 Add to Cursor while that project is selected), or run \`mushi setup --all-projects --ide cursor\` for one entry per repo.`
+        );
+      }
+      return explicitId;
+    }
     if (projectId) return projectId;
     try {
       const data = await apiCall(
@@ -964,6 +975,11 @@ function createMushiServer(config) {
       );
     }
   }
+  async function projectScopeHeaders(explicitId) {
+    const pid = await resolveProjectId(explicitId ?? void 0);
+    const headers = { "X-Mushi-Project-Id": pid };
+    return { projectId: pid, headers };
+  }
   function jsonText(value) {
     return {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -1045,11 +1061,15 @@ function createMushiServer(config) {
       title: titleOf("get_report_detail"),
       description: descOf("get_report_detail"),
       annotations: annotationsFor("get_report_detail"),
-      inputSchema: { reportId: z.string().describe("The report UUID") },
+      inputSchema: {
+        reportId: z.string().describe("The report UUID"),
+        project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
+      },
       outputSchema: { report: z.unknown() }
     },
     async (args) => {
-      const data = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      const { headers } = await projectScopeHeaders(args.project_id);
+      const data = await apiCall(`/v1/admin/reports/${args.reportId}`, { headers });
       const res = jsonResult({ report: data });
       return {
         ...res,
@@ -1075,7 +1095,7 @@ function createMushiServer(config) {
       title: titleOf("get_two_way_comms_health"),
       description: descOf("get_two_way_comms_health"),
       annotations: annotationsFor("get_two_way_comms_health"),
-      inputSchema: {}
+      inputSchema: NO_ARG_INPUT
     },
     async () => jsonText(await apiCall("/v1/sync/two-way-health"))
   );
@@ -1140,7 +1160,10 @@ function createMushiServer(config) {
       title: titleOf("get_fix_context"),
       description: descOf("get_fix_context"),
       annotations: annotationsFor("get_fix_context"),
-      inputSchema: { reportId: z.string().describe("The report UUID to fix") },
+      inputSchema: {
+        reportId: z.string().describe("The report UUID to fix"),
+        project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
+      },
       outputSchema: {
         report: z.unknown(),
         fixPrompt: z.unknown(),
@@ -1151,7 +1174,10 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      const { headers } = await projectScopeHeaders(args.project_id);
+      const report = await apiCall(`/v1/admin/reports/${args.reportId}`, {
+        headers
+      });
       return jsonResult({
         report,
         // Paste-ready fix prompt composed server-side by composeFixPacket()
@@ -1171,9 +1197,15 @@ function createMushiServer(config) {
       title: titleOf("get_fix_timeline"),
       description: descOf("get_fix_timeline"),
       annotations: annotationsFor("get_fix_timeline"),
-      inputSchema: { fixId: z.string().describe("fix_attempt UUID") }
+      inputSchema: {
+        fixId: z.string().describe("fix_attempt UUID"),
+        project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
+      }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`))
+    async (args) => {
+      const { headers } = await projectScopeHeaders(args.project_id);
+      return jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`, { headers }));
+    }
   );
   server.registerTool(
     "get_blast_radius",
@@ -1370,7 +1402,7 @@ function createMushiServer(config) {
       title: titleOf("ingest_setup_check"),
       description: descOf("ingest_setup_check"),
       annotations: annotationsFor("ingest_setup_check"),
-      inputSchema: {}
+      inputSchema: NO_ARG_INPUT
     },
     async () => {
       const data = await apiCall("/v1/sync/ingest-setup");
@@ -1464,9 +1496,11 @@ function createMushiServer(config) {
             const failed = preflight.checks.filter((c) => !c.ready);
             dispatchBlock = failed[0]?.hint;
           }
-        } catch {
+        } catch (err) {
           dispatchReady = false;
-          dispatchBlock = "Could not run dispatch preflight \u2014 verify project_id and API key scope.";
+          const detail = err instanceof Error ? err.message : String(err);
+          dispatchBlock = `Could not run dispatch preflight \u2014 ${detail}`;
+          apiLog.warn("diagnose_setup dispatch preflight failed", { error: detail });
         }
       }
       const ingestFailed = ingest.steps.filter((s) => s.required && !s.complete);
@@ -1490,7 +1524,7 @@ function createMushiServer(config) {
       title: titleOf("diagnose_connection"),
       description: descOf("diagnose_connection"),
       annotations: annotationsFor("diagnose_connection"),
-      inputSchema: {},
+      inputSchema: NO_ARG_INPUT,
       outputSchema: {
         ready: z.boolean(),
         healthOk: z.boolean(),
@@ -1643,7 +1677,7 @@ function createMushiServer(config) {
       title: titleOf("list_projects"),
       description: descOf("list_projects"),
       annotations: annotationsFor("list_projects"),
-      inputSchema: {},
+      inputSchema: NO_ARG_INPUT,
       outputSchema: {
         projects: z.array(z.unknown()),
         total: z.number().optional(),
@@ -1664,7 +1698,7 @@ function createMushiServer(config) {
       title: titleOf("get_account_overview"),
       description: descOf("get_account_overview"),
       annotations: annotationsFor("get_account_overview"),
-      inputSchema: {},
+      inputSchema: NO_ARG_INPUT,
       outputSchema: {
         projects: z.array(z.unknown()),
         total: z.number(),
@@ -1783,7 +1817,7 @@ function createMushiServer(config) {
       description: descOf("triage_issue"),
       annotations: annotationsFor("triage_issue"),
       inputSchema: {
-        report_id: z.string().describe("Report UUID to triage."),
+        report_id: z.string().uuid().describe("Report UUID to triage."),
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
         include_logs: z.boolean().optional().describe("Include recent pipeline logs in triage packet (default: true).")
       },
@@ -1803,18 +1837,19 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const pid = args.project_id ?? projectId;
+      const { projectId: pid, headers } = await projectScopeHeaders(args.project_id);
       const includeLogs = args.include_logs !== false;
       const [reportRes, evidenceRes, similarRes, fixCtxRes, blastRes, logsRes] = await Promise.allSettled([
-        apiCall(`/v1/admin/reports/${args.report_id}`),
-        apiCall(`/v1/admin/reports/${args.report_id}/timeline`),
+        apiCall(`/v1/admin/reports/${args.report_id}`, { headers }),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`, { headers }),
         apiCall(`/v1/admin/reports/similarity`, {
           method: "POST",
+          headers,
           body: JSON.stringify({ report_id: args.report_id })
         }).catch(() => null),
-        pid ? apiCall(`/v1/admin/reports/${args.report_id}/fix-context`).catch(() => null) : Promise.resolve(null),
-        pid ? apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`).catch(() => null) : Promise.resolve(null),
-        includeLogs && pid ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`).catch(() => null) : Promise.resolve(null)
+        apiCall(`/v1/admin/reports/${args.report_id}/fix-context`, { headers }).catch(() => null),
+        apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`, { headers }).catch(() => null),
+        includeLogs ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`, { headers }).catch(() => null) : Promise.resolve(null)
       ]);
       const report = reportRes.status === "fulfilled" ? reportRes.value : null;
       const severity = report ? report.severity : "unknown";
@@ -1843,11 +1878,31 @@ function createMushiServer(config) {
           args: { reportId: args.report_id }
         });
       }
+      const partial_errors = [];
+      if (reportRes.status === "rejected") {
+        partial_errors.push(`report: ${String(reportRes.reason)}`);
+      }
+      if (evidenceRes.status === "rejected") {
+        partial_errors.push(`timeline: ${String(evidenceRes.reason)}`);
+      }
+      if (similarRes.status === "rejected") {
+        partial_errors.push(`similarity: ${String(similarRes.reason)}`);
+      }
+      if (fixCtxRes.status === "rejected") {
+        partial_errors.push(`fix_context: ${String(fixCtxRes.reason)}`);
+      }
+      if (blastRes.status === "rejected") {
+        partial_errors.push(`blast_radius: ${String(blastRes.reason)}`);
+      }
+      if (includeLogs && logsRes.status === "rejected") {
+        partial_errors.push(`recent_logs: ${String(logsRes.reason)}`);
+      }
       const result = {
         report_id: args.report_id,
         severity,
         category,
         status,
+        partial_errors,
         report: reportRes.status === "fulfilled" ? reportRes.value : { error: String(reportRes.reason) },
         reporter_thread: evidenceRes.status === "fulfilled" ? evidenceRes.value : null,
         similar_bugs: similarRes.status === "fulfilled" ? similarRes.value : null,
@@ -1912,7 +1967,7 @@ function createMushiServer(config) {
       description: descOf("dispatch_fix"),
       annotations: annotationsFor("dispatch_fix"),
       inputSchema: {
-        reportId: z.string().describe("Report UUID to fix"),
+        reportId: z.string().uuid().describe("Report UUID to fix"),
         agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
         idempotencyKey: z.string().uuid().optional().describe("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
         inventoryActionNodeId: z.string().uuid().optional().describe("Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR.")
@@ -3079,6 +3134,7 @@ Be specific. No generic advice.`
 }
 
 // src/index.ts
+import * as Sentry from "@sentry/node";
 var _writeStderr = (...args) => process.stderr.write(
   args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") + "\n"
 );
@@ -3094,6 +3150,14 @@ var SCOPES_RAW = process.env.MUSHI_SCOPES ?? "";
 var parsedScopes = SCOPES_RAW ? SCOPES_RAW.split(",").map((s) => s.trim()).filter((s) => s === "mcp:read" || s === "mcp:write") : ALL_SCOPES;
 var SCOPES = SCOPES_RAW && parsedScopes.length === 0 ? ALL_SCOPES : parsedScopes;
 var FEATURES = parseFeaturesCsv(process.env.MUSHI_FEATURES);
+var MCP_SENTRY_DSN = process.env.MUSHI_MCP_SENTRY_DSN?.trim();
+if (MCP_SENTRY_DSN) {
+  Sentry.init({
+    dsn: MCP_SENTRY_DSN,
+    environment: process.env.MUSHI_SENTRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "development",
+    tracesSampleRate: 0
+  });
+}
 async function main() {
   if (!API_KEY) {
     log.fatal("MUSHI_API_KEY environment variable is required");
@@ -3149,7 +3213,8 @@ async function main() {
           }
           lastInventoryAt = updatedAt;
         }
-      } catch {
+      } catch (pollErr) {
+        log.debug("inventory poll failed", { err: String(pollErr) });
       }
     };
     void pollInventory();

package/dist/server.js

@@ -2,13 +2,13 @@ import {
   CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-MM3IMFM4.js";
+} from "./chunk-7UOTJ2LI.js";
 import {
   MUSHI_SERVER_METADATA
-} from "./chunk-EHB2BGWX.js";
+} from "./chunk-EANW5YTI.js";
 import {
   toolMatchesFeatures
-} from "./chunk-ZX3XIJ7S.js";
+} from "./chunk-PW4AK6SV.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -123,6 +123,7 @@ function searchMushiDocs(query, limit = 8) {
 }
 
 // src/server.ts
+var NO_ARG_INPUT = {};
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -199,7 +200,16 @@ function createMushiServer(config) {
     return body;
   }
   async function resolveProjectId(explicitId) {
-    if (explicitId) return explicitId;
+    if (explicitId) {
+      if (projectId && explicitId !== projectId) {
+        throw new MushiApiError(
+          400,
+          "PROJECT_SCOPE_MISMATCH",
+          `This MCP entry is bound to project ${projectId}. Either pass projectId="${projectId}", add a second MCP server entry for ${explicitId} (Console \u2192 Connect \u2192 Add to Cursor while that project is selected), or run \`mushi setup --all-projects --ide cursor\` for one entry per repo.`
+        );
+      }
+      return explicitId;
+    }
     if (projectId) return projectId;
     try {
       const data = await apiCall(
@@ -230,6 +240,11 @@ function createMushiServer(config) {
       );
     }
   }
+  async function projectScopeHeaders(explicitId) {
+    const pid = await resolveProjectId(explicitId ?? void 0);
+    const headers = { "X-Mushi-Project-Id": pid };
+    return { projectId: pid, headers };
+  }
   function jsonText(value) {
     return {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -311,11 +326,15 @@ function createMushiServer(config) {
       title: titleOf("get_report_detail"),
       description: descOf("get_report_detail"),
       annotations: annotationsFor("get_report_detail"),
-      inputSchema: { reportId: z.string().describe("The report UUID") },
+      inputSchema: {
+        reportId: z.string().describe("The report UUID"),
+        project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
+      },
       outputSchema: { report: z.unknown() }
     },
     async (args) => {
-      const data = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      const { headers } = await projectScopeHeaders(args.project_id);
+      const data = await apiCall(`/v1/admin/reports/${args.reportId}`, { headers });
       const res = jsonResult({ report: data });
       return {
         ...res,
@@ -341,7 +360,7 @@ function createMushiServer(config) {
       title: titleOf("get_two_way_comms_health"),
       description: descOf("get_two_way_comms_health"),
       annotations: annotationsFor("get_two_way_comms_health"),
-      inputSchema: {}
+      inputSchema: NO_ARG_INPUT
     },
     async () => jsonText(await apiCall("/v1/sync/two-way-health"))
   );
@@ -406,7 +425,10 @@ function createMushiServer(config) {
       title: titleOf("get_fix_context"),
       description: descOf("get_fix_context"),
       annotations: annotationsFor("get_fix_context"),
-      inputSchema: { reportId: z.string().describe("The report UUID to fix") },
+      inputSchema: {
+        reportId: z.string().describe("The report UUID to fix"),
+        project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
+      },
       outputSchema: {
         report: z.unknown(),
         fixPrompt: z.unknown(),
@@ -417,7 +439,10 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      const { headers } = await projectScopeHeaders(args.project_id);
+      const report = await apiCall(`/v1/admin/reports/${args.reportId}`, {
+        headers
+      });
       return jsonResult({
         report,
         // Paste-ready fix prompt composed server-side by composeFixPacket()
@@ -437,9 +462,15 @@ function createMushiServer(config) {
       title: titleOf("get_fix_timeline"),
       description: descOf("get_fix_timeline"),
       annotations: annotationsFor("get_fix_timeline"),
-      inputSchema: { fixId: z.string().describe("fix_attempt UUID") }
+      inputSchema: {
+        fixId: z.string().describe("fix_attempt UUID"),
+        project_id: z.string().optional().describe("Project UUID \u2014 required for org-scoped keys with multiple projects.")
+      }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`))
+    async (args) => {
+      const { headers } = await projectScopeHeaders(args.project_id);
+      return jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`, { headers }));
+    }
   );
   server.registerTool(
     "get_blast_radius",
@@ -636,7 +667,7 @@ function createMushiServer(config) {
       title: titleOf("ingest_setup_check"),
       description: descOf("ingest_setup_check"),
       annotations: annotationsFor("ingest_setup_check"),
-      inputSchema: {}
+      inputSchema: NO_ARG_INPUT
     },
     async () => {
       const data = await apiCall("/v1/sync/ingest-setup");
@@ -730,9 +761,11 @@ function createMushiServer(config) {
             const failed = preflight.checks.filter((c) => !c.ready);
             dispatchBlock = failed[0]?.hint;
           }
-        } catch {
+        } catch (err) {
           dispatchReady = false;
-          dispatchBlock = "Could not run dispatch preflight \u2014 verify project_id and API key scope.";
+          const detail = err instanceof Error ? err.message : String(err);
+          dispatchBlock = `Could not run dispatch preflight \u2014 ${detail}`;
+          apiLog.warn("diagnose_setup dispatch preflight failed", { error: detail });
         }
       }
       const ingestFailed = ingest.steps.filter((s) => s.required && !s.complete);
@@ -756,7 +789,7 @@ function createMushiServer(config) {
       title: titleOf("diagnose_connection"),
       description: descOf("diagnose_connection"),
       annotations: annotationsFor("diagnose_connection"),
-      inputSchema: {},
+      inputSchema: NO_ARG_INPUT,
       outputSchema: {
         ready: z.boolean(),
         healthOk: z.boolean(),
@@ -909,7 +942,7 @@ function createMushiServer(config) {
       title: titleOf("list_projects"),
       description: descOf("list_projects"),
       annotations: annotationsFor("list_projects"),
-      inputSchema: {},
+      inputSchema: NO_ARG_INPUT,
       outputSchema: {
         projects: z.array(z.unknown()),
         total: z.number().optional(),
@@ -930,7 +963,7 @@ function createMushiServer(config) {
       title: titleOf("get_account_overview"),
       description: descOf("get_account_overview"),
       annotations: annotationsFor("get_account_overview"),
-      inputSchema: {},
+      inputSchema: NO_ARG_INPUT,
       outputSchema: {
         projects: z.array(z.unknown()),
         total: z.number(),
@@ -1049,7 +1082,7 @@ function createMushiServer(config) {
       description: descOf("triage_issue"),
       annotations: annotationsFor("triage_issue"),
       inputSchema: {
-        report_id: z.string().describe("Report UUID to triage."),
+        report_id: z.string().uuid().describe("Report UUID to triage."),
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
         include_logs: z.boolean().optional().describe("Include recent pipeline logs in triage packet (default: true).")
       },
@@ -1069,18 +1102,19 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const pid = args.project_id ?? projectId;
+      const { projectId: pid, headers } = await projectScopeHeaders(args.project_id);
       const includeLogs = args.include_logs !== false;
       const [reportRes, evidenceRes, similarRes, fixCtxRes, blastRes, logsRes] = await Promise.allSettled([
-        apiCall(`/v1/admin/reports/${args.report_id}`),
-        apiCall(`/v1/admin/reports/${args.report_id}/timeline`),
+        apiCall(`/v1/admin/reports/${args.report_id}`, { headers }),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`, { headers }),
         apiCall(`/v1/admin/reports/similarity`, {
           method: "POST",
+          headers,
           body: JSON.stringify({ report_id: args.report_id })
         }).catch(() => null),
-        pid ? apiCall(`/v1/admin/reports/${args.report_id}/fix-context`).catch(() => null) : Promise.resolve(null),
-        pid ? apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`).catch(() => null) : Promise.resolve(null),
-        includeLogs && pid ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`).catch(() => null) : Promise.resolve(null)
+        apiCall(`/v1/admin/reports/${args.report_id}/fix-context`, { headers }).catch(() => null),
+        apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`, { headers }).catch(() => null),
+        includeLogs ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`, { headers }).catch(() => null) : Promise.resolve(null)
       ]);
       const report = reportRes.status === "fulfilled" ? reportRes.value : null;
       const severity = report ? report.severity : "unknown";
@@ -1109,11 +1143,31 @@ function createMushiServer(config) {
           args: { reportId: args.report_id }
         });
       }
+      const partial_errors = [];
+      if (reportRes.status === "rejected") {
+        partial_errors.push(`report: ${String(reportRes.reason)}`);
+      }
+      if (evidenceRes.status === "rejected") {
+        partial_errors.push(`timeline: ${String(evidenceRes.reason)}`);
+      }
+      if (similarRes.status === "rejected") {
+        partial_errors.push(`similarity: ${String(similarRes.reason)}`);
+      }
+      if (fixCtxRes.status === "rejected") {
+        partial_errors.push(`fix_context: ${String(fixCtxRes.reason)}`);
+      }
+      if (blastRes.status === "rejected") {
+        partial_errors.push(`blast_radius: ${String(blastRes.reason)}`);
+      }
+      if (includeLogs && logsRes.status === "rejected") {
+        partial_errors.push(`recent_logs: ${String(logsRes.reason)}`);
+      }
       const result = {
         report_id: args.report_id,
         severity,
         category,
         status,
+        partial_errors,
         report: reportRes.status === "fulfilled" ? reportRes.value : { error: String(reportRes.reason) },
         reporter_thread: evidenceRes.status === "fulfilled" ? evidenceRes.value : null,
         similar_bugs: similarRes.status === "fulfilled" ? similarRes.value : null,
@@ -1178,7 +1232,7 @@ function createMushiServer(config) {
       description: descOf("dispatch_fix"),
       annotations: annotationsFor("dispatch_fix"),
       inputSchema: {
-        reportId: z.string().describe("Report UUID to fix"),
+        reportId: z.string().uuid().describe("Report UUID to fix"),
         agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
         idempotencyKey: z.string().uuid().optional().describe("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
         inventoryActionNodeId: z.string().uuid().optional().describe("Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR.")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
   "mcpName": "io.github.kensaurus/mushi-mushi",
-  "version": "0.16.2",
+  "version": "0.17.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",
@@ -25,6 +25,10 @@
     "./feature-groups": {
       "types": "./dist/feature-groups.d.ts",
       "import": "./dist/feature-groups.js"
+    },
+    "./clients": {
+      "types": "./dist/clients.d.ts",
+      "import": "./dist/clients.js"
     }
   },
   "main": "./dist/index.js",
@@ -42,8 +46,9 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@sentry/node": "^10.57.0",
     "zod": "^4.4.3",
-    "@mushi-mushi/core": "^1.20.0"
+    "@mushi-mushi/core": "^1.22.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",