@mushi-mushi/mcp 0.24.4 → 0.24.6

package/dist/clients.d.ts

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

package/dist/clients.js

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

package/dist/index.js

@@ -1476,7 +1476,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/admin/billing",
     markdown: "admin/billing.md",
     keywords: ["admin", "billing"],
-    headings: ["Reading your usage card", "Usage breakdown", "Predictability controls", "Upgrading your plan", "Managing payment and invoices", "CLI parity", "Related docs"],
+    headings: ["Reading your usage card", "Usage breakdown", "Predictability controls", "Upgrading your plan", "Changing plan", "Managing payment and invoices", "CLI parity", "Related docs"],
     excerpt: "The Billing page shows your diagnosis quota, usage alerts at 50% and 80%, your projected bill, and spend caps for your Mushi plan."
   },
   {
@@ -1854,7 +1854,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/admin/research",
     markdown: "admin/research.md",
     keywords: ["admin", "research"],
-    headings: ["What it's for", "Running a search", "Saving results", "Prerequisites", "Related pages"],
+    headings: ["What it's for", "Running a search", "Saving results", "Automatic results on error reports", "Prerequisites", "Related pages"],
     excerpt: "The Research page runs a Firecrawl web search scoped to your tech stack and returns summarised answers with links to their sources."
   },
   {
@@ -3141,7 +3141,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/security/byok",
     markdown: "security/byok.md",
     keywords: ["security", "byok", "bring-your-own-key"],
-    headings: ["Setup", "What uses the key", "OpenRouter", "Audit trail", "Rotation", "Langfuse trace attribution"],
+    headings: ["Setup", "One key for every app", "What uses the key", "OpenRouter", "Audit trail", "Rotation", "Langfuse trace attribution"],
     excerpt: "Use your own Anthropic, OpenAI or OpenRouter key for a Mushi project, so every diagnosis, fix and grading run bills to your provider account."
   },
   {
@@ -5305,7 +5305,8 @@ function createMushiServer(config) {
       );
       const latest = data.latest ?? data.version;
       const current = args.current;
-      const outdated = current && latest ? current !== latest : void 0;
+      const pinned = current?.trim().replace(/^[\^~>=<v\s]+/, "");
+      const outdated = pinned && latest ? pinned !== latest : void 0;
       return jsonResult({
         package: data.package ?? pkg,
         latest,
@@ -7541,7 +7542,7 @@ function createSetupModeServer(config) {
     features: "all",
     ...config.fetch ? { fetch: config.fetch } : {},
     ...config.timeoutMs ? { timeoutMs: config.timeoutMs } : {},
-    instructions: "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
+    instructions: config.reason === "sdk-key" ? "Mushi is running in setup mode: the configured API key is an SDK key (report:write). It can send bug reports but not read them, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for how to mint an MCP key (mcp:read), then restart the MCP server." : "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
   });
   const internals = server;
   for (const [name, tool] of Object.entries(internals._registeredTools)) {
@@ -7556,7 +7557,8 @@ function createSetupModeServer(config) {
   }
   const spec = TOOL_CATALOG.find((t) => t.name === "diagnose_setup");
   if (!spec) throw new Error("[mushi-mcp] diagnose_setup is missing from TOOL_CATALOG");
-  const nextAction = "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
+  const sdkKey = config.reason === "sdk-key";
+  const nextAction = sdkKey ? `Mint an MCP key in the console (${MUSHI_CONSOLE_URL}/mcp \u2192 "Mint mcp:read key") or run \`mushi login\`, put it in MUSHI_API_KEY for this server, then restart it.` : "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
   server.registerTool(
     "diagnose_setup",
     {
@@ -7578,7 +7580,12 @@ function createSetupModeServer(config) {
         ready: false,
         mode: "setup",
         steps: [
-          {
+          sdkKey ? {
+            label: "MCP server key can read reports (mcp:read)",
+            complete: false,
+            required: true,
+            hint: `${nextAction} The SDK key (report:write) belongs in your app; MCP and the CLI need a key with mcp:read, or mcp:write to also triage and dispatch fixes.`
+          } : {
             label: "MCP server has an API key",
             complete: false,
             required: true,
@@ -7595,6 +7602,50 @@ function createSetupModeServer(config) {
   return server;
 }
 
+// src/key-scopes.ts
+async function fetchKeyScopes(opts) {
+  const doFetch = opts.fetch ?? fetch;
+  try {
+    const res = await doFetch(`${opts.apiEndpoint.replace(/\/+$/, "")}/v1/sync/whoami`, {
+      headers: {
+        "X-Mushi-Api-Key": opts.apiKey,
+        ...opts.projectId ? { "X-Mushi-Project-Id": opts.projectId } : {}
+      },
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 5e3)
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const scopes = body?.data?.scopes;
+    if (!Array.isArray(scopes)) return null;
+    return scopes.filter((s) => typeof s === "string");
+  } catch {
+    return null;
+  }
+}
+function decideScopes(keyScopes, configured) {
+  if (keyScopes === null) return { kind: "serve", scopes: configured };
+  const granted = /* @__PURE__ */ new Set();
+  if (keyScopes.includes("mcp:write")) {
+    granted.add("mcp:read");
+    granted.add("mcp:write");
+  } else if (keyScopes.includes("mcp:read")) {
+    granted.add("mcp:read");
+  }
+  if (granted.size === 0) return { kind: "sdk-key", keyScopes };
+  return { kind: "serve", scopes: configured.filter((s) => granted.has(s)) };
+}
+function sdkKeyReport(keyScopes, consoleUrl) {
+  const held = keyScopes.length > 0 ? keyScopes.join(", ") : "none";
+  return [
+    "",
+    `[mushi-mcp] This API key has scopes: ${held}. It can send bug reports (the SDK key) but not read them,`,
+    "            so the MCP tools would all be refused. Serving setup mode.",
+    `            Fix: mint an MCP key in the console (${consoleUrl}/mcp \u2192 "Mint mcp:read key"),`,
+    "            or run `mushi login`, then put it in MUSHI_API_KEY for this server and restart it.",
+    ""
+  ].join("\n");
+}
+
 // src/inventory-poll.ts
 function startInventoryPoll(options) {
   const doFetch = options.fetch ?? globalThis.fetch;
@@ -7854,6 +7905,23 @@ async function main() {
       );
     }
   }
+  let scopes = SCOPES;
+  if (!SCOPES_RAW) {
+    const keyScopes = await fetchKeyScopes({ apiEndpoint: API_ENDPOINT, apiKey: API_KEY, projectId: PROJECT_ID || void 0 });
+    const decision = decideScopes(keyScopes, SCOPES);
+    if (decision.kind === "sdk-key") {
+      const report = sdkKeyReport(decision.keyScopes, MUSHI_CONSOLE_URL);
+      process.stderr.write(report);
+      log.warn("The API key has no MCP scope (mcp:read / mcp:write) \u2014 serving setup mode.", {
+        keyScopes: decision.keyScopes.join(",")
+      });
+      serveUntilClosed(serveStdio(() => createSetupModeServer({ version: VERSION, missingKeyReport: report, reason: "sdk-key" }), {
+        onerror: (err) => log.error("stdio transport error", { err: String(err) })
+      }));
+      return;
+    }
+    scopes = decision.scopes;
+  }
   const mode = PROJECT_ID ? "single-project" : "account";
   if (!PROJECT_ID) {
     log.info(
@@ -7865,7 +7933,7 @@ async function main() {
     mode,
     endpoint: API_ENDPOINT,
     hasProjectId: !!PROJECT_ID,
-    scopes: SCOPES.join(",")
+    scopes: scopes.join(",")
   });
   let server;
   const handle = serveStdio(
@@ -7875,7 +7943,7 @@ async function main() {
         apiEndpoint: API_ENDPOINT,
         apiKey: API_KEY,
         projectId: PROJECT_ID || void 0,
-        scopes: SCOPES,
+        scopes,
         features: FEATURES
       });
       log.debug("[mushi-mcp] server instance created", { era: ctx.era });

package/dist/server.d.ts

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

package/dist/server.js

@@ -86,7 +86,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/admin/billing",
     markdown: "admin/billing.md",
     keywords: ["admin", "billing"],
-    headings: ["Reading your usage card", "Usage breakdown", "Predictability controls", "Upgrading your plan", "Managing payment and invoices", "CLI parity", "Related docs"],
+    headings: ["Reading your usage card", "Usage breakdown", "Predictability controls", "Upgrading your plan", "Changing plan", "Managing payment and invoices", "CLI parity", "Related docs"],
     excerpt: "The Billing page shows your diagnosis quota, usage alerts at 50% and 80%, your projected bill, and spend caps for your Mushi plan."
   },
   {
@@ -464,7 +464,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/admin/research",
     markdown: "admin/research.md",
     keywords: ["admin", "research"],
-    headings: ["What it's for", "Running a search", "Saving results", "Prerequisites", "Related pages"],
+    headings: ["What it's for", "Running a search", "Saving results", "Automatic results on error reports", "Prerequisites", "Related pages"],
     excerpt: "The Research page runs a Firecrawl web search scoped to your tech stack and returns summarised answers with links to their sources."
   },
   {
@@ -1751,7 +1751,7 @@ var MUSHI_DOCS_INDEX = [
     route: "/security/byok",
     markdown: "security/byok.md",
     keywords: ["security", "byok", "bring-your-own-key"],
-    headings: ["Setup", "What uses the key", "OpenRouter", "Audit trail", "Rotation", "Langfuse trace attribution"],
+    headings: ["Setup", "One key for every app", "What uses the key", "OpenRouter", "Audit trail", "Rotation", "Langfuse trace attribution"],
     excerpt: "Use your own Anthropic, OpenAI or OpenRouter key for a Mushi project, so every diagnosis, fix and grading run bills to your provider account."
   },
   {
@@ -3981,7 +3981,8 @@ function createMushiServer(config) {
       );
       const latest = data.latest ?? data.version;
       const current = args.current;
-      const outdated = current && latest ? current !== latest : void 0;
+      const pinned = current?.trim().replace(/^[\^~>=<v\s]+/, "");
+      const outdated = pinned && latest ? pinned !== latest : void 0;
       return jsonResult({
         package: data.package ?? pkg,
         latest,
@@ -6217,7 +6218,7 @@ function createSetupModeServer(config) {
     features: "all",
     ...config.fetch ? { fetch: config.fetch } : {},
     ...config.timeoutMs ? { timeoutMs: config.timeoutMs } : {},
-    instructions: "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
+    instructions: config.reason === "sdk-key" ? "Mushi is running in setup mode: the configured API key is an SDK key (report:write). It can send bug reports but not read them, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for how to mint an MCP key (mcp:read), then restart the MCP server." : "Mushi is running in setup mode: no API key is configured, so only search_mushi_docs, get_mushi_doc and diagnose_setup work. Call diagnose_setup for the exact steps to connect (run `npx mushi-mushi` or `mushi login`, or put MUSHI_API_KEY in this server's env block), then restart the MCP server."
   });
   const internals = server;
   for (const [name, tool] of Object.entries(internals._registeredTools)) {
@@ -6232,7 +6233,8 @@ function createSetupModeServer(config) {
   }
   const spec = TOOL_CATALOG.find((t) => t.name === "diagnose_setup");
   if (!spec) throw new Error("[mushi-mcp] diagnose_setup is missing from TOOL_CATALOG");
-  const nextAction = "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
+  const sdkKey = config.reason === "sdk-key";
+  const nextAction = sdkKey ? `Mint an MCP key in the console (${MUSHI_CONSOLE_URL}/mcp \u2192 "Mint mcp:read key") or run \`mushi login\`, put it in MUSHI_API_KEY for this server, then restart it.` : "Run `npx mushi-mushi` in your project (signs you in and writes the key) or `mushi login`, then restart this MCP server.";
   server.registerTool(
     "diagnose_setup",
     {
@@ -6254,7 +6256,12 @@ function createSetupModeServer(config) {
         ready: false,
         mode: "setup",
         steps: [
-          {
+          sdkKey ? {
+            label: "MCP server key can read reports (mcp:read)",
+            complete: false,
+            required: true,
+            hint: `${nextAction} The SDK key (report:write) belongs in your app; MCP and the CLI need a key with mcp:read, or mcp:write to also triage and dispatch fixes.`
+          } : {
             label: "MCP server has an API key",
             complete: false,
             required: true,
@@ -6271,6 +6278,7 @@ function createSetupModeServer(config) {
   return server;
 }
 export {
+  MUSHI_CONSOLE_URL,
   MushiApiError,
   SETUP_MODE_TOOLS,
   createMushiServer,

package/package.json

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