@mushi-mushi/mcp 0.17.1 → 0.18.1

package/dist/server.js

@@ -2,13 +2,14 @@ import {
   CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-7UOTJ2LI.js";
+} from "./chunk-TJSPX5CD.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EANW5YTI.js";
 import {
+  DEPRECATED_TOOL_ALIASES,
   toolMatchesFeatures
-} from "./chunk-PW4AK6SV.js";
+} from "./chunk-VBXXUK5G.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -45,8 +46,8 @@ var MUSHI_DOCS_INDEX = [
   {
     title: "Cursor MCP troubleshooting",
     path: `${BASE}/guides/mcp-setup`,
-    keywords: ["cursor", "mcp.json", "red badge", "transport error", "stdout", "stderr", "json-rpc", "INVALID_TOKEN", "syntax helper", "diagnose_connection"],
-    excerpt: "Cursor stdio MCP requires stdout to contain only JSON-RPC. Use the console syntax helper, restart Cursor MCP, then run diagnose_connection."
+    keywords: ["cursor", "mcp.json", "red badge", "transport error", "stdout", "stderr", "json-rpc", "INVALID_TOKEN", "syntax helper", "diagnose_setup"],
+    excerpt: "Cursor stdio MCP requires stdout to contain only JSON-RPC. Use the console syntax helper, restart Cursor MCP, then run diagnose_setup."
   },
   {
     title: "Judge loop",
@@ -489,8 +490,12 @@ function createMushiServer(config) {
       description: descOf("get_knowledge_graph"),
       annotations: annotationsFor("get_knowledge_graph"),
       inputSchema: {
-        seed: z.string().describe("Starting node id or label"),
-        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+        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: {
+        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) => {
@@ -498,18 +503,23 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
-    "graph_neighborhood",
+    "get_graph_neighborhood",
     {
-      title: titleOf("graph_neighborhood"),
-      description: descOf("graph_neighborhood"),
-      annotations: annotationsFor("graph_neighborhood"),
+      title: titleOf("get_graph_neighborhood"),
+      description: descOf("get_graph_neighborhood"),
+      annotations: annotationsFor("get_graph_neighborhood"),
       inputSchema: {
-        seed: z.string().describe("Starting node id or label"),
-        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+        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: {
+        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) => {
@@ -517,88 +527,108 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
-    "graph_node_status",
+    "get_graph_node",
     {
-      title: titleOf("graph_node_status"),
-      description: descOf("graph_node_status"),
-      annotations: annotationsFor("graph_node_status"),
-      inputSchema: { nodeId: z.string().describe("graph_nodes.id") }
+      title: titleOf("get_graph_node"),
+      description: descOf("get_graph_node"),
+      annotations: annotationsFor("get_graph_node"),
+      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") },
+      outputSchema: {
+        node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
+      }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
+    async (args) => {
+      const data = await apiCall(`/v1/admin/graph/node/${args.nodeId}`);
+      return jsonResult(data);
+    }
   );
   server.registerTool(
-    "inventory_get",
+    "get_inventory",
     {
-      title: titleOf("inventory_get"),
-      description: descOf("inventory_get"),
-      annotations: annotationsFor("inventory_get"),
+      title: titleOf("get_inventory"),
+      description: descOf("get_inventory"),
+      annotations: annotationsFor("get_inventory"),
       inputSchema: {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to the server-configured project when omitted")
       }
     },
     async (args) => {
       const pid = args.projectId ?? projectId;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_get");
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for get_inventory");
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
     }
   );
   server.registerTool(
-    "inventory_diff",
+    "diff_inventory",
     {
-      title: titleOf("inventory_diff"),
-      description: descOf("inventory_diff"),
-      annotations: annotationsFor("inventory_diff"),
+      title: titleOf("diff_inventory"),
+      description: descOf("diff_inventory"),
+      annotations: annotationsFor("diff_inventory"),
       inputSchema: {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
-        fromSha: z.string().describe("Older commit SHA (baseline)"),
-        toSha: z.string().describe("Newer commit SHA (candidate)")
+        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;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_diff");
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for diff_inventory");
       const q = new URLSearchParams({ from: args.fromSha, to: args.toSha });
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
     }
   );
   server.registerTool(
-    "inventory_findings",
+    "list_gate_findings",
     {
-      title: titleOf("inventory_findings"),
-      description: descOf("inventory_findings"),
-      annotations: annotationsFor("inventory_findings"),
+      title: titleOf("list_gate_findings"),
+      description: descOf("list_gate_findings"),
+      annotations: annotationsFor("list_gate_findings"),
       inputSchema: {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
-        gate: z.string().optional().describe("Filter by gate id (e.g. dead_handler, status_claim)"),
-        severity: z.string().optional().describe("Filter findings by severity")
+        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: {
+        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;
-      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_findings");
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for list_gate_findings");
       const q = new URLSearchParams();
       if (args.gate) q.set("gate", args.gate);
       if (args.severity) q.set("severity", args.severity);
       const suffix = q.toString() ? `?${q}` : "";
-      return jsonText(await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`));
+      const data = await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
-    "fix_suggest",
+    "suggest_fix",
     {
-      title: titleOf("fix_suggest"),
-      description: descOf("fix_suggest"),
-      annotations: annotationsFor("fix_suggest"),
-      inputSchema: { reportId: z.string().describe("Report UUID") }
+      title: titleOf("suggest_fix"),
+      description: descOf("suggest_fix"),
+      annotations: annotationsFor("suggest_fix"),
+      inputSchema: { reportId: z.string().describe("Report UUID to read the Stage-2 suggested-fix slice for") },
+      outputSchema: {
+        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")
+      }
     },
     async (args) => {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       const s2 = report.stage2_analysis;
-      return jsonText({
+      return jsonResult({
         reportId: args.reportId,
         rootCause: s2?.rootCause ?? null,
         suggestedFix: s2?.suggestedFix ?? null,
@@ -624,73 +654,6 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  server.registerTool(
-    "setup_check",
-    {
-      title: titleOf("setup_check"),
-      description: descOf("setup_check"),
-      annotations: annotationsFor("setup_check"),
-      inputSchema: {
-        projectId: z.string().optional().describe(
-          "Project UUID to check. Falls back to the projectId the server was initialised with."
-        )
-      }
-    },
-    async (args) => {
-      const resolvedId = args.projectId ?? projectId;
-      if (!resolvedId) {
-        return jsonText({
-          ok: false,
-          error: "No projectId provided and none configured on the MCP server. Pass projectId explicitly."
-        });
-      }
-      const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
-      const summary = data.checks.map((c) => ({
-        check: c.key,
-        label: c.label,
-        passed: c.ready,
-        hint: c.hint,
-        fixPath: c.fixHref
-      }));
-      return jsonText({
-        ready: data.ready,
-        repoUrl: data.repoUrl ?? null,
-        checks: summary,
-        // Human-readable summary for agents that paste the result into a prompt
-        summary: data.ready ? `Project ${resolvedId} is ready to dispatch auto-fixes${data.repoUrl ? ` (target: ${data.repoUrl})` : ""}.` : `Project ${resolvedId} cannot dispatch yet \u2014 ${summary.filter((c) => !c.passed).map((c) => c.label).join(", ")}.`
-      });
-    }
-  );
-  server.registerTool(
-    "ingest_setup_check",
-    {
-      title: titleOf("ingest_setup_check"),
-      description: descOf("ingest_setup_check"),
-      annotations: annotationsFor("ingest_setup_check"),
-      inputSchema: NO_ARG_INPUT
-    },
-    async () => {
-      const data = await apiCall("/v1/sync/ingest-setup");
-      const failed = data.steps.filter((s) => s.required && !s.complete);
-      const summary = data.ready ? `Ingest setup complete (${data.required_complete}/${data.required_total}) for ${data.project_name}.` : `Ingest incomplete (${data.required_complete}/${data.required_total}) \u2014 still need: ${failed.map((s) => s.label).join(", ")}.`;
-      return jsonText({
-        ready: data.ready,
-        projectId: data.project_id,
-        projectName: data.project_name,
-        requiredComplete: data.required_complete,
-        requiredTotal: data.required_total,
-        steps: data.steps.map((s) => ({
-          id: s.id,
-          label: s.label,
-          passed: s.complete,
-          required: s.required,
-          hint: s.hint
-        })),
-        diagnostic: data.diagnostic ?? null,
-        summary
-      });
-    }
-  );
   server.registerTool(
     "diagnose_setup",
     {
@@ -708,7 +671,8 @@ function createMushiServer(config) {
         summary: z.string(),
         nextAction: z.string().optional(),
         ingest: z.unknown().optional(),
-        dispatch: z.unknown().optional()
+        dispatch: z.unknown().optional(),
+        connection: z.unknown().optional()
       }
     },
     async (args) => {
@@ -748,162 +712,99 @@ function createMushiServer(config) {
           dispatch: { repoUrl: data.repoUrl ?? null, checks: data.checks }
         });
       }
-      const ingest = await apiCall("/v1/sync/ingest-setup");
-      let dispatchReady = true;
-      let dispatchBlock;
-      let dispatchChecks = null;
-      if (resolvedId) {
-        try {
-          const preflight = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
-          dispatchReady = preflight.ready;
-          dispatchChecks = preflight.checks;
-          if (!preflight.ready) {
-            const failed = preflight.checks.filter((c) => !c.ready);
-            dispatchBlock = failed[0]?.hint;
-          }
-        } catch (err) {
-          dispatchReady = false;
-          const detail = err instanceof Error ? err.message : String(err);
-          dispatchBlock = `Could not run dispatch preflight \u2014 ${detail}`;
-          apiLog.warn("diagnose_setup dispatch preflight failed", { error: detail });
-        }
-      }
-      const ingestFailed = ingest.steps.filter((s) => s.required && !s.complete);
-      const ingestBlock = ingestFailed[0]?.hint;
-      const ready = ingest.ready && dispatchReady;
-      const nextAction = !ingest.ready ? ingestBlock ?? "Complete SDK ingest setup." : !dispatchReady ? dispatchBlock ?? "Complete dispatch preflight in Settings \u2192 Integrations." : "All setup checks pass \u2014 submit a test report to confirm end-to-end.";
-      const summary = ready ? "Mushi ingest and dispatch setup look healthy." : !ingest.ready ? `Ingest incomplete \u2014 ${ingestFailed.map((s) => s.label).join(", ")}.` : "Ingest OK; dispatch preflight still has blockers.";
-      return jsonResult({
-        mode: "full",
-        ready,
-        summary,
-        nextAction,
-        ingest: { ready: ingest.ready, steps: ingest.steps },
-        dispatch: resolvedId ? { ready: dispatchReady, checks: dispatchChecks } : null
-      });
-    }
-  );
-  server.registerTool(
-    "diagnose_connection",
-    {
-      title: titleOf("diagnose_connection"),
-      description: descOf("diagnose_connection"),
-      annotations: annotationsFor("diagnose_connection"),
-      inputSchema: NO_ARG_INPUT,
-      outputSchema: {
-        ready: z.boolean(),
-        healthOk: z.boolean(),
-        ingestReady: z.boolean(),
-        dispatchReady: z.boolean(),
-        endpoint: z.string().nullable(),
-        projectId: z.string().nullable(),
-        accessibleProjectCount: z.number().nullable(),
-        issues: z.array(z.unknown()),
-        nextAction: z.string(),
-        summary: z.string()
-      }
-    },
-    async () => {
-      const issues = [];
+      const connIssues = [];
+      let healthOk = false;
       if (!apiKey?.startsWith("mushi_")) {
-        issues.push({
+        connIssues.push({
           check: "mcp_api_key",
-          detail: "MCP server API key missing or malformed",
-          fix: "Run `mushi connect` to write MUSHI_API_KEY into .cursor/mcp.json, then restart the MCP server."
+          detail: "MCP server API key missing or malformed (expected prefix: mushi_)",
+          fix: "Run `mushi connect` or set MUSHI_API_KEY to a valid key in your MCP config."
         });
       }
       if (!apiEndpoint) {
-        issues.push({
+        connIssues.push({
           check: "mcp_endpoint",
           detail: "No API endpoint configured",
-          fix: "Set MUSHI_API_ENDPOINT to your `\u2026/functions/v1/api` URL in .cursor/mcp.json."
+          fix: "Set MUSHI_API_ENDPOINT to your `.../functions/v1/api` URL in your MCP config."
         });
-      }
-      let healthOk = false;
-      if (apiEndpoint) {
+      } else {
         try {
           const healthRes = await doFetch(`${apiEndpoint.replace(/\/$/, "")}/health`, {
             signal: AbortSignal.timeout(5e3)
           });
           healthOk = healthRes.status === 200;
           if (!healthOk) {
-            issues.push({
+            connIssues.push({
               check: "endpoint_health",
               detail: `GET /health \u2192 HTTP ${healthRes.status}`,
               fix: "Verify MUSHI_API_ENDPOINT and that the Supabase edge function is deployed."
             });
           }
         } catch (err) {
-          issues.push({
+          connIssues.push({
             check: "endpoint_health",
             detail: err instanceof Error ? err.message : String(err),
-            fix: "Check network connectivity and the endpoint URL in .cursor/mcp.json."
+            fix: "Check network connectivity and MUSHI_API_ENDPOINT in your MCP config."
           });
         }
       }
-      let ingestReady = false;
-      let dispatchReady = false;
       let accessibleProjectCount = null;
-      if (!projectId && healthOk) {
+      if (!resolvedId && healthOk) {
         try {
-          const overview = await apiCall("/v1/admin/mcp/account-overview");
+          const overview = await apiCall(
+            "/v1/admin/mcp/account-overview"
+          );
           accessibleProjectCount = overview.total;
           if (overview.total === 0) {
-            issues.push({
+            connIssues.push({
               check: "no_accessible_projects",
               detail: "API key has no accessible projects",
-              fix: "Mint an API key on a project (console \u2192 Projects \u2192 API Keys) or add MUSHI_PROJECT_ID to restrict to a single project."
+              fix: "Mint an API key on a project (console \u2192 Projects \u2192 API Keys) or add MUSHI_PROJECT_ID."
             });
           }
         } catch {
         }
       }
-      try {
-        const ingest = await apiCall("/v1/sync/ingest-setup");
-        ingestReady = ingest.ready;
-        if (!ingest.ready) {
-          const failed = ingest.steps.filter((s) => s.required && !s.complete);
-          issues.push({
-            check: "ingest_setup",
-            detail: `Incomplete: ${failed.map((s) => s.label).join(", ")}`,
-            fix: failed[0]?.hint ?? "Paste the SDK snippet, start your dev server, submit a test report."
-          });
-        }
-      } catch (err) {
-        issues.push({
-          check: "ingest_setup",
-          detail: err instanceof Error ? err.message : String(err),
-          fix: "Confirm API key is active for this project (Projects \u2192 API Keys)."
-        });
-      }
-      if (projectId) {
+      const ingest = await apiCall("/v1/sync/ingest-setup");
+      let dispatchReady = true;
+      let dispatchBlock;
+      let dispatchChecks = null;
+      if (resolvedId) {
         try {
-          const preflight = await apiCall(`/v1/admin/projects/${projectId}/preflight`);
+          const preflight = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
           dispatchReady = preflight.ready;
+          dispatchChecks = preflight.checks;
           if (!preflight.ready) {
             const failed = preflight.checks.filter((c) => !c.ready);
-            issues.push({
-              check: "dispatch_preflight",
-              detail: `Blocked: ${failed.map((c) => c.label).join(", ")}`,
-              fix: failed[0]?.hint ?? "Open Settings \u2192 Integrations and complete GitHub + BYOK setup."
-            });
+            dispatchBlock = failed[0]?.hint;
           }
-        } catch {
+        } catch (err) {
+          dispatchReady = false;
+          const detail = err instanceof Error ? err.message : String(err);
+          dispatchBlock = `Could not run dispatch preflight \u2014 ${detail}`;
+          apiLog.warn("diagnose_setup dispatch preflight failed", { error: detail });
         }
       }
-      const ready = issues.length === 0 && healthOk && ingestReady;
-      const nextAction = issues[0]?.fix ?? (ready ? "Connection healthy \u2014 SDK ingest is working. Submit a report to confirm end-to-end." : "Run `mushi doctor` in your app repo for a full local checklist.");
+      const ingestFailed = ingest.steps.filter((s) => s.required && !s.complete);
+      const ingestBlock = ingestFailed[0]?.hint;
+      const connOk = connIssues.length === 0;
+      const ready = connOk && ingest.ready && dispatchReady;
+      const nextAction = !connOk ? connIssues[0]?.fix ?? "Fix the connection issue above." : !ingest.ready ? ingestBlock ?? "Complete SDK ingest setup." : !dispatchReady ? dispatchBlock ?? "Complete dispatch preflight in Settings \u2192 Integrations." : "All setup checks pass \u2014 submit a test report to confirm end-to-end.";
+      const summary = ready ? "Mushi connection, ingest, and dispatch setup look healthy." : !connOk ? `Connection issue \u2014 ${connIssues[0]?.check}: ${connIssues[0]?.detail}` : !ingest.ready ? `Ingest incomplete \u2014 ${ingestFailed.map((s) => s.label).join(", ")}.` : "Ingest OK; dispatch preflight still has blockers.";
       return jsonResult({
+        mode: "full",
         ready,
-        healthOk,
-        ingestReady,
-        dispatchReady,
-        endpoint: apiEndpoint ?? null,
-        projectId: projectId ?? null,
-        accessibleProjectCount,
-        issues,
+        summary,
         nextAction,
-        summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
+        connection: {
+          healthOk,
+          endpoint: apiEndpoint ?? null,
+          projectId: resolvedId ?? null,
+          accessibleProjectCount,
+          issues: connIssues
+        },
+        ingest: { ready: ingest.ready, steps: ingest.steps },
+        dispatch: resolvedId ? { ready: dispatchReady, checks: dispatchChecks } : null
       });
     }
   );
@@ -1194,13 +1095,17 @@ function createMushiServer(config) {
       description: descOf("submit_fix_result"),
       annotations: annotationsFor("submit_fix_result"),
       inputSchema: {
-        reportId: z.string().describe("The report UUID"),
-        branch: z.string().describe("Git branch name"),
-        prUrl: z.string().optional().describe("GitHub PR URL"),
-        filesChanged: z.array(z.string()).describe("Files modified"),
-        linesChanged: z.number().describe("Total lines changed"),
-        summary: z.string().describe("Fix summary"),
+        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"),
+        filesChanged: z.array(z.string()).describe("Repo-relative paths modified by the fix"),
+        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")
+      },
+      outputSchema: {
+        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) => {
@@ -1222,7 +1127,7 @@ function createMushiServer(config) {
           completed_at: (/* @__PURE__ */ new Date()).toISOString()
         })
       });
-      return jsonText({ ok: true, fixId: created.fixId });
+      return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
   server.registerTool(
@@ -1279,6 +1184,9 @@ function createMushiServer(config) {
       inputSchema: {
         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: {
+        dispatched: z.number().describe("Number of judge-batch jobs dispatched (one per accessible project)")
       }
     },
     async (args) => {
@@ -1289,7 +1197,7 @@ function createMushiServer(config) {
           projectId: args.projectId ?? projectId ?? void 0
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1316,12 +1224,18 @@ function createMushiServer(config) {
   server.registerTool(
     "merge_fix",
     {
-      title: "Merge fix PR",
-      description: "Squash-merge a fix attempt PR and mark the linked report fixed.",
+      title: titleOf("merge_fix"),
+      description: descOf("merge_fix"),
       annotations: annotationsFor("merge_fix"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID"),
-        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method")
+        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: {
+        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) => {
@@ -1329,22 +1243,27 @@ function createMushiServer(config) {
         method: "POST",
         body: JSON.stringify({ mergeMethod: args.mergeMethod ?? "squash" })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
     "refresh_ci",
     {
-      title: "Refresh fix CI status",
-      description: "Pull the latest GitHub check-run status for a fix attempt.",
+      title: titleOf("refresh_ci"),
+      description: descOf("refresh_ci"),
       annotations: annotationsFor("refresh_ci"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID")
+        fixId: z.string().describe("Fix attempt UUID whose PR check-runs should be re-polled")
+      },
+      outputSchema: {
+        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" });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1354,16 +1273,19 @@ function createMushiServer(config) {
       description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
       inputSchema: {
-        reportId: z.string().describe("Report UUID"),
-        note: z.string().optional().describe("Triage note")
+        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: {
+        report: z.unknown().describe("Updated report row with status=reopened")
       }
     },
     async (args) => {
-      const data = await apiCall(`/v1/sync/reports/${args.reportId}`, {
+      const report = await apiCall(`/v1/sync/reports/${args.reportId}`, {
         method: "PATCH",
         body: JSON.stringify({ status: "reopened", note: args.note })
       });
-      return jsonText(data);
+      return jsonResult({ report });
     }
   );
   server.registerTool(
@@ -1440,9 +1362,12 @@ function createMushiServer(config) {
       description: descOf("list_lessons"),
       annotations: annotationsFor("list_lessons"),
       inputSchema: {
-        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter by severity level."),
-        limit: z.number().optional().describe("Max number of lessons to return (default 50, max 200)."),
-        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+        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: {
+        lessons: z.array(z.unknown()).describe("Promoted lesson rows ordered by frequency")
       }
     },
     async (args) => {
@@ -1451,8 +1376,8 @@ function createMushiServer(config) {
       if (args.severity) params.set("severity", args.severity);
       params.set("limit", String(Math.min(args.limit ?? 50, 200)));
       if (pid) params.set("projectId", pid);
-      const data = await apiCall(`/v1/admin/lessons?${params}`);
-      return jsonText(data);
+      const lessons = await apiCall(`/v1/admin/lessons?${params}`);
+      return jsonResult({ lessons });
     }
   );
   server.resource(
@@ -1618,6 +1543,22 @@ function createMushiServer(config) {
       };
     }
   );
+  server.registerTool(
+    "activation_status",
+    {
+      title: titleOf("activation_status"),
+      description: descOf("activation_status"),
+      annotations: annotationsFor("activation_status"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID (defaults to the configured project).")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const qs = pid ? `?project_id=${encodeURIComponent(pid)}` : "";
+      return jsonResult(await apiCall(`/v1/admin/activation${qs}`));
+    }
+  );
   server.resource(
     "activation_status",
     "mushi://activation",
@@ -1716,7 +1657,7 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
           text: `You are a Mushi onboarding copilot. Use the MCP tools:
 1. Read mushi://activation for unified setup posture.
 2. Read project://integration-health if GitHub or Sentry looks blocked.
-3. Call get_activation_status if the resource is unavailable.
+3. Call diagnose_setup if the resource is unavailable.
 
 Then output:
 - **Status:** one sentence on what is done vs blocked
@@ -1774,11 +1715,17 @@ Be specific. No generic advice.`
       description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
       inputSchema: {
-        projectId: z.string().describe("Project id"),
-        storyNodeId: z.string().describe("User story id slug from the accepted inventory"),
-        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Gate mode for the generated test (default: review)"),
-        baseUrl: z.string().url().optional().describe("Override the app base URL"),
-        openPr: z.boolean().optional().describe("Open a draft GitHub PR (default: true)")
+        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)"),
+        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: {
+        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 }) => {
@@ -1787,7 +1734,7 @@ Be specific. No generic advice.`
         `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
         { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
       );
-      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2149,36 +2096,6 @@ Be specific. No generic advice.`
       return jsonText({ ok: true, message: `Step ${step_index} \u2192 ${args.status}` });
     }
   );
-  server.registerTool(
-    "get_activation_status",
-    {
-      title: titleOf("get_activation_status"),
-      description: descOf("get_activation_status"),
-      annotations: annotationsFor("get_activation_status"),
-      inputSchema: {
-        project_id: z.string().optional().describe("Optional project UUID override")
-      }
-    },
-    async (args) => {
-      const qs = args.project_id ? `?project_id=${encodeURIComponent(args.project_id)}` : "";
-      const data = await apiCall(`/v1/admin/activation${qs}`);
-      return jsonText(data);
-    }
-  );
-  server.registerTool(
-    "get_reporter_thread",
-    {
-      title: titleOf("get_reporter_thread"),
-      description: descOf("get_reporter_thread"),
-      annotations: annotationsFor("get_reporter_thread"),
-      inputSchema: { reportId: z.string().describe("The report UUID") }
-    },
-    // The reporter thread is the `comments` lane of the unified report
-    // timeline. There is no standalone admin `/comments` route (only the
-    // reporter-token-gated `/v1/reporter/reports/:id/comments`), so we read the
-    // admin-authed timeline, which also carries fix / QA / status lanes.
-    async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}/timeline`))
-  );
   server.registerTool(
     "ask_codebase",
     {
@@ -2263,23 +2180,31 @@ Be specific. No generic advice.`
       annotations: annotationsFor("search_codebase", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        query: z.string().describe("Plain-English search query"),
-        k: z.number().optional().describe("Number of results (default 8, max 20)"),
-        scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
+        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: {
+        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;
       if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
-      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/search`, {
-        method: "POST",
-        body: JSON.stringify({
-          query: args.query,
-          k: args.k ?? 8,
-          scope_prefix: args.scope_prefix ?? void 0
-        })
-      });
-      return jsonText(data);
+      const data = await apiCall(
+        `/v1/admin/projects/${pid}/codebase/search`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            query: args.query,
+            k: args.k ?? 8,
+            scope_prefix: args.scope_prefix ?? void 0
+          })
+        }
+      );
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2313,10 +2238,17 @@ Be specific. No generic advice.`
       annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        paths: z.array(z.string()).optional().describe("Changed file paths"),
-        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths"),
-        compare: z.string().optional().describe("GitHub compare range base...head"),
-        fix_id: z.string().optional().describe("Fix attempt UUID for PR changed files")
+        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: {
+        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) => {
@@ -2331,7 +2263,7 @@ Be specific. No generic advice.`
         throw new MushiApiError(400, "BAD_REQUEST", "Provide paths, source=last_push, compare, or fix_id");
       }
       const data = await apiCall(`/v1/admin/projects/${pid}/codebase/impact?${qs}`);
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2395,6 +2327,39 @@ Be specific. No generic advice.`
       return result;
     });
   }
+  {
+    const llAliasServer = server.server;
+    const innerHandler = llAliasServer?._requestHandlers?.get("tools/call");
+    if (typeof innerHandler === "function") {
+      llAliasServer._requestHandlers.set("tools/call", async (...args) => {
+        const req = args[0];
+        const originalName = req?.params?.name;
+        const canonicalName = originalName ? DEPRECATED_TOOL_ALIASES[originalName] : void 0;
+        if (canonicalName) {
+          const rewritten = {
+            ...args[0],
+            params: { ...req?.params ?? {}, name: canonicalName }
+          };
+          const result = await innerHandler(rewritten, ...args.slice(1));
+          if (result != null && typeof result === "object" && "content" in result && Array.isArray(result.content)) {
+            const r = result;
+            return {
+              ...r,
+              content: [
+                {
+                  type: "text",
+                  text: `\u26A0\uFE0F Deprecated: \`${originalName}\` was renamed to \`${canonicalName}\`. Update your agent config \u2014 this alias will be removed in the next release.`
+                },
+                ...r.content
+              ]
+            };
+          }
+          return result;
+        }
+        return innerHandler(...args);
+      });
+    }
+  }
   return server;
 }
 export {