@mushi-mushi/mcp 0.20.1 → 0.20.2

package/dist/server.d.ts

@@ -19,6 +19,8 @@ import { FeatureFilter } from './feature-groups.js';
  *          a proxy strips first.
  */
 
+/** Resolve the per-request timeout from `MUSHI_MCP_TIMEOUT_MS`, clamped. Exported for tests. */
+declare function resolveTimeoutMsFromEnv(): number;
 declare class MushiApiError extends Error {
     readonly status: number;
     readonly code: string;
@@ -49,6 +51,12 @@ interface MushiServerConfig {
      * Set via `MUSHI_FEATURES` env (CSV) on stdio; HTTP uses `?features=` query.
      */
     features?: FeatureFilter;
+    /**
+     * Per-request timeout in ms for every Mushi API call a tool makes.
+     * Defaults to `MUSHI_MCP_TIMEOUT_MS` (clamped to 250ms…5min) or 15000.
+     * Explicit values are honoured as given — tests use small ones.
+     */
+    timeoutMs?: number;
 }
 /**
  * Build an MCP server instance pre-wired with every Mushi tool, resource,
@@ -57,4 +65,4 @@ interface MushiServerConfig {
  */
 declare function createMushiServer(config: MushiServerConfig): McpServer;
 
-export { MushiApiError, type MushiServerConfig, createMushiServer };
+export { MushiApiError, type MushiServerConfig, createMushiServer, resolveTimeoutMsFromEnv };

package/dist/server.js

@@ -3,7 +3,7 @@ import {
   TDD_TOOL_CATALOG,
   TOOL_CATALOG,
   USE_MUSHI_INTENTS
-} from "./chunk-TP2QQWDJ.js";
+} from "./chunk-RVZIKP4X.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EANW5YTI.js";
@@ -143,8 +143,107 @@ function wrapUntrustedJson(value, role) {
   return wrapUntrusted(serialised, role);
 }
 
+// src/stdout-guard.ts
+import { Console } from "console";
+var GUARDED_CONSOLE_METHODS = [
+  "log",
+  "info",
+  "debug",
+  "dir",
+  "dirxml",
+  "table",
+  "group",
+  "groupCollapsed",
+  "groupEnd",
+  "count",
+  "countReset",
+  "time",
+  "timeEnd",
+  "timeLog",
+  "trace",
+  "assert",
+  "warn",
+  "error"
+];
+var installed = false;
+function installStdoutGuard() {
+  if (installed) return false;
+  if (typeof process !== "undefined" && process.env?.MUSHI_MCP_STDOUT_GUARD === "off") {
+    return false;
+  }
+  if (typeof process === "undefined" || typeof process.stderr?.write !== "function" || typeof console === "undefined") {
+    return false;
+  }
+  try {
+    const stderrConsole = new Console({
+      stdout: process.stderr,
+      stderr: process.stderr,
+      // Colour codes would land in the client's log pane as escape noise.
+      colorMode: false
+    });
+    const target = console;
+    const source = stderrConsole;
+    for (const method of GUARDED_CONSOLE_METHODS) {
+      const fn = source[method];
+      if (typeof fn === "function") {
+        target[method] = fn.bind(stderrConsole);
+      }
+    }
+  } catch {
+    const write = (...args) => process.stderr.write(
+      args.map((a) => typeof a === "string" ? a : safeStringify(a)).join(" ") + "\n"
+    );
+    const target = console;
+    for (const method of GUARDED_CONSOLE_METHODS) {
+      target[method] = write;
+    }
+  }
+  installed = true;
+  return true;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
 // src/server.ts
+installStdoutGuard();
 var NO_ARG_INPUT = {};
+var DEFAULT_API_TIMEOUT_MS = 15e3;
+var MIN_API_TIMEOUT_MS = 250;
+var MAX_API_TIMEOUT_MS = 3e5;
+function resolveTimeoutMsFromEnv() {
+  const raw = process.env?.MUSHI_MCP_TIMEOUT_MS?.trim();
+  if (!raw) return DEFAULT_API_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_API_TIMEOUT_MS;
+  return Math.min(Math.max(parsed, MIN_API_TIMEOUT_MS), MAX_API_TIMEOUT_MS);
+}
+function bareMessage(err) {
+  const raw = err instanceof Error ? err.message : String(err);
+  return raw.replace(/^\[[A-Z0-9_]+\]\s*/, "");
+}
+var IDEMPOTENCY_NAMESPACE = "mushi.mcp.submit_fix_result.v1";
+async function stableUuidFrom(...parts) {
+  const input = parts.join("");
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input))
+  );
+  const bytes = digest.slice(0, 16);
+  bytes[6] = bytes[6] & 15 | 80;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+function withTimeoutSignal(callerSignal, timeoutSignal) {
+  if (!callerSignal) return timeoutSignal;
+  const anyFn = AbortSignal.any;
+  if (typeof anyFn === "function") return anyFn.call(AbortSignal, [callerSignal, timeoutSignal]);
+  return timeoutSignal;
+}
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -158,6 +257,7 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const timeoutMs = typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : resolveTimeoutMsFromEnv();
   const apiLog = createLogger({
     scope: "mushi:mcp:api",
     level: process.env.MUSHI_LOG_LEVEL ?? "info",
@@ -175,22 +275,66 @@ function createMushiServer(config) {
   async function apiCall(path, options) {
     const requestId = crypto.randomUUID().slice(0, 12);
     const started = Date.now();
-    const res = await doFetch(`${apiEndpoint}${path}`, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
-        // still send it for endpoints still behind plain `jwtAuth` (legacy)
-        // and for transparent proxies that strip X-Mushi-* headers.
-        Authorization: `Bearer ${apiKey}`,
-        "X-Mushi-Api-Key": apiKey,
-        "X-Request-Id": requestId,
-        ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
-        ...options?.headers ?? {}
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    let res;
+    try {
+      res = await doFetch(`${apiEndpoint}${path}`, {
+        ...options,
+        headers: {
+          "Content-Type": "application/json",
+          // Authorization is accepted by `adminOrApiKey` only as a JWT, but we
+          // still send it for endpoints still behind plain `jwtAuth` (legacy)
+          // and for transparent proxies that strip X-Mushi-* headers.
+          Authorization: `Bearer ${apiKey}`,
+          "X-Mushi-Api-Key": apiKey,
+          "X-Request-Id": requestId,
+          ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
+          ...options?.headers ?? {}
+        },
+        // After the spread so a caller-supplied `signal` is merged, not lost.
+        signal: withTimeoutSignal(options?.signal, timeoutSignal)
+      });
+    } catch (err) {
+      throw classifyTransportError(err);
+    }
+    let text;
+    try {
+      text = await res.text();
+    } catch (err) {
+      throw classifyTransportError(err);
+    }
+    function classifyTransportError(err) {
+      const durationMs2 = Date.now() - started;
+      if (timeoutSignal.aborted) {
+        apiLog.warn("api.timeout", { path, requestId, durationMs: durationMs2, timeoutMs });
+        return new MushiApiError(
+          504,
+          "MUSHI_TIMEOUT",
+          `Timed out after ${timeoutMs}ms waiting for ${path}. The Mushi API accepted the connection but did not answer in time \u2014 retry, or raise the budget with MUSHI_MCP_TIMEOUT_MS (ms) in your MCP env block if you self-host and cold starts are slow. Endpoint: ${apiEndpoint}`
+        );
       }
-    });
+      const name = err instanceof Error ? err.name : "";
+      if (name === "AbortError") {
+        apiLog.warn("api.aborted", { path, requestId, durationMs: durationMs2 });
+        return new MushiApiError(
+          499,
+          "REQUEST_ABORTED",
+          `The request to ${path} was aborted by the caller after ${durationMs2}ms.`
+        );
+      }
+      apiLog.warn("api.unreachable", {
+        path,
+        requestId,
+        durationMs: durationMs2,
+        err: bareMessage(err)
+      });
+      return new MushiApiError(
+        503,
+        "NETWORK_ERROR",
+        `Could not reach the Mushi API at ${apiEndpoint}${path} \u2014 ${bareMessage(err)}. This is a connectivity failure, not an API rejection: check that you are online, that MUSHI_API_ENDPOINT points at your \`.../functions/v1/api\` URL, and that no proxy/VPN is blocking it.`
+      );
+    }
     const durationMs = Date.now() - started;
-    const text = await res.text();
     let body = null;
     if (text) {
       try {
@@ -220,6 +364,7 @@ function createMushiServer(config) {
     apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
     return body;
   }
+  let resolvedAccountProjectId = null;
   async function resolveProjectId(explicitId) {
     if (explicitId) {
       if (projectId && explicitId !== projectId) {
@@ -232,10 +377,12 @@ function createMushiServer(config) {
       return explicitId;
     }
     if (projectId) return projectId;
+    if (resolvedAccountProjectId) return resolvedAccountProjectId;
     try {
       const data = await apiCall("/v1/admin/mcp/account-overview");
       if (data.total === 1 && data.projects[0]) {
-        return data.projects[0].id;
+        resolvedAccountProjectId = data.projects[0].id;
+        return resolvedAccountProjectId;
       }
       if (data.total === 0) {
         throw new MushiApiError(
@@ -251,11 +398,27 @@ function createMushiServer(config) {
         `Multiple projects are accessible with this key: ${projectList}. Pass projectId explicitly to target a specific project, or set MUSHI_PROJECT_ID in your MCP env config.`
       );
     } catch (err) {
-      if (err instanceof MushiApiError) throw err;
+      if (err instanceof MushiApiError) {
+        if (err.code === "MUSHI_TIMEOUT" || err.code === "NETWORK_ERROR") {
+          throw new MushiApiError(
+            err.status,
+            err.code,
+            `Could not resolve which project to use because the Mushi API is unreachable: ${bareMessage(err)} This is a connectivity problem \u2014 setting MUSHI_PROJECT_ID would only skip the lookup, not fix the tool call that follows it.`
+          );
+        }
+        if (err.status === 401 || err.status === 403) {
+          throw new MushiApiError(
+            err.status,
+            err.code,
+            `The API key was rejected while resolving the project: ${bareMessage(err)} Mint a fresh key in the console (Settings \u2192 API keys) and update MUSHI_API_KEY, or re-run \`mushi login\`. This is an authentication problem, not a missing project id.`
+          );
+        }
+        throw err;
+      }
       throw new MushiApiError(
         400,
         "MISSING_PROJECT_ID",
-        "projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly."
+        `projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly. (Project lookup failed with: ${bareMessage(err)})`
       );
     }
   }
@@ -679,12 +842,24 @@ function createMushiServer(config) {
         suggestedFix: z.unknown().describe("Stage-2 suggested fix, or null if not yet classified"),
         reproductionSteps: z.unknown().describe("Reproduction steps recorded on the report (array; [] if none)"),
         summary: z.unknown().describe("One-line report summary, or null"),
-        component: z.unknown().describe("Component/page the bug was attributed to, or null")
+        component: z.unknown().describe("Component/page the bug was attributed to, or null"),
+        note: z.string().optional().describe("Present when no Stage-2 analysis exists \u2014 explains why and what to call instead")
       }
     },
     async (args) => {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       const s2 = report.stage2_analysis;
+      if (!s2 || s2.rootCause == null && s2.suggestedFix == null) {
+        return jsonResult({
+          reportId: args.reportId,
+          rootCause: null,
+          suggestedFix: null,
+          reproductionSteps: report.reproduction_steps ?? [],
+          summary: report.summary ?? null,
+          component: report.component ?? null,
+          note: "No Stage-2 analysis exists for this report (it was classified by the fast Stage-1 path, which does not produce root-cause/fix hints). Use triage_issue for the full review packet, or dispatch_fix \u2014 the fix worker does its own grounded analysis."
+        });
+      }
       return jsonResult({
         reportId: args.reportId,
         rootCause: s2?.rootCause ?? null,
@@ -1115,12 +1290,31 @@ function createMushiServer(config) {
       const category = report ? report.category : "unknown";
       const status = report ? report.status : "unknown";
       const actions = [];
-      if (status === "new" || status === "classified") {
+      const processingError = report ? report.processing_error : null;
+      const attempts = report ? report.fix_attempts ?? [] : [];
+      const lastAttempt = attempts.length > 0 ? attempts[attempts.length - 1] : null;
+      const lastAttemptStatus = lastAttempt ? String(lastAttempt.status ?? "") : "";
+      const autofixBlocked = typeof processingError === "string" && processingError.startsWith("autofix_blocked:") || lastAttemptStatus.startsWith("skipped") || lastAttemptStatus === "failed";
+      if (autofixBlocked && status !== "fixing" && status !== "fixed") {
+        const blockReason = typeof processingError === "string" && processingError || String(lastAttempt?.error ?? "previous fix attempt was skipped or failed");
+        actions.push({
+          action: "unblock_autofix",
+          reason: `Auto-fix is blocked: ${blockReason}. Resolve the blocker (settings/integration/budget), then re-dispatch.`,
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+        actions.push({
+          action: "redispatch_after_unblock",
+          reason: "Once the blocker above is resolved, dispatch a fresh fix attempt.",
+          tool: "dispatch_fix",
+          args: { reportId: args.report_id }
+        });
+      } else if (status === "new" || status === "classified") {
         actions.push({
           action: "dispatch_fix",
-          reason: "Report is classified but no fix has been attempted",
+          reason: "Report is classified and no fix has been attempted",
           tool: "dispatch_fix",
-          args: { reportId: args.report_id, agent: "cursor_cloud" }
+          args: { reportId: args.report_id }
         });
       } else if (status === "fixing") {
         actions.push({
@@ -1198,7 +1392,7 @@ function createMushiServer(config) {
         linesChanged: z.number().describe("Total lines added + removed across filesChanged"),
         summary: z.string().describe("One-line human summary of what the fix changed"),
         idempotencyKey: z.string().uuid().optional().describe(
-          "Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows"
+          "Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows. Omit it and a stable key is derived from reportId + branch + prUrl, so a retried submission carries the identical key instead of a fresh random one."
         )
       },
       outputSchema: {
@@ -1207,27 +1401,123 @@ function createMushiServer(config) {
       }
     },
     async (args) => {
-      const idemKey = args.idempotencyKey ?? crypto.randomUUID();
+      const idemKey = args.idempotencyKey ?? await stableUuidFrom(
+        IDEMPOTENCY_NAMESPACE,
+        args.reportId,
+        args.branch,
+        args.prUrl ?? ""
+      );
       const created = await apiCall("/v1/admin/fixes", {
         method: "POST",
         headers: { "Idempotency-Key": idemKey },
         body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
       });
-      await apiCall(`/v1/admin/fixes/${created.fixId}`, {
-        method: "PATCH",
-        body: JSON.stringify({
-          status: "completed",
-          branch: args.branch,
-          pr_url: args.prUrl,
-          files_changed: args.filesChanged,
-          lines_changed: args.linesChanged,
-          summary: args.summary,
-          completed_at: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      });
+      try {
+        await apiCall(`/v1/admin/fixes/${created.fixId}`, {
+          method: "PATCH",
+          body: JSON.stringify({
+            status: "completed",
+            branch: args.branch,
+            pr_url: args.prUrl,
+            files_changed: args.filesChanged,
+            lines_changed: args.linesChanged,
+            summary: args.summary,
+            completed_at: (/* @__PURE__ */ new Date()).toISOString()
+          })
+        });
+      } catch (err) {
+        const status = err instanceof MushiApiError ? err.status : 500;
+        throw new MushiApiError(
+          status,
+          "FIX_PATCH_FAILED",
+          `Fix row ${created.fixId} was created for report ${args.reportId}, but marking it completed failed: ${bareMessage(err)} \u2014 the fix row exists and is still in its initial (pending) state, so no work is lost. Preferred repair: PATCH /v1/admin/fixes/${created.fixId} with {"status":"completed"} to finish this exact row. Re-running submit_fix_result re-sends the same derived Idempotency-Key (reportId + branch + prUrl) rather than a fresh one, so it dedupes wherever the API honours that header \u2014 retry only with identical arguments.`
+        );
+      }
       return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
+  server.registerTool(
+    "triage_next_steps",
+    {
+      title: titleOf("triage_next_steps"),
+      description: descOf("triage_next_steps"),
+      annotations: annotationsFor("triage_next_steps"),
+      inputSchema: {
+        project_id: z.string().uuid().optional().describe("Project UUID (defaults to the configured project).")
+      },
+      outputSchema: {
+        steps: z.array(
+          z.object({
+            priority: z.number(),
+            action: z.string(),
+            reason: z.string(),
+            tool: z.string().optional(),
+            args: z.record(z.string(), z.unknown()).optional()
+          })
+        ),
+        summary: z.string()
+      }
+    },
+    async (args) => {
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const data = await apiCall(
+        "/v1/admin/reports?limit=100",
+        { headers: extraHeaders }
+      );
+      const reports = data.reports ?? [];
+      const isCron = (r) => typeof r.reporter_token_hash === "string" && r.reporter_token_hash.startsWith("cron:");
+      const isBlocked = (r) => typeof r.processing_error === "string" && r.processing_error.startsWith("autofix_blocked:");
+      const label = (r) => String(r.title ?? r.summary ?? r.description ?? "").slice(0, 90);
+      const steps = [];
+      let priority = 1;
+      const blocked = reports.filter(isBlocked);
+      if (blocked.length > 0) {
+        steps.push({
+          priority: priority++,
+          action: `Unblock auto-fix (${blocked.length} report${blocked.length === 1 ? "" : "s"} blocked)`,
+          reason: String(blocked[0].processing_error).slice(0, 200),
+          tool: "diagnose_setup",
+          args: { mode: "dispatch" }
+        });
+      }
+      const fixing = reports.filter((r) => r.status === "fixing");
+      for (const r of fixing.slice(0, 2)) {
+        steps.push({
+          priority: priority++,
+          action: `Shepherd in-flight fix: ${label(r)}`,
+          reason: "A fix branch/PR is open \u2014 check CI and merge when green.",
+          tool: "get_report_timeline",
+          args: { report_id: r.id }
+        });
+      }
+      const openUserReports = reports.filter((r) => (r.status === "new" || r.status === "classified") && !isCron(r) && !isBlocked(r)).sort((a, b) => {
+        const rank = { critical: 0, high: 1, medium: 2, low: 3 };
+        return (rank[String(a.severity)] ?? 4) - (rank[String(b.severity)] ?? 4);
+      });
+      for (const r of openUserReports.slice(0, Math.max(0, 4 - steps.length))) {
+        steps.push({
+          priority: priority++,
+          action: `Triage [${r.severity}] ${label(r)}`,
+          reason: "User-felt report awaiting triage \u2014 review the packet, then dispatch or dismiss.",
+          tool: "triage_issue",
+          args: { report_id: r.id }
+        });
+      }
+      const chores = reports.filter((r) => r.status === "classified" && isCron(r) && !isBlocked(r));
+      if (chores.length > 0 && steps.length < 5) {
+        steps.push({
+          priority: priority++,
+          action: `Batch ${chores.length} maintenance chore${chores.length === 1 ? "" : "s"} (dependency bumps)`,
+          reason: "Robot-filed modernization reports \u2014 batch-dispatch or dismiss in one sitting; do not let them crowd out user bugs.",
+          tool: "get_recent_reports",
+          args: { status: "classified" }
+        });
+      }
+      const summary = steps.length === 0 ? "Inbox is clear \u2014 no blocked fixes, no open user reports, no chores. Nothing needs your attention." : `${steps.length} prioritised step${steps.length === 1 ? "" : "s"}: ` + steps.map((s) => s.action).join(" \u2192 ");
+      return jsonResult({ steps, summary });
+    }
+  );
   server.registerTool(
     "dispatch_fix",
     {
@@ -1264,7 +1554,7 @@ function createMushiServer(config) {
         } catch {
         }
       }
-      const data = await apiCall("/v1/admin/fixes/dispatch", {
+      const dispatch = await apiCall("/v1/admin/fixes/dispatch", {
         method: "POST",
         headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
         body: JSON.stringify({
@@ -1274,7 +1564,12 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonResult(data);
+      if (!dispatch?.dispatchId) {
+        throw new Error(
+          `Dispatch response missing dispatchId \u2014 got: ${JSON.stringify(dispatch).slice(0, 300)}`
+        );
+      }
+      return jsonResult({ fixId: dispatch.dispatchId, status: dispatch.status ?? "queued" });
     }
   );
   server.registerTool(
@@ -1409,6 +1704,11 @@ function createMushiServer(config) {
         status: z.enum([
           "pending",
           "classified",
+          // Workflow states added 20260520600000 but missing from this
+          // enum ever since (2026-08-16 audit P2-2) — agents could not
+          // mark a report as being looked at.
+          "triaged",
+          "in_progress",
           "grouped",
           "fixing",
           "fixed",
@@ -1416,7 +1716,7 @@ function createMushiServer(config) {
           "verified",
           "reopened",
           "dismissed"
-        ]).describe("Target status"),
+        ]).describe("Target status (resolved is stored as fixed)"),
         reason: z.string().optional().describe("Reason for the transition (audit trail)")
       }
     },
@@ -2632,5 +2932,6 @@ Be specific. No generic advice.`
 }
 export {
   MushiApiError,
-  createMushiServer
+  createMushiServer,
+  resolveTimeoutMsFromEnv
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
   "mcpName": "io.github.kensaurus/mushi-mushi",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "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",
@@ -48,7 +48,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sentry/node": "^10.57.0",
     "zod": "^4.4.3",
-    "@mushi-mushi/core": "^1.27.0"
+    "@mushi-mushi/core": "^1.27.2"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",