@mushi-mushi/mcp 0.20.1 → 0.21.0

package/dist/server.js

@@ -3,17 +3,17 @@ import {
   TDD_TOOL_CATALOG,
   TOOL_CATALOG,
   USE_MUSHI_INTENTS
-} from "./chunk-TP2QQWDJ.js";
+} from "./chunk-FNDGCFSJ.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EANW5YTI.js";
 import {
   DEPRECATED_TOOL_ALIASES,
   toolMatchesFeatures
-} from "./chunk-ZSVRLSW5.js";
+} from "./chunk-XSL2FPLV.js";
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { createLogger } from "@mushi-mushi/core";
 
@@ -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
-var NO_ARG_INPUT = {};
+installStdoutGuard();
+var NO_ARG_INPUT = z.object({});
+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)})`
       );
     }
   }
@@ -322,7 +485,7 @@ function createMushiServer(config) {
       title: titleOf("get_recent_reports"),
       description: descOf("get_recent_reports"),
       annotations: annotationsFor("get_recent_reports"),
-      inputSchema: {
+      inputSchema: z.object({
         status: z.string().optional().describe("Filter by status: new, classified, grouped, fixing, fixed, dismissed"),
         category: z.string().optional().describe("Filter by category: bug, slow, visual, confusing, other"),
         severity: z.string().optional().describe("Filter by severity: critical, high, medium, low"),
@@ -330,11 +493,11 @@ function createMushiServer(config) {
         project_id: z.string().optional().describe(
           "Project UUID \u2014 defaults to the server-configured project. Useful when you have multiple projects and want to query a specific one by its ID. Get IDs by calling list_projects or get_account_overview first."
         )
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         reports: z.array(z.unknown()),
         total: z.number()
-      }
+      })
     },
     async (args) => {
       const params = new URLSearchParams();
@@ -359,11 +522,11 @@ function createMushiServer(config) {
       title: titleOf("get_report_detail"),
       description: descOf("get_report_detail"),
       annotations: annotationsFor("get_report_detail"),
-      inputSchema: {
+      inputSchema: z.object({
         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() }
+      }),
+      outputSchema: z.object({ report: z.unknown() })
     },
     async (args) => {
       const { headers } = await projectScopeHeaders(args.project_id);
@@ -386,7 +549,7 @@ function createMushiServer(config) {
       title: titleOf("get_report_timeline"),
       description: descOf("get_report_timeline"),
       annotations: annotationsFor("get_report_timeline"),
-      inputSchema: { reportId: z.string().describe("The report UUID") }
+      inputSchema: z.object({ reportId: z.string().describe("The report UUID") })
     },
     async (args) => jsonText(await apiCall(`/v1/sync/reports/${args.reportId}/timeline`))
   );
@@ -406,14 +569,14 @@ function createMushiServer(config) {
       title: titleOf("search_reports"),
       description: descOf("search_reports"),
       annotations: annotationsFor("search_reports"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().describe("Natural-language search text or component path"),
         limit: z.number().optional().describe("Max results (default 10, max 50)"),
         threshold: z.number().optional().describe("Similarity threshold 0..1, default 0.2")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         results: z.array(z.unknown())
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/reports/similarity", {
@@ -434,13 +597,13 @@ function createMushiServer(config) {
       title: titleOf("get_similar_bugs"),
       description: descOf("get_similar_bugs"),
       annotations: annotationsFor("get_similar_bugs"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().describe("Component name, page path, or bug description"),
         limit: z.number().optional().describe("Max results (default 5, max 20)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         results: z.array(z.unknown())
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/reports/similarity", {
@@ -461,18 +624,18 @@ function createMushiServer(config) {
       title: titleOf("get_fix_context"),
       description: descOf("get_fix_context"),
       annotations: annotationsFor("get_fix_context"),
-      inputSchema: {
+      inputSchema: z.object({
         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: {
+      }),
+      outputSchema: z.object({
         report: z.unknown(),
         fixPrompt: z.unknown(),
         reproductionSteps: z.unknown(),
         component: z.unknown(),
         rootCause: z.unknown(),
         bugOntologyTags: z.unknown()
-      }
+      })
     },
     async (args) => {
       const { headers } = await projectScopeHeaders(args.project_id);
@@ -501,10 +664,10 @@ function createMushiServer(config) {
       title: titleOf("get_fix_timeline"),
       description: descOf("get_fix_timeline"),
       annotations: annotationsFor("get_fix_timeline"),
-      inputSchema: {
+      inputSchema: z.object({
         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) => {
       const { headers } = await projectScopeHeaders(args.project_id);
@@ -517,7 +680,7 @@ function createMushiServer(config) {
       title: titleOf("get_blast_radius"),
       description: descOf("get_blast_radius"),
       annotations: annotationsFor("get_blast_radius"),
-      inputSchema: { nodeId: z.string().describe("Graph node UUID") }
+      inputSchema: z.object({ nodeId: z.string().describe("Graph node UUID") })
     },
     async (args) => jsonText(await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`))
   );
@@ -527,14 +690,14 @@ function createMushiServer(config) {
       title: titleOf("get_knowledge_graph"),
       description: descOf("get_knowledge_graph"),
       annotations: annotationsFor("get_knowledge_graph"),
-      inputSchema: {
+      inputSchema: z.object({
         seed: z.string().describe("Starting graph node id or human-readable label to traverse from"),
         depth: z.number().optional().describe("BFS hops outward from seed \u2014 clamped to 4 in the handler (default 2)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
         edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
-      }
+      })
     },
     async (args) => {
       const params = new URLSearchParams({
@@ -553,16 +716,16 @@ function createMushiServer(config) {
       title: titleOf("get_graph_neighborhood"),
       description: descOf("get_graph_neighborhood"),
       annotations: annotationsFor("get_graph_neighborhood"),
-      inputSchema: {
+      inputSchema: z.object({
         seed: z.string().describe(
           "Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"
         ),
         depth: z.number().int().min(1).max(4).optional().describe("BFS hops to traverse outward. Default 2; clamped to a max of 4.")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
         edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
-      }
+      })
     },
     async (args) => {
       const params = new URLSearchParams({
@@ -581,12 +744,12 @@ function createMushiServer(config) {
       title: titleOf("get_graph_node"),
       description: descOf("get_graph_node"),
       annotations: annotationsFor("get_graph_node"),
-      inputSchema: {
+      inputSchema: z.object({
         nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/graph/node/${args.nodeId}`);
@@ -599,9 +762,9 @@ function createMushiServer(config) {
       title: titleOf("get_inventory"),
       description: descOf("get_inventory"),
       annotations: annotationsFor("get_inventory"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to the server-configured project when omitted")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -616,11 +779,11 @@ function createMushiServer(config) {
       title: titleOf("diff_inventory"),
       description: descOf("diff_inventory"),
       annotations: annotationsFor("diff_inventory"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
         fromSha: z.string().describe("Older commit SHA (the baseline to diff from)"),
         toSha: z.string().describe("Newer commit SHA (the candidate to diff to)")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -636,15 +799,15 @@ function createMushiServer(config) {
       title: titleOf("list_gate_findings"),
       description: descOf("list_gate_findings"),
       annotations: annotationsFor("list_gate_findings"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
         gate: z.string().optional().describe("Filter to one gate id: dead-handler | mock-leak | crawl | status-claim"),
         severity: z.string().optional().describe("Minimum severity to include: low | medium | high | critical")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         runs: z.array(z.unknown()).describe("Recent gate_runs rows, newest first"),
         findings: z.array(z.unknown()).describe("gate_findings rows for those runs")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -670,21 +833,35 @@ function createMushiServer(config) {
       title: titleOf("suggest_fix"),
       description: descOf("suggest_fix"),
       annotations: annotationsFor("suggest_fix"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         reportId: z.string().describe("The report this slice was read from"),
         rootCause: z.unknown().describe("Stage-2 root-cause hint, or null if not yet classified"),
         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,
@@ -701,11 +878,11 @@ function createMushiServer(config) {
       title: titleOf("run_nl_query"),
       description: descOf("run_nl_query"),
       annotations: annotationsFor("run_nl_query"),
-      inputSchema: {
+      inputSchema: z.object({
         question: z.string().describe(
           'Question in plain English, e.g. "Which components had the most critical bugs this week?"'
         )
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/query", {
@@ -721,14 +898,14 @@ function createMushiServer(config) {
       title: titleOf("diagnose_setup"),
       description: descOf("diagnose_setup"),
       annotations: annotationsFor("diagnose_setup"),
-      inputSchema: {
+      inputSchema: z.object({
         mode: z.enum(["full", "ingest", "dispatch"]).optional().describe(
           "full (default) = ingest + dispatch; ingest = SDK pipeline only; dispatch = fix preflight only."
         ),
         project_id: z.string().optional().describe("Project UUID for dispatch checks (defaults to configured project)."),
         projectId: z.string().optional().describe("Alias for project_id.")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         mode: z.string(),
         ready: z.boolean(),
         summary: z.string(),
@@ -736,7 +913,7 @@ function createMushiServer(config) {
         ingest: z.unknown().optional(),
         dispatch: z.unknown().optional(),
         connection: z.unknown().optional()
-      }
+      })
     },
     async (args) => {
       const mode = args.mode ?? "full";
@@ -875,17 +1052,71 @@ function createMushiServer(config) {
       });
     }
   );
+  server.registerTool(
+    "check_sdk_version",
+    {
+      title: titleOf("check_sdk_version"),
+      description: descOf("check_sdk_version"),
+      annotations: annotationsFor("check_sdk_version"),
+      inputSchema: z.object({
+        package: z.string().optional().describe(
+          "npm package name (default @mushi-mushi/web). Examples: @mushi-mushi/web, @mushi-mushi/node, @mushi-mushi/core."
+        ),
+        current: z.string().optional().describe("Installed version from package.json, if known (e.g. 1.27.0).")
+      }),
+      outputSchema: z.object({
+        package: z.string(),
+        latest: z.string().optional(),
+        current: z.string().optional(),
+        outdated: z.boolean().optional(),
+        suggestedActions: z.array(
+          z.object({
+            type: z.literal("tool_call"),
+            toolName: z.string(),
+            arguments: z.record(z.string(), z.unknown()),
+            reason: z.string()
+          })
+        ).optional()
+      })
+    },
+    async (args) => {
+      const pkg = args.package?.trim() || "@mushi-mushi/web";
+      const query = new URLSearchParams({ package: pkg }).toString();
+      const data = await apiCall(
+        `/v1/sdk/latest-version?${query}`
+      );
+      const latest = data.latest ?? data.version;
+      const current = args.current;
+      const outdated = current && latest ? current !== latest : void 0;
+      return jsonResult({
+        package: data.package ?? pkg,
+        latest,
+        current,
+        outdated,
+        ...outdated ? {
+          suggestedActions: [
+            {
+              type: "tool_call",
+              toolName: "search_mushi_docs",
+              arguments: { query: `${pkg} upgrade mushi-sdk-upgrade` },
+              reason: "Read current upgrade notes, then apply the mushi-sdk-upgrade skill. This tool does not bump the pin."
+            }
+          ]
+        } : {}
+      });
+    }
+  );
   server.registerTool(
     "search_mushi_docs",
     {
       title: titleOf("search_mushi_docs"),
       description: descOf("search_mushi_docs"),
       annotations: annotationsFor("search_mushi_docs"),
-      inputSchema: {
+      inputSchema: z.object({
         query: z.string().describe("Keywords to search official Mushi docs (guides, MCP, inventory, QA)."),
         limit: z.number().int().min(1).max(20).optional().describe("Max results (default 8).")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         query: z.string(),
         results: z.array(
           z.object({
@@ -895,7 +1126,7 @@ function createMushiServer(config) {
             score: z.number()
           })
         )
-      }
+      })
     },
     async (args) => {
       const query = args.query ?? "";
@@ -916,11 +1147,11 @@ function createMushiServer(config) {
       description: descOf("list_projects"),
       annotations: annotationsFor("list_projects"),
       inputSchema: NO_ARG_INPUT,
-      outputSchema: {
+      outputSchema: z.object({
         projects: z.array(z.unknown()),
         total: z.number().optional(),
         _multi_project_hint: z.string().optional()
-      }
+      })
     },
     async () => {
       const data = await apiCall("/v1/admin/mcp/projects");
@@ -937,7 +1168,7 @@ function createMushiServer(config) {
       description: descOf("get_account_overview"),
       annotations: annotationsFor("get_account_overview"),
       inputSchema: NO_ARG_INPUT,
-      outputSchema: {
+      outputSchema: z.object({
         projects: z.array(z.unknown()),
         total: z.number(),
         active_project_id: z.string().nullable(),
@@ -945,7 +1176,7 @@ function createMushiServer(config) {
         resourceCount: z.number().optional(),
         promptCount: z.number().optional(),
         multi_project_hint: z.string()
-      }
+      })
     },
     async () => {
       const data = await apiCall("/v1/admin/mcp/account-overview");
@@ -967,9 +1198,9 @@ function createMushiServer(config) {
       title: titleOf("get_project_context"),
       description: descOf("get_project_context"),
       annotations: annotationsFor("get_project_context"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -991,13 +1222,13 @@ function createMushiServer(config) {
       title: titleOf("get_pipeline_logs"),
       description: descOf("get_pipeline_logs"),
       annotations: annotationsFor("get_pipeline_logs"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
         service: z.enum(["fix-worker", "qa-story-runner", "pipeline", "all"]).optional().describe("Pipeline service to filter (default: all)."),
         since: z.string().optional().describe("ISO-8601 timestamp \u2014 return only entries after this time."),
         limit: z.number().optional().describe("Max entries to return (default 50, max 200)."),
         level: z.enum(["info", "warn", "error", "fatal"]).optional().describe("Minimum severity level (default: warn).")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -1017,9 +1248,9 @@ function createMushiServer(config) {
       title: titleOf("get_report_evidence"),
       description: descOf("get_report_evidence"),
       annotations: annotationsFor("get_report_evidence"),
-      inputSchema: {
+      inputSchema: z.object({
         report_id: z.string().describe("Report UUID.")
-      }
+      })
     },
     async (args) => {
       const [reportRes, timelineRes] = await Promise.allSettled([
@@ -1067,12 +1298,12 @@ function createMushiServer(config) {
       title: titleOf("triage_issue"),
       description: descOf("triage_issue"),
       annotations: annotationsFor("triage_issue"),
-      inputSchema: {
+      inputSchema: z.object({
         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).")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         report_id: z.string(),
         severity: z.unknown(),
         category: z.unknown(),
@@ -1085,7 +1316,7 @@ function createMushiServer(config) {
         recent_logs: z.unknown().nullable(),
         recommended_actions: z.array(z.unknown()),
         triage_summary: z.string()
-      }
+      })
     },
     async (args) => {
       const { projectId: pid, headers } = await projectScopeHeaders(args.project_id);
@@ -1115,12 +1346,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({
@@ -1190,7 +1440,7 @@ function createMushiServer(config) {
       title: titleOf("submit_fix_result"),
       description: descOf("submit_fix_result"),
       annotations: annotationsFor("submit_fix_result"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to attach this external fix attempt to"),
         branch: z.string().describe("Git branch name where the fix was implemented"),
         prUrl: z.string().optional().describe("GitHub pull request URL, if a PR was opened"),
@@ -1198,43 +1448,136 @@ 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: {
+      }),
+      outputSchema: z.object({
         ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
         fixId: z.string().describe("UUID of the new fix_attempt row")
-      }
+      })
     },
     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: z.object({
+        project_id: z.string().uuid().optional().describe("Project UUID (defaults to the configured project).")
+      }),
+      outputSchema: z.object({
+        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",
     {
       title: titleOf("dispatch_fix"),
       description: descOf("dispatch_fix"),
       annotations: annotationsFor("dispatch_fix"),
-      inputSchema: {
+      inputSchema: z.object({
         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(
@@ -1243,19 +1586,19 @@ function createMushiServer(config) {
         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."
         )
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         fixId: z.string(),
         status: z.string()
-      }
+      })
     },
-    async (args, extra) => {
-      if (extra?.sendNotification && extra?._meta?.progressToken) {
+    async (args, ctx) => {
+      if (ctx?.mcpReq.notify && ctx?.mcpReq._meta?.progressToken) {
         try {
-          await extra.sendNotification({
+          await ctx.mcpReq.notify({
             method: "notifications/progress",
             params: {
-              progressToken: extra._meta.progressToken,
+              progressToken: ctx.mcpReq._meta.progressToken,
               progress: 0,
               total: 100,
               message: "Dispatching Mushi fix orchestrator\u2026"
@@ -1264,7 +1607,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 +1617,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(
@@ -1283,13 +1631,13 @@ function createMushiServer(config) {
       title: titleOf("trigger_judge"),
       description: descOf("trigger_judge"),
       annotations: annotationsFor("trigger_judge"),
-      inputSchema: {
+      inputSchema: z.object({
         limit: z.number().optional().describe("Max reports to judge in this batch (default 25, max 100)"),
         projectId: z.string().optional().describe("Restrict to one project when the API key owns multiple")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         dispatched: z.number().describe("Number of judge-batch jobs dispatched (one per accessible project)")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall("/v1/admin/judge/run", {
@@ -1308,10 +1656,10 @@ function createMushiServer(config) {
       title: titleOf("test_gen_from_report"),
       description: descOf("test_gen_from_report"),
       annotations: annotationsFor("test_gen_from_report"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to turn into a Playwright PR"),
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -1337,16 +1685,16 @@ function createMushiServer(config) {
       title: titleOf("merge_fix"),
       description: descOf("merge_fix"),
       annotations: annotationsFor("merge_fix"),
-      inputSchema: {
+      inputSchema: z.object({
         fixId: z.string().describe("Fix attempt UUID whose GitHub PR should be squash-merged"),
         mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method (default squash)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         merged: z.boolean().optional().describe("True when GitHub accepted the merge in this call"),
         alreadyMerged: z.boolean().optional().describe("True when the PR was already merged (idempotent no-op)"),
         reportId: z.string().describe("Report UUID linked to this fix attempt"),
         reportStatus: z.string().describe("Report workflow status after merge bookkeeping")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/merge`, {
@@ -1362,14 +1710,14 @@ function createMushiServer(config) {
       title: titleOf("refresh_ci"),
       description: descOf("refresh_ci"),
       annotations: annotationsFor("refresh_ci"),
-      inputSchema: {
+      inputSchema: z.object({
         fixId: z.string().describe("Fix attempt UUID whose PR check-runs should be re-polled")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         check_run_status: z.string().nullable().describe("GitHub check run status after refresh"),
         check_run_conclusion: z.string().nullable().describe("success | failure | neutral | null while pending"),
         check_run_updated_at: z.string().nullable().describe("ISO timestamp when CI status was last persisted")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
@@ -1382,13 +1730,13 @@ function createMushiServer(config) {
       title: titleOf("reopen_report"),
       description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID to move back to reopened status"),
         note: z.string().optional().describe("Operator note recorded on the reopen transition")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         report: z.unknown().describe("Updated report row with status=reopened")
-      }
+      })
     },
     async (args) => {
       const report = await apiCall(`/v1/sync/reports/${args.reportId}`, {
@@ -1404,11 +1752,16 @@ function createMushiServer(config) {
       title: titleOf("transition_status"),
       description: descOf("transition_status"),
       annotations: annotationsFor("transition_status"),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report UUID"),
         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,9 +1769,9 @@ 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)")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/reports/${args.reportId}`, {
@@ -1434,9 +1787,9 @@ function createMushiServer(config) {
       title: titleOf("setup_repo_for_mushi"),
       description: descOf("setup_repo_for_mushi"),
       annotations: annotationsFor("setup_repo_for_mushi"),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
-      }
+      })
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
@@ -1459,12 +1812,12 @@ function createMushiServer(config) {
       title: titleOf("query_lessons"),
       description: descOf("query_lessons"),
       annotations: annotationsFor("query_lessons"),
-      inputSchema: {
+      inputSchema: z.object({
         diff_text: z.string().describe("The PR diff, code snippet, or description of the change being made."),
         max_tokens: z.number().optional().describe("Maximum tokens for returned lessons context (default 3000, max 8000)."),
         top_k: z.number().optional().describe("Max number of lessons to return (default 15, max 50)."),
         project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -1486,14 +1839,14 @@ function createMushiServer(config) {
       title: titleOf("list_lessons"),
       description: descOf("list_lessons"),
       annotations: annotationsFor("list_lessons"),
-      inputSchema: {
+      inputSchema: z.object({
         severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter to one severity level"),
         limit: z.number().optional().describe("Max lessons to return (default 50, max 200)"),
         project_id: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         lessons: z.array(z.unknown()).describe("Promoted lesson rows ordered by frequency")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -1505,7 +1858,7 @@ function createMushiServer(config) {
       return wrappedJsonResult({ lessons }, "lesson text");
     }
   );
-  server.resource(
+  server.registerResource(
     "project_stats",
     "project://stats",
     { description: "Report counts, category breakdown, severity distribution" },
@@ -1519,7 +1872,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "project_settings",
     "project://settings",
     {
@@ -1535,7 +1888,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "project_dashboard",
     "project://dashboard",
     {
@@ -1557,10 +1910,10 @@ function createMushiServer(config) {
       title: titleOf("list_top_contributors"),
       description: descOf("list_top_contributors"),
       annotations: annotationsFor("list_top_contributors"),
-      inputSchema: {
+      inputSchema: z.object({
         limit: z.number().int().min(1).max(100).optional().default(10).describe("Max rows to return (default 10, max 100)"),
         range: z.enum(["30d", "90d", "all"]).optional().default("30d").describe("Time window for points calculation")
-      }
+      })
     },
     async ({ limit, range }) => ({
       content: [
@@ -1581,11 +1934,11 @@ function createMushiServer(config) {
       title: titleOf("award_bonus_points"),
       description: descOf("award_bonus_points"),
       annotations: annotationsFor("award_bonus_points"),
-      inputSchema: {
+      inputSchema: z.object({
         external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
         points: z.number().int().min(1).max(5e4).describe("Bonus points to award (max 50,000 per call)"),
         reason: z.string().max(200).describe("Human-readable reason, logged to end_user_activity")
-      }
+      })
     },
     async ({ external_user_id, points, reason }) => ({
       content: [
@@ -1610,11 +1963,11 @@ function createMushiServer(config) {
       title: titleOf("set_tier"),
       description: descOf("set_tier"),
       annotations: annotationsFor("set_tier"),
-      inputSchema: {
+      inputSchema: z.object({
         external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
         tier_slug: z.string().describe('Tier slug to assign, e.g. "champion", "contributor", "explorer"'),
         reason: z.string().max(200).optional().describe("Optional reason for manual override")
-      }
+      })
     },
     async ({ external_user_id, tier_slug, reason }) => ({
       content: [
@@ -1633,7 +1986,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "privacy_status",
     "privacy://status",
     {
@@ -1649,7 +2002,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "evolution_history",
     "evolution://history",
     {
@@ -1671,7 +2024,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "project_integration_health",
     "project://integration-health",
     {
@@ -1687,7 +2040,7 @@ function createMushiServer(config) {
       ]
     })
   );
-  server.resource(
+  server.registerResource(
     "inventory_current",
     "inventory://current",
     {
@@ -1712,9 +2065,9 @@ function createMushiServer(config) {
       title: titleOf("activation_status"),
       description: descOf("activation_status"),
       annotations: annotationsFor("activation_status"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to the configured project).")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -1722,7 +2075,7 @@ function createMushiServer(config) {
       return jsonResult(await apiCall(`/v1/admin/activation${qs}`));
     }
   );
-  server.resource(
+  server.registerResource(
     "activation_status",
     "mushi://activation",
     {
@@ -1741,10 +2094,12 @@ function createMushiServer(config) {
       };
     }
   );
-  server.prompt(
+  server.registerPrompt(
     "summarize_report_for_fix",
-    "Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. Use before asking an agent to write the patch.",
-    { reportId: z.string().describe("The report UUID to summarize") },
+    {
+      description: "Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. Use before asking an agent to write the patch.",
+      argsSchema: z.object({ reportId: z.string().describe("The report UUID to summarize") })
+    },
     ({ reportId }) => ({
       messages: [
         {
@@ -1769,10 +2124,12 @@ Lead with the fix. Skip the preamble.`
       ]
     })
   );
-  server.prompt(
+  server.registerPrompt(
     "explain_judge_result",
-    "Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. Use after a fix attempt has been judged.",
-    { fixId: z.string().describe("The fix_attempt UUID to explain") },
+    {
+      description: "Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. Use after a fix attempt has been judged.",
+      argsSchema: z.object({ fixId: z.string().describe("The fix_attempt UUID to explain") })
+    },
     ({ fixId }) => ({
       messages: [
         {
@@ -1793,10 +2150,12 @@ No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
       ]
     })
   );
-  server.prompt(
+  server.registerPrompt(
     "triage_next_steps",
-    'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
-    {},
+    {
+      description: 'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
+      argsSchema: z.object({})
+    },
     () => ({
       messages: [
         {
@@ -1816,10 +2175,12 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
       ]
     })
   );
-  server.prompt(
+  server.registerPrompt(
     "mushi_setup",
-    "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
-    {},
+    {
+      description: "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
+      argsSchema: z.object({})
+    },
     () => ({
       messages: [
         {
@@ -1849,13 +2210,13 @@ Be specific. No generic advice.`
       title: titleOf("map_user_stories", TDD_TOOL_CATALOG),
       description: descOf("map_user_stories", TDD_TOOL_CATALOG),
       annotations: annotationsFor("map_user_stories", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id to map stories for"),
         baseUrl: z.string().url().describe("Live app URL to crawl"),
         maxPages: z.number().int().min(1).max(50).optional().describe("Max pages to crawl (default 20)"),
         provider: z.enum(["firecrawl", "browserbase"]).optional().describe("Crawl provider (default: firecrawl)"),
         cursorCloudRefine: z.boolean().optional().describe("Dispatch Cursor Cloud agent to refine and open a PR")
-      }
+      })
     },
     async ({ projectId: projectId2, baseUrl, maxPages, provider, cursorCloudRefine }) => {
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
@@ -1880,9 +2241,9 @@ Be specific. No generic advice.`
       title: titleOf("get_map_run_status", TDD_TOOL_CATALOG),
       description: descOf("get_map_run_status", TDD_TOOL_CATALOG),
       annotations: annotationsFor("get_map_run_status", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall(`/v1/admin/inventory/${projectId2}/map-runs`);
@@ -1895,7 +2256,7 @@ Be specific. No generic advice.`
       title: titleOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project UUID that owns the inventory story"),
         storyNodeId: z.string().describe(
           "User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"
@@ -1903,13 +2264,13 @@ Be specific. No generic advice.`
         automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Approval gate for the generated qa_story (default review \u2192 pending_review)"),
         baseUrl: z.string().url().optional().describe("Override the live app URL the Playwright test should target"),
         openPr: z.boolean().optional().describe("Open a draft GitHub PR with the generated spec (default true)")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         qaStoryId: z.string().describe("UUID of the inserted qa_stories row"),
         prUrl: z.string().nullable().describe("GitHub PR URL when openPr=true and GitHub is connected"),
         approvalStatus: z.string().describe("pending_review | approved \u2014 follows automationMode and project defaults"),
         needsHumanReview: z.boolean().describe("True when the story requires operator approval before scheduled runs")
-      }
+      })
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
       if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
@@ -1930,9 +2291,9 @@ Be specific. No generic advice.`
       title: titleOf("improve_qa_story", TDD_TOOL_CATALOG),
       description: descOf("improve_qa_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("improve_qa_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().optional().describe("Project id (omit to run across all projects)")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall("/v1/admin/pdca/improve-qa-stories", {
@@ -1948,10 +2309,10 @@ Be specific. No generic advice.`
       title: titleOf("run_qa_story", TDD_TOOL_CATALOG),
       description: descOf("run_qa_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("run_qa_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         qaStoryId: z.string().describe("qa_story id to run")
-      }
+      })
     },
     async ({ projectId: projectId2, qaStoryId }) => {
       const data = await apiCall(
@@ -1967,9 +2328,9 @@ Be specific. No generic advice.`
       title: titleOf("list_byok_keys", TDD_TOOL_CATALOG),
       description: descOf("list_byok_keys", TDD_TOOL_CATALOG),
       annotations: annotationsFor("list_byok_keys", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall(
@@ -1984,14 +2345,14 @@ Be specific. No generic advice.`
       title: titleOf("add_byok_key", TDD_TOOL_CATALOG),
       description: descOf("add_byok_key", TDD_TOOL_CATALOG),
       annotations: annotationsFor("add_byok_key", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor"]).describe("Provider slug"),
         key: z.string().min(8).max(4096).describe("The API key value to add"),
         label: z.string().optional().describe("Human-readable label for this key"),
         priority: z.number().int().min(0).max(1e4).optional().describe("Priority for ordering (lower = higher priority)"),
         baseUrl: z.string().url().max(2048).optional().describe("Allow-listed OpenAI-compatible HTTPS base URL")
-      }
+      })
     },
     async ({ projectId: projectId2, provider, key, label, priority, baseUrl }) => {
       const data = await apiCall("/v1/admin/byok/keys", {
@@ -2014,10 +2375,10 @@ Be specific. No generic advice.`
       title: titleOf("test_byok_key", TDD_TOOL_CATALOG),
       description: descOf("test_byok_key", TDD_TOOL_CATALOG),
       annotations: annotationsFor("test_byok_key", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         keyId: z.string().uuid().describe("Pooled BYOK key id")
-      }
+      })
     },
     async ({ keyId }) => {
       const data = await apiCall(`/v1/admin/byok/keys/${encodeURIComponent(keyId)}/test`, {
@@ -2032,10 +2393,10 @@ Be specific. No generic advice.`
       title: titleOf("remove_byok_key", TDD_TOOL_CATALOG),
       description: descOf("remove_byok_key", TDD_TOOL_CATALOG),
       annotations: annotationsFor("remove_byok_key", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         keyId: z.string().uuid().describe("Pooled BYOK key UUID from list_byok_keys")
-      }
+      })
     },
     async ({ keyId }) => {
       const data = await apiCall(`/v1/admin/byok/keys/${encodeURIComponent(keyId)}`, {
@@ -2050,9 +2411,9 @@ Be specific. No generic advice.`
       title: titleOf("list_pending_review_stories", TDD_TOOL_CATALOG),
       description: descOf("list_pending_review_stories", TDD_TOOL_CATALOG),
       annotations: annotationsFor("list_pending_review_stories", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id")
-      }
+      })
     },
     async ({ projectId: projectId2 }) => {
       const data = await apiCall(
@@ -2067,11 +2428,11 @@ Be specific. No generic advice.`
       title: titleOf("approve_qa_story", TDD_TOOL_CATALOG),
       description: descOf("approve_qa_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("approve_qa_story", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         projectId: z.string().describe("Project id"),
         qaStoryId: z.string().describe("QA story id to approve or reject"),
         status: z.enum(["approved", "rejected"]).describe("New approval status")
-      }
+      })
     },
     async ({ projectId: projectId2, qaStoryId, status }) => {
       const data = await apiCall(
@@ -2087,11 +2448,11 @@ Be specific. No generic advice.`
       title: titleOf("reply_to_reporter", TDD_TOOL_CATALOG),
       description: descOf("reply_to_reporter", TDD_TOOL_CATALOG),
       annotations: annotationsFor("reply_to_reporter", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         reportId: z.string().describe("Report id to reply to"),
         message: z.string().min(1).max(1e4).describe("Message text to send to the reporter"),
         authorName: z.string().optional().describe('Display name for the admin sender (default: "Mushi Admin")')
-      }
+      })
     },
     async ({ reportId, message, authorName }) => {
       const data = await apiCall(`/v1/sync/reports/${reportId}/reply`, {
@@ -2107,10 +2468,10 @@ Be specific. No generic advice.`
       title: titleOf("list_qa_story_runs", TDD_TOOL_CATALOG),
       description: descOf("list_qa_story_runs", TDD_TOOL_CATALOG),
       annotations: annotationsFor("list_qa_story_runs", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         storyId: z.string().describe("QA story id (uuid)"),
         limit: z.number().int().min(1).max(50).optional().default(10).describe("Max runs to return (default 10)")
-      }
+      })
     },
     async ({ storyId, limit }) => {
       const data = await apiCall(
@@ -2125,10 +2486,10 @@ Be specific. No generic advice.`
       title: titleOf("get_qa_story_run", TDD_TOOL_CATALOG),
       description: descOf("get_qa_story_run", TDD_TOOL_CATALOG),
       annotations: annotationsFor("get_qa_story_run", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         storyId: z.string().describe("QA story id (uuid)"),
         runId: z.string().describe("Run id (uuid) to fetch detail for")
-      }
+      })
     },
     async ({ storyId, runId }) => {
       const data = await apiCall(
@@ -2151,9 +2512,9 @@ Be specific. No generic advice.`
       title: titleOf("test_notification_channel", TDD_TOOL_CATALOG),
       description: descOf("test_notification_channel", TDD_TOOL_CATALOG),
       annotations: annotationsFor("test_notification_channel", TDD_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         kind: z.enum(["slack", "discord"]).describe("Notification channel kind to test")
-      }
+      })
     },
     async ({ kind }) => {
       const data = await apiCall(
@@ -2169,9 +2530,9 @@ Be specific. No generic advice.`
       title: titleOf("run_fullstack_audit"),
       description: descOf("run_fullstack_audit"),
       annotations: annotationsFor("run_fullstack_audit"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project ID to audit. Defaults to the configured project.")
-      }
+      })
     },
     async ({ project_id }) => {
       const pid = project_id ?? config.projectId;
@@ -2189,10 +2550,10 @@ Be specific. No generic advice.`
       title: titleOf("get_backend_health"),
       description: descOf("get_backend_health"),
       annotations: annotationsFor("get_backend_health"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project ID. Defaults to the configured project."),
         include_logs: z.boolean().optional().describe("Whether to include recent backend error logs (default: true).")
-      }
+      })
     },
     async ({ project_id, include_logs = true }) => {
       const pid = project_id ?? config.projectId;
@@ -2216,9 +2577,9 @@ Be specific. No generic advice.`
       title: titleOf("get_usage"),
       description: descOf("get_usage"),
       annotations: annotationsFor("get_usage"),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project ID. Defaults to the configured project.")
-      }
+      })
     },
     async ({ project_id }) => {
       const pid = project_id ?? config.projectId;
@@ -2233,12 +2594,12 @@ Be specific. No generic advice.`
       title: titleOf("list_skills"),
       description: descOf("list_skills"),
       annotations: annotationsFor("list_skills"),
-      inputSchema: {
+      inputSchema: z.object({
         category: z.string().optional().describe("Filter by category: workflow, debug, test, audit, enhance, \u2026"),
         search: z.string().optional().describe("Free-text search across slug, title, description"),
         page: z.number().optional().describe("Page number (default 1)"),
         limit: z.number().optional().describe("Max results per page (default 200, max 200)")
-      }
+      })
     },
     async (args) => {
       const qs = new URLSearchParams();
@@ -2257,9 +2618,9 @@ Be specific. No generic advice.`
       title: titleOf("get_skill"),
       description: descOf("get_skill"),
       annotations: annotationsFor("get_skill"),
-      inputSchema: {
+      inputSchema: z.object({
         slug: z.string().describe('Skill slug, e.g. "workflow-fix-and-ship"')
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/skills/${args.slug}`);
@@ -2272,14 +2633,14 @@ Be specific. No generic advice.`
       title: titleOf("start_skill_pipeline"),
       description: descOf("start_skill_pipeline"),
       annotations: annotationsFor("start_skill_pipeline"),
-      inputSchema: {
+      inputSchema: z.object({
         root_skill_slug: z.string().describe('Root skill slug to run, e.g. "workflow-fix-and-ship"'),
         report_id: z.string().optional().describe("Report UUID to attach the pipeline to"),
         mode: z.enum(["handoff", "cloud"]).optional().describe(
           "handoff (default): get context packet for local agent. cloud: auto-dispatch via Cursor Cloud."
         ),
         project_id: z.string().optional().describe("Project UUID. Falls back to the configured project.")
-      }
+      })
     },
     async (args) => {
       const resolvedProjectId = args.project_id ?? projectId;
@@ -2297,9 +2658,9 @@ Be specific. No generic advice.`
       title: titleOf("get_pipeline_run"),
       description: descOf("get_pipeline_run"),
       annotations: annotationsFor("get_pipeline_run"),
-      inputSchema: {
+      inputSchema: z.object({
         run_id: z.string().describe("Pipeline run UUID")
-      }
+      })
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/skills/pipelines/${args.run_id}`);
@@ -2312,14 +2673,14 @@ Be specific. No generic advice.`
       title: titleOf("checkin_pipeline_step"),
       description: descOf("checkin_pipeline_step"),
       annotations: annotationsFor("checkin_pipeline_step"),
-      inputSchema: {
+      inputSchema: z.object({
         run_id: z.string().describe("Pipeline run UUID"),
         step_index: z.number().describe("Step index (0-based)"),
         status: z.enum(["running", "passed", "failed", "skipped"]).describe("Step status"),
         notes: z.string().optional().describe("Optional notes or output summary"),
         pr_url: z.string().optional().describe("PR URL opened during this step"),
         agent_ref: z.string().optional().describe("Cursor agentId or external agent reference")
-      }
+      })
     },
     async (args) => {
       const { run_id, step_index, ...body } = args;
@@ -2336,13 +2697,13 @@ Be specific. No generic advice.`
       title: titleOf("ask_codebase", CODEBASE_TOOL_CATALOG),
       description: descOf("ask_codebase", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("ask_codebase", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         question: z.string().describe("Plain-English question about the repo"),
         thread_id: z.string().optional().describe("Optional thread UUID to continue a conversation"),
         file_path: z.string().optional().describe("Optional file path focus"),
         symbol_name: z.string().optional().describe("Optional symbol name focus")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2370,12 +2731,12 @@ Be specific. No generic advice.`
       title: titleOf("get_file_summary", CODEBASE_TOOL_CATALOG),
       description: descOf("get_file_summary", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("get_file_summary", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         file_path: z.string().describe("Indexed file path"),
         symbol_name: z.string().optional().describe("Optional symbol name within the file"),
         force: z.boolean().optional().describe("Bypass cache and regenerate")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2393,10 +2754,10 @@ Be specific. No generic advice.`
       title: titleOf("get_codebase_tour", CODEBASE_TOOL_CATALOG),
       description: descOf("get_codebase_tour", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("get_codebase_tour", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         force: z.boolean().optional().describe("Bypass cache and regenerate")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2412,17 +2773,17 @@ Be specific. No generic advice.`
       title: titleOf("search_codebase", CODEBASE_TOOL_CATALOG),
       description: descOf("search_codebase", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("search_codebase", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         query: z.string().describe("Plain-English search query against indexed source files"),
         k: z.number().int().min(1).max(20).optional().describe("Max hits to return (default 8, max 20)"),
         scope_prefix: z.string().optional().describe("Optional repo subdirectory prefix to limit search scope")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         results: z.array(z.unknown()).describe("Ranked file/symbol hits with paths, line ranges, and similarity"),
         query: z.string().describe("Normalized query string that was searched"),
         mode: z.string().optional().describe("semantic (embeddings) or name (path/symbol match)")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2447,11 +2808,11 @@ Be specific. No generic advice.`
       title: titleOf("get_codebase_domains", CODEBASE_TOOL_CATALOG),
       description: descOf("get_codebase_domains", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("get_codebase_domains", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         force: z.boolean().optional().describe("Bypass cache and regenerate"),
         scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2470,20 +2831,20 @@ Be specific. No generic advice.`
       title: titleOf("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       description: descOf("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
         paths: z.array(z.string()).optional().describe("Changed repo-relative file paths to analyze"),
         source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths instead of manual paths"),
         compare: z.string().optional().describe("GitHub compare range base...head when source=compare"),
         fix_id: z.string().optional().describe("Fix attempt UUID \u2014 uses that PR's changed files when source=fix")
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         changed_paths: z.array(z.string()).describe("Resolved set of changed paths analyzed"),
         source: z.string().describe("How changed_paths were resolved (manual, last_push, compare, fix, \u2026)"),
         affected_file_paths: z.array(z.string()).describe("Indexed files that import or depend on changed paths"),
         affected_node_ids: z.array(z.string()).describe("Codebase graph node ids impacted by the change"),
         meta: z.unknown().nullable().optional().describe("Extra resolution metadata when auto-sourced")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2510,9 +2871,9 @@ Be specific. No generic advice.`
       title: titleOf("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
       description: descOf("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
       annotations: annotationsFor("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
-      inputSchema: {
+      inputSchema: z.object({
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)")
-      }
+      })
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
@@ -2526,11 +2887,11 @@ Be specific. No generic advice.`
     {
       title: titleOf("use_mushi"),
       description: descOf("use_mushi"),
-      inputSchema: {
+      inputSchema: z.object({
         intent: z.string().optional().describe(
           'What you are trying to accomplish with Mushi, e.g. "fix the top bug", "check project health", "run QA tests", "set up Mushi". Leave blank for a general orientation.'
         )
-      },
+      }),
       annotations: annotationsFor("use_mushi")
     },
     async (args) => {
@@ -2632,5 +2993,6 @@ Be specific. No generic advice.`
 }
 export {
   MushiApiError,
-  createMushiServer
+  createMushiServer,
+  resolveTimeoutMsFromEnv
 };