@mushi-mushi/mcp 0.16.1 → 0.17.0

package/CONTRIBUTING.md

@@ -27,12 +27,24 @@ pnpm build
 
 ```bash
 pnpm dev          # Start all dev servers (admin on :6464)
+```
+
+| Surface | URL |
+| --- | --- |
+| Admin console | http://localhost:6464 |
+| Docs site | http://localhost:3000 |
+| CLI console override | `MUSHI_CONSOLE_URL=http://localhost:6464` |
+
+```bash
 pnpm test         # Run Vitest across all packages
 pnpm typecheck    # TypeScript checks
 pnpm lint         # ESLint
 pnpm format       # Prettier
+pnpm smoke:cli-setup   # Playwright: onboarding ?setup=cli + success panel (skips headless if unsigned)
 ```
 
+Set `CLI_SETUP_SMOKE_STRICT=1` to fail the smoke script when Playwright is not signed in (CI gate).
+
 Ad-hoc screenshots captured during UI reviews can live temporarily at the repo
 root, but root-level `*.png` files are intentionally ignored. Canonical
 screenshots that should be versioned belong under `docs/screenshots/`.
@@ -58,7 +70,7 @@ packages/
   react-native/  React Native SDK (MIT)
   cli/           CLI tool (MIT)
   mcp/           MCP server for coding agents (MIT)
-  server/        Supabase Edge Functions (AGPLv3)
+  server/        Supabase Edge Functions (AGPLv3; ee/ is commercial)
   agents/        Agentic fix pipeline (AGPLv3)
   verify/        Fix verification (AGPLv3)
 apps/
@@ -69,6 +81,18 @@ tooling/
   tsconfig/      Shared TypeScript configs
 ```
 
+## What we don't accept
+
+Knowing this upfront saves everyone time.
+
+- **Automated / bulk / AI-slop PRs** — any PR that was opened by a script, an LLM agent acting without meaningful human review, or as part of a parallel bounty-farming sweep is closed on sight. The commit history, branch name, or helper scripts included in the PR make this obvious.
+- **PRs that target the wrong base** — all PRs must branch from and target `master`. PRs targeting `main` or any other branch are closed (and will show an inflated diff that is not your work).
+- **One PR per issue, one issue per PR** — splitting or duplicating work just to collect acknowledgements isn't welcome.
+- **Good-first-issues without claiming first** — comment on the issue to claim it before starting. If two people open PRs for the same issue, the one that commented first is prioritised.
+- **Documentation-only PRs that merely duplicate existing content** — if the information already exists (e.g. in another file in this repo), adding a redundant copy adds noise without value.
+
+If a PR violates these policies it will be closed with a brief explanation. No hard feelings — a genuine contribution on the same issue is always welcome.
+
 ## Making Changes
 
 1. Create a feature branch from `master`
@@ -187,7 +211,7 @@ chore: bump dependencies
 ## License
 
 - SDK packages are MIT — your contributions will be MIT-licensed
-- Server/agents/verify are AGPLv3 — contributions to those packages fall under AGPLv3
+- Server/agents/verify are AGPLv3 — contributions to those packages fall under AGPLv3. A [commercial license](./COMMERCIAL-LICENSE.md) is available for hosted-SaaS use cases that cannot publish modifications. The `packages/server/ee/` directory is source-available but commercial (production use needs a license); contributions there are accepted under the same EE terms.
 
 ## Questions?
 

package/SECURITY.md

@@ -113,7 +113,7 @@ What we treat as in-scope attacker capabilities, and what we don't.
 | Compromised Supabase service-role key | ❌ | Treated as a tier-0 incident; would require key rotation and audit-log forensics. Not defendable in software. |
 | Compromise of `kensaurus@gmail.com` | ❌ | Treated as a project-fork event; downstream consumers should pin to the last known-good version and follow the new release channel. |
 | Physical / OS-level attacker on an end-user device | ❌ | Out of scope. |
-| Malicious fork using the Mushi name to ship malware | ❌ (technical) ✅ (legal) | The MIT/BSL grant lets the fork exist; the trademark policy (`TRADEMARK.md`) makes shipping it under the Mushi name an infringement we will pursue. |
+| Malicious fork using the Mushi name to ship malware | ❌ (technical) ✅ (legal) | The MIT / AGPLv3 grant lets the fork exist; the trademark policy (`TRADEMARK.md`) makes shipping it under the Mushi name an infringement we will pursue. |
 
 ## Data handling and PII
 

package/dist/catalog.js

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

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

@@ -534,6 +534,15 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: 'Did "Add to Slack" work? Send a test ping to confirm.'
   },
+  // ── Billing / usage tools ─────────────────────────────────────────────────
+  {
+    name: "get_usage",
+    title: "Usage & billing summary",
+    description: 'Read-only diagnoses quota and billing summary for the current project: diagnoses used / limit / percentage, spend cap, period start/end, plan name, and whether the project is approaching or over its quota. Use this to answer "how many diagnoses do I have left?" or "am I close to my spend cap?".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: false },
+    useCase: "How many diagnoses do I have left this month?"
+  },
   // ── Skill Pipeline tools ─────────────────────────────────────────────────────
   {
     name: "list_skills",

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

@@ -10,6 +10,7 @@ var FEATURE_GROUPS = [
   "admin",
   "audit",
   "docs",
+  "usage",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];
@@ -82,6 +83,8 @@ var TOOL_FEATURE_MAP = {
   project_settings: "admin",
   privacy_status: "admin",
   evolution_history: "admin",
+  // usage / billing
+  get_usage: "usage",
   // qa / tdd
   map_user_stories: "qa",
   get_map_run_status: "qa",

package/dist/clients.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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;
+}
+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[]): 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,250 @@
+import {
+  MUSHI_ICON_PNG_URL
+} from "./chunk-EHB2BGWX.js";
+import {
+  DEFAULT_FEATURE_GROUPS,
+  appendFeaturesToUrl,
+  featuresQueryString
+} from "./chunk-ZX3XIJ7S.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 buildHttpConfigObj(projectId, apiKey, mcpHttpUrl, features = DEFAULT_FEATURE_GROUPS) {
+  const url = appendFeaturesToUrl(mcpHttpUrl, features);
+  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 }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const config = buildStdioConfigObj(projectId, apiKey, endpoint);
+      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 }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const config = buildStdioConfigObj(projectId, apiKey, endpoint);
+      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 }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const config = buildStdioConfigObj(projectId, apiKey, endpoint);
+      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 }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const url = appendFeaturesToUrl(mcpHttpUrl, DEFAULT_FEATURE_GROUPS);
+      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 }) {
+      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 (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 }) {
+      const name = projectId ? projectServerName(projectId, projectName) : `mushi-${projectName.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 24)}`;
+      const url = appendFeaturesToUrl(mcpHttpUrl, DEFAULT_FEATURE_GROUPS);
+      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 }) {
+      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 (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 }) {
+      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 (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 }) {
+      const url = appendFeaturesToUrl(mcpHttpUrl, DEFAULT_FEATURE_GROUPS);
+      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", "legacy"];
+declare const FEATURE_GROUPS: readonly ["triage", "fixes", "inventory", "setup", "qa", "skills", "rewards", "admin", "audit", "docs", "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-B2QEG35D.js";
+} from "./chunk-ZX3XIJ7S.js";
 export {
   ALL_FEATURE_GROUPS,
   DEFAULT_FEATURE_GROUPS,

package/dist/index.js

@@ -457,6 +457,15 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: 'Did "Add to Slack" work? Send a test ping to confirm.'
   },
+  // ── Billing / usage tools ─────────────────────────────────────────────────
+  {
+    name: "get_usage",
+    title: "Usage & billing summary",
+    description: 'Read-only diagnoses quota and billing summary for the current project: diagnoses used / limit / percentage, spend cap, period start/end, plan name, and whether the project is approaching or over its quota. Use this to answer "how many diagnoses do I have left?" or "am I close to my spend cap?".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: false },
+    useCase: "How many diagnoses do I have left this month?"
+  },
   // ── Skill Pipeline tools ─────────────────────────────────────────────────────
   {
     name: "list_skills",
@@ -603,6 +612,7 @@ var FEATURE_GROUPS = [
   "admin",
   "audit",
   "docs",
+  "usage",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];
@@ -668,6 +678,8 @@ var TOOL_FEATURE_MAP = {
   project_settings: "admin",
   privacy_status: "admin",
   evolution_history: "admin",
+  // usage / billing
+  get_usage: "usage",
   // qa / tdd
   map_user_stories: "qa",
   get_map_run_status: "qa",
@@ -921,7 +933,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(
@@ -952,6 +973,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) }]
@@ -1033,11 +1059,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,
@@ -1128,7 +1158,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(),
@@ -1139,7 +1172,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()
@@ -1159,9 +1195,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",
@@ -1791,18 +1833,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";
@@ -2699,6 +2742,23 @@ Be specific. No generic advice.`
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
+  server.registerTool(
+    "get_usage",
+    {
+      title: titleOf("get_usage"),
+      description: descOf("get_usage"),
+      annotations: annotationsFor("get_usage"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project ID. Defaults to the configured project.")
+      }
+    },
+    async ({ project_id }) => {
+      const pid = project_id ?? config.projectId;
+      const path = pid ? `/v1/admin/billing/stats?project_id=${pid}` : "/v1/admin/billing/stats";
+      const data = await apiCall(path);
+      return jsonText(data);
+    }
+  );
   server.registerTool(
     "list_skills",
     {
@@ -3020,6 +3080,32 @@ Be specific. No generic advice.`
       }
     }
   }
+  const _nativeFetch = globalThis.fetch;
+  let _firstToolCallSignalled = false;
+  const _signalFirstToolCall = () => {
+    if (_firstToolCallSignalled || !projectId) return;
+    _firstToolCallSignalled = true;
+    void _nativeFetch(`${apiEndpoint}/v1/cli/funnel`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mushi-Api-Key": apiKey,
+        "X-Mushi-Project": projectId
+      },
+      body: JSON.stringify({ event: "mcp_first_tool_call" }),
+      signal: AbortSignal.timeout(4e3)
+    }).catch(() => {
+    });
+  };
+  const llServer = server.server;
+  const existingToolsCallHandler = llServer?._requestHandlers?.get("tools/call");
+  if (typeof existingToolsCallHandler === "function") {
+    llServer._requestHandlers.set("tools/call", async (...args) => {
+      const result = await existingToolsCallHandler(...args);
+      _signalFirstToolCall();
+      return result;
+    });
+  }
   return server;
 }
 

package/dist/server.js

@@ -2,13 +2,13 @@ import {
   CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-UYZEIJ5G.js";
+} from "./chunk-MM3IMFM4.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EHB2BGWX.js";
 import {
   toolMatchesFeatures
-} from "./chunk-B2QEG35D.js";
+} from "./chunk-ZX3XIJ7S.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -199,7 +199,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 +239,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 +325,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,
@@ -406,7 +424,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 +438,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 +461,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",
@@ -1069,18 +1099,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";
@@ -1977,6 +2008,23 @@ Be specific. No generic advice.`
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
+  server.registerTool(
+    "get_usage",
+    {
+      title: titleOf("get_usage"),
+      description: descOf("get_usage"),
+      annotations: annotationsFor("get_usage"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project ID. Defaults to the configured project.")
+      }
+    },
+    async ({ project_id }) => {
+      const pid = project_id ?? config.projectId;
+      const path = pid ? `/v1/admin/billing/stats?project_id=${pid}` : "/v1/admin/billing/stats";
+      const data = await apiCall(path);
+      return jsonText(data);
+    }
+  );
   server.registerTool(
     "list_skills",
     {
@@ -2298,6 +2346,32 @@ Be specific. No generic advice.`
       }
     }
   }
+  const _nativeFetch = globalThis.fetch;
+  let _firstToolCallSignalled = false;
+  const _signalFirstToolCall = () => {
+    if (_firstToolCallSignalled || !projectId) return;
+    _firstToolCallSignalled = true;
+    void _nativeFetch(`${apiEndpoint}/v1/cli/funnel`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mushi-Api-Key": apiKey,
+        "X-Mushi-Project": projectId
+      },
+      body: JSON.stringify({ event: "mcp_first_tool_call" }),
+      signal: AbortSignal.timeout(4e3)
+    }).catch(() => {
+    });
+  };
+  const llServer = server.server;
+  const existingToolsCallHandler = llServer?._requestHandlers?.get("tools/call");
+  if (typeof existingToolsCallHandler === "function") {
+    llServer._requestHandlers.set("tools/call", async (...args) => {
+      const result = await existingToolsCallHandler(...args);
+      _signalFirstToolCall();
+      return result;
+    });
+  }
   return server;
 }
 export {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
   "mcpName": "io.github.kensaurus/mushi-mushi",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "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,15 +46,15 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.2",
-    "@mushi-mushi/core": "^1.16.0"
+    "zod": "^4.4.3",
+    "@mushi-mushi/core": "^1.21.0"
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
-    "eslint": "^10.3.0",
+    "@types/node": "^22.19.21",
+    "eslint": "^10.4.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
+    "vitest": "^4.1.8",
     "@mushi-mushi/eslint-config": "0.0.0"
   },
   "repository": {
@@ -58,8 +62,8 @@
     "url": "https://github.com/kensaurus/mushi-mushi.git",
     "directory": "packages/mcp"
   },
-  "author": "Kenji Sakuramoto",
-  "homepage": "https://github.com/kensaurus/mushi-mushi/tree/main/packages/mcp#readme",
+  "author": "Kenji Sakuramoto (https://bsky.app/profile/mushimushi.dev)",
+  "homepage": "https://kensaur.us/mushi-mushi",
   "bugs": {
     "url": "https://github.com/kensaurus/mushi-mushi/issues"
   },
@@ -94,6 +98,10 @@
   "engines": {
     "node": ">=20"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/kensaurus"
+  },
   "scripts": {
     "build": "tsup",
     "clean:types": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",