@mushi-mushi/mcp 0.13.1 → 0.14.0

package/dist/server.js

@@ -0,0 +1,1715 @@
+import {
+  TDD_TOOL_CATALOG,
+  TOOL_CATALOG
+} from "./chunk-QWZEQYCN.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+var MushiApiError = class extends Error {
+  constructor(status, code, message) {
+    super(`[${code}] ${message}`);
+    this.status = status;
+    this.code = code;
+    this.name = "MushiApiError";
+  }
+  status;
+  code;
+};
+function createMushiServer(config) {
+  const { version, apiEndpoint, apiKey, projectId } = config;
+  const doFetch = config.fetch ?? globalThis.fetch;
+  if (config.scopes !== void 0 && config.scopes.length === 0) {
+    return new McpServer({ name: "mushi-mushi", version });
+  }
+  async function apiCall(path, options) {
+    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,
+        ...projectId ? { "X-Mushi-Project": projectId } : {},
+        ...options?.headers ?? {}
+      }
+    });
+    const text = await res.text();
+    let body = null;
+    if (text) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = { raw: text };
+      }
+    }
+    if (!res.ok) {
+      const envelope2 = body;
+      const code = envelope2?.error?.code ?? `HTTP_${res.status}`;
+      const message = envelope2?.error?.message ?? text.slice(0, 500) ?? `Request failed with ${res.status}`;
+      throw new MushiApiError(res.status, code, message);
+    }
+    const envelope = body;
+    if (envelope && typeof envelope === "object" && "ok" in envelope) {
+      if (!envelope.ok) {
+        const code = envelope.error?.code ?? "API_ERROR";
+        const message = envelope.error?.message ?? "API returned ok=false";
+        throw new MushiApiError(res.status, code, message);
+      }
+      return envelope.data ?? {};
+    }
+    return body;
+  }
+  function jsonText(value) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+    };
+  }
+  function jsonResult(value) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+      structuredContent: value
+    };
+  }
+  const server = new McpServer({
+    name: "mushi-mushi",
+    version
+  });
+  const ALL_TOOL_CATALOG = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+  function annotationsFor(name, catalog = ALL_TOOL_CATALOG) {
+    const spec = catalog.find((t) => t.name === name);
+    if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
+    const a = {
+      title: spec.title,
+      readOnlyHint: spec.hints.readOnly
+    };
+    if (spec.hints.destructive !== void 0) a.destructiveHint = spec.hints.destructive;
+    if (spec.hints.idempotent !== void 0) a.idempotentHint = spec.hints.idempotent;
+    if (spec.hints.openWorld !== void 0) a.openWorldHint = spec.hints.openWorld;
+    return a;
+  }
+  function descOf(name, catalog = ALL_TOOL_CATALOG) {
+    const spec = catalog.find((t) => t.name === name);
+    if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
+    return spec.description;
+  }
+  function titleOf(name, catalog = ALL_TOOL_CATALOG) {
+    const spec = catalog.find((t) => t.name === name);
+    if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
+    return spec.title;
+  }
+  server.registerTool(
+    "get_recent_reports",
+    {
+      title: titleOf("get_recent_reports"),
+      description: descOf("get_recent_reports"),
+      annotations: annotationsFor("get_recent_reports"),
+      inputSchema: {
+        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"),
+        limit: z.number().optional().describe("Max reports to return (default 20, max 100)")
+      },
+      outputSchema: {
+        reports: z.array(z.unknown()),
+        total: z.number()
+      }
+    },
+    async (args) => {
+      const params = new URLSearchParams();
+      if (args.status) params.set("status", args.status);
+      if (args.category) params.set("category", args.category);
+      if (args.severity) params.set("severity", args.severity);
+      params.set("limit", String(Math.min(args.limit ?? 20, 100)));
+      const data = await apiCall(`/v1/admin/reports?${params}`);
+      return jsonResult(data);
+    }
+  );
+  server.registerTool(
+    "get_report_detail",
+    {
+      title: titleOf("get_report_detail"),
+      description: descOf("get_report_detail"),
+      annotations: annotationsFor("get_report_detail"),
+      inputSchema: { reportId: z.string().describe("The report UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}`))
+  );
+  server.registerTool(
+    "get_report_timeline",
+    {
+      title: titleOf("get_report_timeline"),
+      description: descOf("get_report_timeline"),
+      annotations: annotationsFor("get_report_timeline"),
+      inputSchema: { reportId: z.string().describe("The report UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/sync/reports/${args.reportId}/timeline`))
+  );
+  server.registerTool(
+    "get_two_way_comms_health",
+    {
+      title: titleOf("get_two_way_comms_health"),
+      description: descOf("get_two_way_comms_health"),
+      annotations: annotationsFor("get_two_way_comms_health"),
+      inputSchema: {}
+    },
+    async () => jsonText(await apiCall("/v1/sync/two-way-health"))
+  );
+  server.registerTool(
+    "search_reports",
+    {
+      title: titleOf("search_reports"),
+      description: descOf("search_reports"),
+      annotations: annotationsFor("search_reports"),
+      inputSchema: {
+        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: {
+        results: z.array(z.unknown())
+      }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/reports/similarity", {
+        method: "POST",
+        body: JSON.stringify({
+          query: args.query,
+          k: Math.min(args.limit ?? 10, 50),
+          threshold: args.threshold ?? 0.2,
+          ...projectId ? { projectId } : {}
+        })
+      });
+      return jsonResult(data);
+    }
+  );
+  server.registerTool(
+    "get_similar_bugs",
+    {
+      title: titleOf("get_similar_bugs"),
+      description: descOf("get_similar_bugs"),
+      annotations: annotationsFor("get_similar_bugs"),
+      inputSchema: {
+        query: z.string().describe("Component name, page path, or bug description"),
+        limit: z.number().optional().describe("Max results (default 5, max 20)")
+      }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/reports/similarity", {
+        method: "POST",
+        body: JSON.stringify({
+          query: args.query,
+          k: Math.min(args.limit ?? 5, 20),
+          threshold: 0.3,
+          ...projectId ? { projectId } : {}
+        })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_fix_context",
+    {
+      title: titleOf("get_fix_context"),
+      description: descOf("get_fix_context"),
+      annotations: annotationsFor("get_fix_context"),
+      inputSchema: { reportId: z.string().describe("The report UUID to fix") }
+    },
+    async (args) => {
+      const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      return jsonText({
+        report,
+        reproductionSteps: report.reproduction_steps ?? [],
+        component: report.component,
+        rootCause: report.stage2_analysis?.rootCause,
+        bugOntologyTags: report.bug_ontology_tags
+      });
+    }
+  );
+  server.registerTool(
+    "get_fix_timeline",
+    {
+      title: titleOf("get_fix_timeline"),
+      description: descOf("get_fix_timeline"),
+      annotations: annotationsFor("get_fix_timeline"),
+      inputSchema: { fixId: z.string().describe("fix_attempt UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`))
+  );
+  server.registerTool(
+    "get_blast_radius",
+    {
+      title: titleOf("get_blast_radius"),
+      description: descOf("get_blast_radius"),
+      annotations: annotationsFor("get_blast_radius"),
+      inputSchema: { nodeId: z.string().describe("Graph node UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`))
+  );
+  server.registerTool(
+    "get_knowledge_graph",
+    {
+      title: titleOf("get_knowledge_graph"),
+      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)")
+      }
+    },
+    async (args) => {
+      const params = new URLSearchParams({
+        seed: args.seed,
+        depth: String(Math.min(args.depth ?? 2, 4))
+      });
+      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+    }
+  );
+  server.registerTool(
+    "graph_neighborhood",
+    {
+      title: titleOf("graph_neighborhood"),
+      description: descOf("graph_neighborhood"),
+      annotations: annotationsFor("graph_neighborhood"),
+      inputSchema: {
+        seed: z.string().describe("Starting node id or label"),
+        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+      }
+    },
+    async (args) => {
+      const params = new URLSearchParams({
+        seed: args.seed,
+        depth: String(Math.min(args.depth ?? 2, 4))
+      });
+      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+    }
+  );
+  server.registerTool(
+    "graph_node_status",
+    {
+      title: titleOf("graph_node_status"),
+      description: descOf("graph_node_status"),
+      annotations: annotationsFor("graph_node_status"),
+      inputSchema: { nodeId: z.string().describe("graph_nodes.id") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
+  );
+  server.registerTool(
+    "inventory_get",
+    {
+      title: titleOf("inventory_get"),
+      description: descOf("inventory_get"),
+      annotations: annotationsFor("inventory_get"),
+      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");
+      return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
+    }
+  );
+  server.registerTool(
+    "inventory_diff",
+    {
+      title: titleOf("inventory_diff"),
+      description: descOf("inventory_diff"),
+      annotations: annotationsFor("inventory_diff"),
+      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)")
+      }
+    },
+    async (args) => {
+      const pid = args.projectId ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_diff");
+      const q = new URLSearchParams({ from: args.fromSha, to: args.toSha });
+      return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
+    }
+  );
+  server.registerTool(
+    "inventory_findings",
+    {
+      title: titleOf("inventory_findings"),
+      description: descOf("inventory_findings"),
+      annotations: annotationsFor("inventory_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")
+      }
+    },
+    async (args) => {
+      const pid = args.projectId ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for inventory_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}`));
+    }
+  );
+  server.registerTool(
+    "fix_suggest",
+    {
+      title: titleOf("fix_suggest"),
+      description: descOf("fix_suggest"),
+      annotations: annotationsFor("fix_suggest"),
+      inputSchema: { reportId: z.string().describe("Report UUID") }
+    },
+    async (args) => {
+      const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      const s2 = report.stage2_analysis;
+      return jsonText({
+        reportId: args.reportId,
+        rootCause: s2?.rootCause ?? null,
+        suggestedFix: s2?.suggestedFix ?? null,
+        reproductionSteps: report.reproduction_steps ?? [],
+        summary: report.summary ?? null,
+        component: report.component ?? null
+      });
+    }
+  );
+  server.registerTool(
+    "run_nl_query",
+    {
+      title: titleOf("run_nl_query"),
+      description: descOf("run_nl_query"),
+      annotations: annotationsFor("run_nl_query"),
+      inputSchema: { 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", {
+        method: "POST",
+        body: JSON.stringify({ question: args.question })
+      });
+      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: {}
+    },
+    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_connection",
+    {
+      title: titleOf("diagnose_connection"),
+      description: descOf("diagnose_connection"),
+      annotations: annotationsFor("diagnose_connection"),
+      inputSchema: {}
+    },
+    async () => {
+      const issues = [];
+      if (!apiKey?.startsWith("mushi_")) {
+        issues.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."
+        });
+      }
+      if (!projectId) {
+        issues.push({
+          check: "mcp_project_id",
+          detail: "No projectId configured on the MCP server",
+          fix: "Add MUSHI_PROJECT_ID to .cursor/mcp.json (copy UUID from console \u2192 Projects)."
+        });
+      }
+      if (!apiEndpoint) {
+        issues.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."
+        });
+      }
+      let healthOk = false;
+      if (apiEndpoint) {
+        try {
+          const healthRes = await doFetch(`${apiEndpoint.replace(/\/$/, "")}/health`, {
+            signal: AbortSignal.timeout(5e3)
+          });
+          healthOk = healthRes.status === 200;
+          if (!healthOk) {
+            issues.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({
+            check: "endpoint_health",
+            detail: err instanceof Error ? err.message : String(err),
+            fix: "Check network connectivity and the endpoint URL in .cursor/mcp.json."
+          });
+        }
+      }
+      let ingestReady = false;
+      let dispatchReady = false;
+      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) {
+        try {
+          const preflight = await apiCall(`/v1/admin/projects/${projectId}/preflight`);
+          dispatchReady = preflight.ready;
+          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."
+            });
+          }
+        } catch {
+        }
+      }
+      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.");
+      return jsonText({
+        ready,
+        healthOk,
+        ingestReady,
+        dispatchReady,
+        endpoint: apiEndpoint ?? null,
+        projectId: projectId ?? null,
+        issues,
+        nextAction,
+        summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
+      });
+    }
+  );
+  server.registerTool(
+    "list_projects",
+    {
+      title: titleOf("list_projects"),
+      description: descOf("list_projects"),
+      annotations: annotationsFor("list_projects"),
+      inputSchema: {}
+    },
+    async () => {
+      const data = await apiCall("/v1/admin/mcp/projects");
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_project_context",
+    {
+      title: titleOf("get_project_context"),
+      description: descOf("get_project_context"),
+      annotations: annotationsFor("get_project_context"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
+      const [preflightRes, activationRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/projects/${pid}/preflight`),
+        apiCall(`/v1/admin/activation?project_id=${encodeURIComponent(pid)}`)
+      ]);
+      return jsonText({
+        project_id: pid,
+        preflight: preflightRes.status === "fulfilled" ? preflightRes.value : { error: String(preflightRes.reason) },
+        activation: activationRes.status === "fulfilled" ? activationRes.value : { error: String(activationRes.reason) }
+      });
+    }
+  );
+  server.registerTool(
+    "get_pipeline_logs",
+    {
+      title: titleOf("get_pipeline_logs"),
+      description: descOf("get_pipeline_logs"),
+      annotations: annotationsFor("get_pipeline_logs"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
+        service: z.enum(["classify-report", "fix-worker", "qa-story-runner", "mcp", "webhook", "api", "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;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
+      const qs = new URLSearchParams();
+      if (args.service && args.service !== "all") qs.set("service", args.service);
+      if (args.since) qs.set("since", args.since);
+      qs.set("limit", String(Math.min(args.limit ?? 50, 200)));
+      if (args.level) qs.set("level", args.level);
+      const data = await apiCall(`/v1/admin/mcp/logs/${pid}?${qs}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_report_evidence",
+    {
+      title: titleOf("get_report_evidence"),
+      description: descOf("get_report_evidence"),
+      annotations: annotationsFor("get_report_evidence"),
+      inputSchema: {
+        report_id: z.string().describe("Report UUID.")
+      }
+    },
+    async (args) => {
+      const [reportRes, timelineRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/reports/${args.report_id}`),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`)
+      ]);
+      const report = reportRes.status === "fulfilled" ? reportRes.value : null;
+      const timeline = timelineRes.status === "fulfilled" ? timelineRes.value : null;
+      const evidence = report ? {
+        report_id: args.report_id,
+        description: report.description,
+        summary: report.summary,
+        screenshot_url: report.screenshot_url ?? null,
+        environment: report.environment ?? null,
+        breadcrumbs: report.breadcrumbs ?? null,
+        sentry_replay_id: report.sentry_replay_id ?? null,
+        sentry_trace_id: report.sentry_trace_id ?? null,
+        sentry_event_id: report.sentry_event_id ?? null,
+        session_id: report.session_id ?? null,
+        created_at: report.created_at,
+        tags: report.tags ?? null
+      } : { error: String(reportRes.reason) };
+      return jsonText({
+        evidence,
+        reporter_thread: timeline ?? { error: String(timelineRes.reason) }
+      });
+    }
+  );
+  server.registerTool(
+    "triage_issue",
+    {
+      title: titleOf("triage_issue"),
+      description: descOf("triage_issue"),
+      annotations: annotationsFor("triage_issue"),
+      inputSchema: {
+        report_id: z.string().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).")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const includeLogs = args.include_logs !== false;
+      const [reportRes, evidenceRes, similarRes, fixCtxRes, blastRes, logsRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/reports/${args.report_id}`),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`),
+        apiCall(`/v1/admin/reports/similarity`, {
+          method: "POST",
+          body: JSON.stringify({ report_id: args.report_id })
+        }).catch(() => null),
+        pid ? apiCall(`/v1/admin/reports/${args.report_id}/fix-context`).catch(() => null) : Promise.resolve(null),
+        pid ? apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`).catch(() => null) : Promise.resolve(null),
+        includeLogs && pid ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`).catch(() => null) : Promise.resolve(null)
+      ]);
+      const report = reportRes.status === "fulfilled" ? reportRes.value : null;
+      const severity = report ? report.severity : "unknown";
+      const category = report ? report.category : "unknown";
+      const status = report ? report.status : "unknown";
+      const actions = [];
+      if (status === "new" || status === "classified") {
+        actions.push({
+          action: "dispatch_fix",
+          reason: "Report is classified but no fix has been attempted",
+          tool: "dispatch_fix",
+          args: { reportId: args.report_id, agent: "cursor_cloud" }
+        });
+      } else if (status === "fixing") {
+        actions.push({
+          action: "check_fix_progress",
+          reason: "Fix is in progress \u2014 check the fix timeline for latest status",
+          tool: "get_fix_timeline",
+          args: { reportId: args.report_id }
+        });
+      } else if (status === "fixed") {
+        actions.push({
+          action: "verify_fix",
+          reason: "Fix was applied \u2014 verify it resolved the issue",
+          tool: "get_fix_context",
+          args: { reportId: args.report_id }
+        });
+      }
+      return jsonText({
+        report_id: args.report_id,
+        severity,
+        category,
+        status,
+        report: reportRes.status === "fulfilled" ? reportRes.value : { error: String(reportRes.reason) },
+        reporter_thread: evidenceRes.status === "fulfilled" ? evidenceRes.value : null,
+        similar_bugs: similarRes.status === "fulfilled" ? similarRes.value : null,
+        fix_context: fixCtxRes.status === "fulfilled" ? fixCtxRes.value : null,
+        blast_radius: blastRes.status === "fulfilled" ? blastRes.value : null,
+        recent_logs: logsRes.status === "fulfilled" ? logsRes.value : null,
+        recommended_actions: actions,
+        triage_summary: `[${severity}] ${category} \u2014 status: ${status}. ${actions.length > 0 ? `Recommended: ${actions[0]?.action}.` : "No action required."}`
+      });
+    }
+  );
+  server.registerTool(
+    "submit_fix_result",
+    {
+      title: titleOf("submit_fix_result"),
+      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"),
+        idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
+      }
+    },
+    async (args) => {
+      const idemKey = args.idempotencyKey ?? crypto.randomUUID();
+      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()
+        })
+      });
+      return jsonText({ ok: true, fixId: created.fixId });
+    }
+  );
+  server.registerTool(
+    "dispatch_fix",
+    {
+      title: titleOf("dispatch_fix"),
+      description: descOf("dispatch_fix"),
+      annotations: annotationsFor("dispatch_fix"),
+      inputSchema: {
+        reportId: z.string().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("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
+        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: {
+        fixId: z.string(),
+        status: z.string()
+      }
+    },
+    async (args, extra) => {
+      if (extra?.sendNotification && extra?._meta?.progressToken) {
+        try {
+          await extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+              progressToken: extra._meta.progressToken,
+              progress: 0,
+              total: 100,
+              message: "Dispatching Mushi fix orchestrator\u2026"
+            }
+          });
+        } catch {
+        }
+      }
+      const data = await apiCall("/v1/admin/fixes/dispatch", {
+        method: "POST",
+        headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
+        body: JSON.stringify({
+          reportId: args.reportId,
+          agent: args.agent,
+          inventoryActionNodeId: args.inventoryActionNodeId,
+          ...projectId ? { projectId } : {}
+        })
+      });
+      return jsonResult(data);
+    }
+  );
+  server.registerTool(
+    "trigger_judge",
+    {
+      title: titleOf("trigger_judge"),
+      description: descOf("trigger_judge"),
+      annotations: annotationsFor("trigger_judge"),
+      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")
+      }
+    },
+    async (args) => {
+      const data = await apiCall("/v1/admin/judge/run", {
+        method: "POST",
+        body: JSON.stringify({
+          limit: Math.min(args.limit ?? 25, 100),
+          projectId: args.projectId ?? projectId ?? void 0
+        })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "test_gen_from_report",
+    {
+      title: titleOf("test_gen_from_report"),
+      description: descOf("test_gen_from_report"),
+      annotations: annotationsFor("test_gen_from_report"),
+      inputSchema: {
+        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;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for test_gen_from_report");
+      const data = await apiCall(`/v1/admin/inventory/${pid}/test-gen/from-report/${args.reportId}`, {
+        method: "POST",
+        body: JSON.stringify({})
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "merge_fix",
+    {
+      title: "Merge fix PR",
+      description: "Squash-merge a fix attempt PR and mark the linked report fixed.",
+      annotations: annotationsFor("merge_fix"),
+      inputSchema: {
+        fixId: z.string().describe("Fix attempt UUID"),
+        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/fixes/${args.fixId}/merge`, {
+        method: "POST",
+        body: JSON.stringify({ mergeMethod: args.mergeMethod ?? "squash" })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "refresh_ci",
+    {
+      title: "Refresh fix CI status",
+      description: "Pull the latest GitHub check-run status for a fix attempt.",
+      annotations: annotationsFor("refresh_ci"),
+      inputSchema: {
+        fixId: z.string().describe("Fix attempt UUID")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "reopen_report",
+    {
+      title: titleOf("reopen_report"),
+      description: descOf("reopen_report"),
+      annotations: annotationsFor("reopen_report"),
+      inputSchema: {
+        reportId: z.string().describe("Report UUID"),
+        note: z.string().optional().describe("Triage note")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/sync/reports/${args.reportId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status: "reopened", note: args.note })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "transition_status",
+    {
+      title: titleOf("transition_status"),
+      description: descOf("transition_status"),
+      annotations: annotationsFor("transition_status"),
+      inputSchema: {
+        reportId: z.string().describe("Report UUID"),
+        status: z.enum(["pending", "classified", "grouped", "fixing", "fixed", "resolved", "verified", "reopened", "dismissed"]).describe("Target status"),
+        reason: z.string().optional().describe("Reason for the transition (audit trail)")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/reports/${args.reportId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status: args.status, reason: args.reason })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "setup_repo_for_mushi",
+    {
+      title: titleOf("setup_repo_for_mushi"),
+      description: descOf("setup_repo_for_mushi"),
+      annotations: annotationsFor("setup_repo_for_mushi"),
+      inputSchema: {
+        projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
+      }
+    },
+    async (args) => {
+      const pid = args.projectId ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for setup_repo_for_mushi");
+      const data = await apiCall(`/v1/admin/projects/${pid}/repo/bootstrap`, {
+        method: "POST",
+        body: JSON.stringify({})
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "query_lessons",
+    {
+      title: titleOf("query_lessons"),
+      description: descOf("query_lessons"),
+      annotations: annotationsFor("query_lessons"),
+      inputSchema: {
+        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;
+      const params = new URLSearchParams();
+      params.set("diff_text", args.diff_text);
+      if (args.max_tokens !== void 0) params.set("max_tokens", String(args.max_tokens));
+      if (args.top_k !== void 0) params.set("top_k", String(args.top_k));
+      if (pid) params.set("projectId", pid);
+      const data = await apiCall(`/v1/admin/lessons/query?${params}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "list_lessons",
+    {
+      title: titleOf("list_lessons"),
+      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.")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const params = new URLSearchParams();
+      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);
+    }
+  );
+  server.resource(
+    "project_stats",
+    "project://stats",
+    { description: "Report counts, category breakdown, severity distribution" },
+    async () => ({
+      contents: [{ uri: "project://stats", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/stats"), null, 2) }]
+    })
+  );
+  server.resource(
+    "project_settings",
+    "project://settings",
+    { description: "Project configuration \u2014 autofix agent, plugins enabled, ontology, LLM budgets" },
+    async () => ({
+      contents: [{ uri: "project://settings", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/settings"), null, 2) }]
+    })
+  );
+  server.resource(
+    "project_dashboard",
+    "project://dashboard",
+    { description: "PDCA health snapshot \u2014 stage counts, bottleneck, recent activity (same payload the admin console polls)" },
+    async () => ({
+      contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
+    })
+  );
+  server.registerTool(
+    "list_top_contributors",
+    {
+      title: titleOf("list_top_contributors"),
+      description: descOf("list_top_contributors"),
+      annotations: annotationsFor("list_top_contributors"),
+      inputSchema: {
+        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: [{
+        type: "text",
+        text: JSON.stringify(
+          await apiCall(`/v1/admin/rewards/leaderboard?range=${range}&limit=${limit}`),
+          null,
+          2
+        )
+      }]
+    })
+  );
+  server.registerTool(
+    "award_bonus_points",
+    {
+      title: titleOf("award_bonus_points"),
+      description: descOf("award_bonus_points"),
+      annotations: annotationsFor("award_bonus_points"),
+      inputSchema: {
+        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: [{
+        type: "text",
+        text: JSON.stringify(
+          await apiCall("/v1/admin/rewards/bonus-points", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ external_user_id, points, reason })
+          }),
+          null,
+          2
+        )
+      }]
+    })
+  );
+  server.registerTool(
+    "set_tier",
+    {
+      title: titleOf("set_tier"),
+      description: descOf("set_tier"),
+      annotations: annotationsFor("set_tier"),
+      inputSchema: {
+        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: [{
+        type: "text",
+        text: JSON.stringify(
+          await apiCall("/v1/admin/rewards/set-tier", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ external_user_id, tier_slug, reason })
+          }),
+          null,
+          2
+        )
+      }]
+    })
+  );
+  server.resource(
+    "privacy_status",
+    "privacy://status",
+    {
+      description: "Returns the privacy posture for this project: storage region, LLM provider, whether BYOK is configured, data retention window, and last audit timestamp."
+    },
+    async () => ({
+      contents: [{
+        uri: "privacy://status",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/privacy/status"), null, 2)
+      }]
+    })
+  );
+  server.resource(
+    "evolution_history",
+    "evolution://history",
+    {
+      description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling."
+    },
+    async () => ({
+      contents: [{
+        uri: "evolution://history",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/evolution/history"), null, 2)
+      }]
+    })
+  );
+  server.resource(
+    "project_integration_health",
+    "project://integration-health",
+    {
+      description: "Live health status of every configured BYOK channel (Sentry, GitHub, LangFuse, PagerDuty, \u2026). Orchestrators should check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run."
+    },
+    async () => ({
+      contents: [{
+        uri: "project://integration-health",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/integrations/health"), null, 2)
+      }]
+    })
+  );
+  server.resource(
+    "inventory_current",
+    "inventory://current",
+    {
+      description: "Current inventory snapshot for the active project \u2014 all Action nodes with their spec contract (expected_outcome), build-gate status, linked reports, and fix attempts. Subscribe to this resource to receive notifications/resources/updated when the inventory is re-crawled (e.g. after a PR merge or manual trigger). Orchestrators can use this to enumerate work items and pick the next Action to fix."
+    },
+    async () => {
+      const path = projectId ? `/v1/admin/inventory/${projectId}` : "/v1/admin/inventory";
+      return {
+        contents: [{
+          uri: "inventory://current",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall(path), null, 2)
+        }]
+      };
+    }
+  );
+  server.resource(
+    "activation_status",
+    "mushi://activation",
+    {
+      description: "Unified setup posture \u2014 SDK heartbeat, reports, GitHub, MCP readiness, QA stories, and the next best action."
+    },
+    async () => {
+      const qs = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
+      return {
+        contents: [{
+          uri: "mushi://activation",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall(`/v1/admin/activation${qs}`), null, 2)
+        }]
+      };
+    }
+  );
+  server.prompt(
+    "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") },
+    ({ reportId }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a senior engineer preparing a fix plan. Use the Mushi MCP tools to:
+1. Call get_fix_context for reportId "${reportId}".
+2. Call get_blast_radius if the report has a component node id.
+3. Call get_similar_bugs with the component or summary as the query.
+
+Then produce a markdown fix plan with exactly these sections:
+- One-line root cause
+- Files likely to change (smallest set that fixes the root cause)
+- Reproduction steps (numbered, \u22645)
+- Blast-radius warnings (what else might break)
+- Confidence (low/medium/high) with a one-line justification
+
+Lead with the fix. Skip the preamble.`
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "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") },
+    ({ fixId }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a release engineer. Use the Mushi MCP tools:
+1. Call get_fix_timeline for fixId "${fixId}" to see the full PDCA journey.
+
+Then write a short verdict in this format:
+- **Recommendation:** ship / iterate / dismiss
+- **Why:** 1\u20132 sentences referencing the judge scores and CI signal
+- **If iterate:** bullet list of the smallest next patch
+
+No preamble, no score-by-score recap \u2014 the numbers are in the tool output.`
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "triage_next_steps",
+    'Answer "what should I focus on right now?" \u2014 five-item markdown list drawn from the dashboard + recent classified queue.',
+    {},
+    () => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a tech lead looking at the Mushi cockpit. Use the MCP tools:
+1. Read the project://dashboard resource for the PDCA snapshot.
+2. Call get_recent_reports with status="classified", limit=10.
+
+Then output exactly 5 bullets, in priority order, each formatted as:
+\`**Action** \u2014 why it matters \u2014 suggested tool call\`
+
+Prefer items that are bottlenecks or critical severity. Skip filler.`
+        }
+      }]
+    })
+  );
+  server.prompt(
+    "mushi_setup",
+    "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
+    {},
+    () => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          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.
+
+Then output:
+- **Status:** one sentence on what is done vs blocked
+- **Next step:** the single highest-leverage action (console link or CLI command)
+- **Prove it:** how the user verifies the step worked
+- **If still stuck:** one diagnostic command (e.g. mushi doctor --fix)
+
+Be specific. No generic advice.`
+        }
+      }]
+    })
+  );
+  server.registerTool(
+    "map_user_stories",
+    {
+      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: {
+        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");
+      const data = await apiCall(
+        `/v1/admin/inventory/${projectId2}/map-from-live`,
+        { method: "POST", body: JSON.stringify({ base_url: baseUrl, max_pages: maxPages, provider, cursor_cloud_refine: cursorCloudRefine }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_map_run_status",
+    {
+      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: {
+        projectId: z.string().describe("Project id")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(`/v1/admin/inventory/${projectId2}/map-runs`);
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "generate_tdd_from_story",
+    {
+      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: {
+        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)")
+      }
+    },
+    async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
+      if (!projectId2) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required");
+      const data = await apiCall(
+        `/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) }] };
+    }
+  );
+  server.registerTool(
+    "improve_qa_story",
+    {
+      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: {
+        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",
+        { method: "POST", body: JSON.stringify({ project_id: projectId2 }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "run_qa_story",
+    {
+      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: {
+        projectId: z.string().describe("Project id"),
+        qaStoryId: z.string().describe("qa_story id to run")
+      }
+    },
+    async ({ projectId: projectId2, qaStoryId }) => {
+      const data = await apiCall(
+        `/v1/admin/projects/${projectId2}/qa-stories/${qaStoryId}/run`,
+        { method: "POST" }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_byok_keys",
+    {
+      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: {
+        projectId: z.string().describe("Project id")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(`/v1/admin/byok/keys?project_id=${encodeURIComponent(projectId2)}`);
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "add_byok_key",
+    {
+      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: {
+        projectId: z.string().describe("Project id"),
+        provider: z.enum(["anthropic", "openai", "firecrawl", "browserbase", "cursor"]).describe("Provider slug"),
+        key: z.string().min(10).describe("The API key value to add"),
+        label: z.string().optional().describe("Human-readable label for this key"),
+        priority: z.number().int().min(1).max(999).optional().describe("Priority for ordering (lower = higher priority)")
+      }
+    },
+    async ({ projectId: projectId2, provider, key, label, priority }) => {
+      const data = await apiCall(
+        "/v1/admin/byok/keys",
+        { method: "POST", body: JSON.stringify({ project_id: projectId2, provider_slug: provider, key, label, priority }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_pending_review_stories",
+    {
+      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: {
+        projectId: z.string().describe("Project id")
+      }
+    },
+    async ({ projectId: projectId2 }) => {
+      const data = await apiCall(`/v1/admin/inventory/${projectId2}/stories/pending-review`);
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "approve_qa_story",
+    {
+      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: {
+        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(
+        `/v1/admin/inventory/${projectId2}/stories/${qaStoryId}/approval`,
+        { method: "PATCH", body: JSON.stringify({ status }) }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "reply_to_reporter",
+    {
+      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: {
+        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`,
+        {
+          method: "POST",
+          body: JSON.stringify({ message, author_name: authorName })
+        }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_qa_story_runs",
+    {
+      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: {
+        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(
+        `/v1/admin/projects/${config.projectId}/qa-stories/${storyId}/runs?limit=${limit ?? 10}`
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_qa_story_run",
+    {
+      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: {
+        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(
+        `/v1/admin/projects/${config.projectId}/qa-stories/${storyId}/runs?limit=50`
+      );
+      const run = data?.data?.runs?.find((r) => r.id === runId) ?? null;
+      if (!run) {
+        throw new MushiApiError(
+          404,
+          "RUN_NOT_FOUND",
+          `Run ${runId} not found in the 50 most recent runs for story ${storyId}`
+        );
+      }
+      return { content: [{ type: "text", text: JSON.stringify(run, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "test_notification_channel",
+    {
+      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: {
+        kind: z.enum(["slack", "discord"]).describe("Notification channel kind to test")
+      }
+    },
+    async ({ kind }) => {
+      const data = await apiCall(
+        `/v1/admin/projects/${config.projectId}/integrations/${kind}/test`,
+        { method: "POST" }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "run_fullstack_audit",
+    {
+      title: titleOf("run_fullstack_audit"),
+      description: descOf("run_fullstack_audit"),
+      annotations: annotationsFor("run_fullstack_audit"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project ID to audit. Defaults to the configured project.")
+      }
+    },
+    async ({ project_id }) => {
+      const pid = project_id ?? config.projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
+      const data = await apiCall(
+        `/v1/admin/projects/${pid}/audit`,
+        { method: "POST", body: "{}" }
+      );
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_backend_health",
+    {
+      title: titleOf("get_backend_health"),
+      description: descOf("get_backend_health"),
+      annotations: annotationsFor("get_backend_health"),
+      inputSchema: {
+        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;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
+      const [schemaRes, advisorsRes, logsRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/projects/${pid}/backend/schema`),
+        apiCall(`/v1/admin/projects/${pid}/db-advisors`),
+        include_logs ? apiCall(`/v1/admin/projects/${pid}/backend/logs?service=api`) : Promise.resolve(null)
+      ]);
+      const result = {
+        schema: schemaRes.status === "fulfilled" ? schemaRes.value : { error: String(schemaRes.reason) },
+        advisors: advisorsRes.status === "fulfilled" ? advisorsRes.value : { error: String(advisorsRes.reason) },
+        logs: logsRes.status === "fulfilled" ? logsRes.value : include_logs ? { error: String(logsRes.reason) } : null
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "list_skills",
+    {
+      title: titleOf("list_skills"),
+      description: descOf("list_skills"),
+      annotations: annotationsFor("list_skills"),
+      inputSchema: {
+        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();
+      if (args.category) qs.set("category", args.category);
+      if (args.search) qs.set("q", args.search);
+      if (args.page) qs.set("page", String(args.page));
+      qs.set("limit", String(Math.min(args.limit ?? 200, 200)));
+      const data = await apiCall(`/v1/admin/skills?${qs}`);
+      const skills = Array.isArray(data) ? data : [];
+      return jsonText({ skills, count: skills.length });
+    }
+  );
+  server.registerTool(
+    "get_skill",
+    {
+      title: titleOf("get_skill"),
+      description: descOf("get_skill"),
+      annotations: annotationsFor("get_skill"),
+      inputSchema: {
+        slug: z.string().describe('Skill slug, e.g. "workflow-fix-and-ship"')
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/skills/${args.slug}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "start_skill_pipeline",
+    {
+      title: titleOf("start_skill_pipeline"),
+      description: descOf("start_skill_pipeline"),
+      annotations: annotationsFor("start_skill_pipeline"),
+      inputSchema: {
+        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;
+      if (!resolvedProjectId) return jsonText({ error: "No project_id provided or configured." });
+      const data = await apiCall(
+        "/v1/admin/skills/pipelines",
+        { method: "POST", body: JSON.stringify({ ...args, project_id: resolvedProjectId }) }
+      );
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_pipeline_run",
+    {
+      title: titleOf("get_pipeline_run"),
+      description: descOf("get_pipeline_run"),
+      annotations: annotationsFor("get_pipeline_run"),
+      inputSchema: {
+        run_id: z.string().describe("Pipeline run UUID")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/skills/pipelines/${args.run_id}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "checkin_pipeline_step",
+    {
+      title: titleOf("checkin_pipeline_step"),
+      description: descOf("checkin_pipeline_step"),
+      annotations: annotationsFor("checkin_pipeline_step"),
+      inputSchema: {
+        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;
+      await apiCall(
+        `/v1/admin/skills/pipelines/${run_id}/steps/${step_index}/checkin`,
+        { method: "POST", body: JSON.stringify(body) }
+      );
+      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`))
+  );
+  const grantedScopes = config.scopes;
+  if (grantedScopes !== void 0) {
+    const toolRegistry = server._registeredTools;
+    const allSpecs = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+    for (const spec of allSpecs) {
+      if (!grantedScopes.includes(spec.scope)) {
+        toolRegistry[spec.name]?.remove();
+      }
+    }
+  }
+  return server;
+}
+export {
+  MushiApiError,
+  createMushiServer
+};