@mushi-mushi/mcp 0.14.1 → 0.16.0

package/dist/server.js

@@ -1,11 +1,128 @@
 import {
+  CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-FQ5WR3PS.js";
+} from "./chunk-PZEGN4XD.js";
+import {
+  MUSHI_SERVER_METADATA
+} from "./chunk-EHB2BGWX.js";
+import {
+  toolMatchesFeatures
+} from "./chunk-B2QEG35D.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { createLogger } from "@mushi-mushi/core";
+
+// src/docs-index.ts
+var BASE = "https://kensaur.us/mushi-mushi/docs";
+var MUSHI_DOCS_INDEX = [
+  {
+    title: "Architecture overview",
+    path: `${BASE}/concepts/architecture`,
+    keywords: ["architecture", "evolution loop", "pdca", "overview"],
+    excerpt: "How Mushi captures user-felt bugs, triages, dispatches fixes, and learns."
+  },
+  {
+    title: "MCP setup",
+    path: `${BASE}/guides/mcp-setup`,
+    keywords: ["mcp", "cursor", "api key", "stdio", "http", "multi-project", "account mode", "install", "setup", "deeplink"],
+    excerpt: "Wire Mushi MCP into Cursor, Claude, or any MCP client. Supports per-project and account-level keys."
+  },
+  {
+    title: "API key scopes",
+    path: `${BASE}/guides/api-keys`,
+    keywords: ["api key", "mcp:read", "mcp:write", "scopes", "security", "account key", "org-scoped", "multi-project"],
+    excerpt: "Separate SDK ingest keys from MCP read/write keys. Mint an org-scoped account key for multi-project access."
+  },
+  {
+    title: "Account key (org-scoped)",
+    path: `${BASE}/guides/mcp-setup`,
+    keywords: ["account key", "org-scoped", "multi-project", "MUSHI_PROJECT_ID", "all projects", "mint-org-key", "get_account_overview"],
+    excerpt: "Mint one org-scoped key that covers all your projects; no MUSHI_PROJECT_ID needed. The agent calls get_account_overview to discover projects."
+  },
+  {
+    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."
+  },
+  {
+    title: "Judge loop",
+    path: `${BASE}/concepts/judge-loop`,
+    keywords: ["judge", "sonnet", "quality", "fix scoring"],
+    excerpt: "Sonnet-as-Judge scores fix quality and feeds the lesson library."
+  },
+  {
+    title: "Inventory v2",
+    path: `${BASE}/concepts/inventory`,
+    keywords: ["inventory", "user stories", "spec", "yaml", "actions"],
+    excerpt: "inventory.yaml maps pages, stories, and expected outcomes for spec traceability."
+  },
+  {
+    title: "QA coverage stories",
+    path: `${BASE}/guides/qa-stories`,
+    keywords: ["qa", "playwright", "tdd", "cron", "browserbase", "firecrawl"],
+    excerpt: "Author, approve, and schedule user-story tests."
+  },
+  {
+    title: "Skill pipelines",
+    path: `${BASE}/guides/skill-pipelines`,
+    keywords: ["skills", "pipeline", "cursor", "workflow"],
+    excerpt: "Attach agent skills to reports and run handoff or cloud pipelines."
+  },
+  {
+    title: "Dispatch fix",
+    path: `${BASE}/guides/dispatch-fix`,
+    keywords: ["dispatch", "fix", "pr", "cursor cloud", "autofix"],
+    excerpt: "Dispatch the Mushi fix agent or Cursor Cloud for a classified report."
+  },
+  {
+    title: "SDK installation",
+    path: `${BASE}/guides/sdk`,
+    keywords: ["sdk", "install", "react", "next", "ingest"],
+    excerpt: "Install @mushi-mushi/web and start capturing user reports."
+  },
+  {
+    title: "Configuration reference",
+    path: `${BASE}/reference/config`,
+    keywords: ["env", "config", "settings", "byok"],
+    excerpt: "Environment variables and project settings reference."
+  },
+  {
+    title: "Evolution loop",
+    path: `${BASE}/concepts/evolution`,
+    keywords: ["evolution", "lessons", "convergence", "prompt promotion"],
+    excerpt: "Closed-loop learning from bugs, fixes, and judge scores."
+  },
+  {
+    title: "Privacy & BYOK",
+    path: `${BASE}/guides/privacy`,
+    keywords: ["privacy", "byok", "data region", "llm"],
+    excerpt: "Data boundaries, BYOK LLM keys, and retention."
+  }
+];
+function searchMushiDocs(query, limit = 8) {
+  const q = query.trim().toLowerCase();
+  if (!q) {
+    return MUSHI_DOCS_INDEX.slice(0, limit).map((e) => ({ ...e, score: 0 }));
+  }
+  const terms = q.split(/\s+/).filter(Boolean);
+  const scored = MUSHI_DOCS_INDEX.map((entry) => {
+    const hay = `${entry.title} ${entry.keywords.join(" ")} ${entry.excerpt}`.toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+      if (entry.title.toLowerCase().includes(term)) score += 4;
+      if (entry.keywords.some((k) => k.includes(term))) score += 3;
+      if (hay.includes(term)) score += 1;
+    }
+    return { ...entry, score };
+  }).filter((e) => e.score > 0).sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
+
+// src/server.ts
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -19,10 +136,23 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const apiLog = createLogger({
+    scope: "mushi:mcp:api",
+    level: process.env.MUSHI_LOG_LEVEL ?? "info",
+    destination: "stderr"
+  });
   if (config.scopes !== void 0 && config.scopes.length === 0) {
-    return new McpServer({ name: "mushi-mushi", version });
+    return new McpServer({
+      name: MUSHI_SERVER_METADATA.name,
+      version,
+      title: MUSHI_SERVER_METADATA.title,
+      websiteUrl: MUSHI_SERVER_METADATA.websiteUrl,
+      icons: [...MUSHI_SERVER_METADATA.icons]
+    });
   }
   async function apiCall(path, options) {
+    const requestId = crypto.randomUUID().slice(0, 12);
+    const started = Date.now();
     const res = await doFetch(`${apiEndpoint}${path}`, {
       ...options,
       headers: {
@@ -32,10 +162,12 @@ function createMushiServer(config) {
         // and for transparent proxies that strip X-Mushi-* headers.
         "Authorization": `Bearer ${apiKey}`,
         "X-Mushi-Api-Key": apiKey,
-        ...projectId ? { "X-Mushi-Project": projectId } : {},
+        "X-Request-Id": requestId,
+        ...projectId ? { "X-Mushi-Project-Id": projectId } : {},
         ...options?.headers ?? {}
       }
     });
+    const durationMs = Date.now() - started;
     const text = await res.text();
     let body = null;
     if (text) {
@@ -49,6 +181,7 @@ function createMushiServer(config) {
       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}`;
+      apiLog.warn("api.failed", { path, requestId, status: res.status, durationMs, code });
       throw new MushiApiError(res.status, code, message);
     }
     const envelope = body;
@@ -56,12 +189,47 @@ function createMushiServer(config) {
       if (!envelope.ok) {
         const code = envelope.error?.code ?? "API_ERROR";
         const message = envelope.error?.message ?? "API returned ok=false";
+        apiLog.warn("api.failed", { path, requestId, status: res.status, durationMs, code });
         throw new MushiApiError(res.status, code, message);
       }
+      apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
       return envelope.data ?? {};
     }
+    apiLog.info("api.done", { path, requestId, status: res.status, durationMs });
     return body;
   }
+  async function resolveProjectId(explicitId) {
+    if (explicitId) return explicitId;
+    if (projectId) return projectId;
+    try {
+      const data = await apiCall(
+        "/v1/admin/mcp/account-overview"
+      );
+      if (data.total === 1 && data.projects[0]) {
+        return data.projects[0].id;
+      }
+      if (data.total === 0) {
+        throw new MushiApiError(
+          400,
+          "NO_ACCESSIBLE_PROJECTS",
+          "This API key has no accessible projects. Mint an API key on a project in the admin console."
+        );
+      }
+      const projectList = data.projects.map((p) => `${p.name ?? "unnamed"} (${p.id})`).join(", ");
+      throw new MushiApiError(
+        400,
+        "PROJECT_ID_REQUIRED",
+        `Multiple projects are accessible with this key: ${projectList}. Pass projectId explicitly to target a specific project, or set MUSHI_PROJECT_ID in your MCP env config.`
+      );
+    } catch (err) {
+      if (err instanceof MushiApiError) throw err;
+      throw new MushiApiError(
+        400,
+        "MISSING_PROJECT_ID",
+        "projectId is required. Set MUSHI_PROJECT_ID in .cursor/mcp.json or pass it explicitly."
+      );
+    }
+  }
   function jsonText(value) {
     return {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -74,10 +242,13 @@ function createMushiServer(config) {
     };
   }
   const server = new McpServer({
-    name: "mushi-mushi",
-    version
+    name: MUSHI_SERVER_METADATA.name,
+    version,
+    title: MUSHI_SERVER_METADATA.title,
+    websiteUrl: MUSHI_SERVER_METADATA.websiteUrl,
+    icons: [...MUSHI_SERVER_METADATA.icons]
   });
-  const ALL_TOOL_CATALOG = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+  const ALL_TOOL_CATALOG = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG, ...CODEBASE_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`);
@@ -110,7 +281,10 @@ function createMushiServer(config) {
         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)")
+        limit: z.number().optional().describe("Max reports to return (default 20, max 100)"),
+        project_id: z.string().optional().describe(
+          "Project UUID \u2014 defaults to the server-configured project. Useful when you have multiple projects and want to query a specific one by its ID. Get IDs by calling list_projects or get_account_overview first."
+        )
       },
       outputSchema: {
         reports: z.array(z.unknown()),
@@ -123,7 +297,11 @@ function createMushiServer(config) {
       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}`);
+      const pid = await resolveProjectId(args.project_id);
+      const extraHeaders = pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const data = await apiCall(`/v1/admin/reports?${params}`, {
+        headers: extraHeaders
+      });
       return jsonResult(data);
     }
   );
@@ -133,9 +311,19 @@ function createMushiServer(config) {
       title: titleOf("get_report_detail"),
       description: descOf("get_report_detail"),
       annotations: annotationsFor("get_report_detail"),
-      inputSchema: { reportId: z.string().describe("The report UUID") }
+      inputSchema: { reportId: z.string().describe("The report UUID") },
+      outputSchema: { report: z.unknown() }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}`))
+    async (args) => {
+      const data = await apiCall(`/v1/admin/reports/${args.reportId}`);
+      const res = jsonResult({ report: data });
+      return {
+        ...res,
+        resource_links: [
+          { uri: `project://reports/${args.reportId}`, title: `Report ${args.reportId.slice(0, 8)}\u2026` }
+        ]
+      };
+    }
   );
   server.registerTool(
     "get_report_timeline",
@@ -194,6 +382,9 @@ function createMushiServer(config) {
       inputSchema: {
         query: z.string().describe("Component name, page path, or bug description"),
         limit: z.number().optional().describe("Max results (default 5, max 20)")
+      },
+      outputSchema: {
+        results: z.array(z.unknown())
       }
     },
     async (args) => {
@@ -206,7 +397,7 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -215,11 +406,18 @@ function createMushiServer(config) {
       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") }
+      inputSchema: { reportId: z.string().describe("The report UUID to fix") },
+      outputSchema: {
+        report: z.unknown(),
+        reproductionSteps: z.unknown(),
+        component: z.unknown(),
+        rootCause: z.unknown(),
+        bugOntologyTags: z.unknown()
+      }
     },
     async (args) => {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
-      return jsonText({
+      return jsonResult({
         report,
         reproductionSteps: report.reproduction_steps ?? [],
         component: report.component,
@@ -457,13 +655,115 @@ function createMushiServer(config) {
       });
     }
   );
+  server.registerTool(
+    "diagnose_setup",
+    {
+      title: titleOf("diagnose_setup"),
+      description: descOf("diagnose_setup"),
+      annotations: annotationsFor("diagnose_setup"),
+      inputSchema: {
+        mode: z.enum(["full", "ingest", "dispatch"]).optional().describe("full (default) = ingest + dispatch; ingest = SDK pipeline only; dispatch = fix preflight only."),
+        project_id: z.string().optional().describe("Project UUID for dispatch checks (defaults to configured project)."),
+        projectId: z.string().optional().describe("Alias for project_id.")
+      },
+      outputSchema: {
+        mode: z.string(),
+        ready: z.boolean(),
+        summary: z.string(),
+        nextAction: z.string().optional(),
+        ingest: z.unknown().optional(),
+        dispatch: z.unknown().optional()
+      }
+    },
+    async (args) => {
+      const mode = args.mode ?? "full";
+      const resolvedId = args.project_id ?? args.projectId ?? projectId;
+      if (mode === "ingest") {
+        const data = await apiCall("/v1/sync/ingest-setup");
+        const failed = data.steps.filter((s) => s.required && !s.complete);
+        const summary2 = data.ready ? `Ingest setup complete (${data.required_complete}/${data.required_total}) for ${data.project_name}.` : `Ingest incomplete \u2014 still need: ${failed.map((s) => s.label).join(", ")}.`;
+        return jsonResult({
+          mode: "ingest",
+          ready: data.ready,
+          summary: summary2,
+          nextAction: failed[0]?.hint,
+          ingest: {
+            projectId: data.project_id,
+            projectName: data.project_name,
+            requiredComplete: data.required_complete,
+            requiredTotal: data.required_total,
+            steps: data.steps,
+            diagnostic: data.diagnostic ?? null
+          }
+        });
+      }
+      if (mode === "dispatch") {
+        if (!resolvedId) {
+          throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required for dispatch mode");
+        }
+        const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
+        const failed = data.checks.filter((c) => !c.ready);
+        const summary2 = data.ready ? `Project ${resolvedId} is ready to dispatch auto-fixes.` : `Dispatch blocked \u2014 ${failed.map((c) => c.label).join(", ")}.`;
+        return jsonResult({
+          mode: "dispatch",
+          ready: data.ready,
+          summary: summary2,
+          nextAction: failed[0]?.hint,
+          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 {
+          dispatchReady = false;
+          dispatchBlock = "Could not run dispatch preflight \u2014 verify project_id and API key scope.";
+        }
+      }
+      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: {}
+      inputSchema: {},
+      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 = [];
@@ -474,13 +774,6 @@ function createMushiServer(config) {
           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",
@@ -512,6 +805,21 @@ function createMushiServer(config) {
       }
       let ingestReady = false;
       let dispatchReady = false;
+      let accessibleProjectCount = null;
+      if (!projectId && healthOk) {
+        try {
+          const overview = await apiCall("/v1/admin/mcp/account-overview");
+          accessibleProjectCount = overview.total;
+          if (overview.total === 0) {
+            issues.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."
+            });
+          }
+        } catch {
+        }
+      }
       try {
         const ingest = await apiCall("/v1/sync/ingest-setup");
         ingestReady = ingest.ready;
@@ -547,30 +855,99 @@ function createMushiServer(config) {
       }
       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({
+      return jsonResult({
         ready,
         healthOk,
         ingestReady,
         dispatchReady,
         endpoint: apiEndpoint ?? null,
         projectId: projectId ?? null,
+        accessibleProjectCount,
         issues,
         nextAction,
         summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
       });
     }
   );
+  server.registerTool(
+    "search_mushi_docs",
+    {
+      title: titleOf("search_mushi_docs"),
+      description: descOf("search_mushi_docs"),
+      annotations: annotationsFor("search_mushi_docs"),
+      inputSchema: {
+        query: z.string().describe("Keywords to search official Mushi docs (guides, MCP, inventory, QA)."),
+        limit: z.number().int().min(1).max(20).optional().describe("Max results (default 8).")
+      },
+      outputSchema: {
+        query: z.string(),
+        results: z.array(
+          z.object({
+            title: z.string(),
+            path: z.string(),
+            excerpt: z.string(),
+            score: z.number()
+          })
+        )
+      }
+    },
+    async (args) => {
+      const query = args.query ?? "";
+      const hits = searchMushiDocs(query, args.limit ?? 8);
+      const results = hits.map(({ title, path, excerpt, score }) => ({ title, path, excerpt, score }));
+      return jsonResult({ query, results });
+    }
+  );
   server.registerTool(
     "list_projects",
     {
       title: titleOf("list_projects"),
       description: descOf("list_projects"),
       annotations: annotationsFor("list_projects"),
-      inputSchema: {}
+      inputSchema: {},
+      outputSchema: {
+        projects: z.array(z.unknown()),
+        total: z.number().optional(),
+        _multi_project_hint: z.string().optional()
+      }
     },
     async () => {
       const data = await apiCall("/v1/admin/mcp/projects");
-      return jsonText(data);
+      return jsonResult({
+        ...data,
+        _multi_project_hint: 'Each Mushi project uses a separate API key. To connect another project, open the Mushi console \u2192 MCP \u2192 Setup, pick the project from the switcher, and click "\u26A1 Add to Cursor". Each deeplink adds a uniquely-named server entry (mushi-{project-name}-{id-prefix}) so all your projects appear in your IDE simultaneously.'
+      });
+    }
+  );
+  server.registerTool(
+    "get_account_overview",
+    {
+      title: titleOf("get_account_overview"),
+      description: descOf("get_account_overview"),
+      annotations: annotationsFor("get_account_overview"),
+      inputSchema: {},
+      outputSchema: {
+        projects: z.array(z.unknown()),
+        total: z.number(),
+        active_project_id: z.string().nullable(),
+        toolCount: z.number().optional(),
+        resourceCount: z.number().optional(),
+        promptCount: z.number().optional(),
+        multi_project_hint: z.string()
+      }
+    },
+    async () => {
+      const data = await apiCall("/v1/admin/mcp/account-overview");
+      const projects = Array.isArray(data?.projects) ? data.projects : [];
+      return jsonResult({
+        projects,
+        total: data?.total ?? projects.length,
+        active_project_id: projectId ?? null,
+        toolCount: data?.toolCount,
+        resourceCount: data?.resourceCount,
+        promptCount: data?.promptCount,
+        multi_project_hint: projects.length <= 1 ? 'You are currently connected to one project. To connect additional Mushi projects, open the Mushi console \u2192 switch to each project \u2192 MCP \u2192 Setup \u2192 "\u26A1 Add to Cursor". Each click adds a uniquely-named entry (mushi-{name}-{id}) to your global ~/.cursor/mcp.json so you can triage reports across all your apps from a single Cursor session.' : `You have access to ${projects.length} projects. To connect any unconnected project, open the Mushi console \u2192 switch to that project \u2192 MCP \u2192 Setup \u2192 "\u26A1 Add to Cursor".`
+      });
     }
   );
   server.registerTool(
@@ -670,6 +1047,20 @@ function createMushiServer(config) {
         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).")
+      },
+      outputSchema: {
+        report_id: z.string(),
+        severity: z.unknown(),
+        category: z.unknown(),
+        status: z.unknown(),
+        report: z.unknown(),
+        reporter_thread: z.unknown().nullable(),
+        similar_bugs: z.unknown().nullable(),
+        fix_context: z.unknown().nullable(),
+        blast_radius: z.unknown().nullable(),
+        recent_logs: z.unknown().nullable(),
+        recommended_actions: z.array(z.unknown()),
+        triage_summary: z.string()
       }
     },
     async (args) => {
@@ -713,7 +1104,7 @@ function createMushiServer(config) {
           args: { reportId: args.report_id }
         });
       }
-      return jsonText({
+      const result = {
         report_id: args.report_id,
         severity,
         category,
@@ -726,7 +1117,15 @@ function createMushiServer(config) {
         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."}`
-      });
+      };
+      const res = jsonResult(result);
+      return {
+        ...res,
+        resource_links: [
+          { uri: `project://reports/${args.report_id}`, title: `Report ${args.report_id.slice(0, 8)}\u2026` },
+          ...pid ? [{ uri: `project://dashboard`, title: "Project dashboard" }] : []
+        ]
+      };
     }
   );
   server.registerTool(
@@ -1107,7 +1506,7 @@ function createMushiServer(config) {
       contents: [{
         uri: "privacy://status",
         mimeType: "application/json",
-        text: JSON.stringify(await apiCall("/v1/admin/privacy/status"), null, 2)
+        text: JSON.stringify(await apiCall("/v1/admin/privacy-status"), null, 2)
       }]
     })
   );
@@ -1121,7 +1520,11 @@ function createMushiServer(config) {
       contents: [{
         uri: "evolution://history",
         mimeType: "application/json",
-        text: JSON.stringify(await apiCall("/v1/admin/evolution/history"), null, 2)
+        text: projectId ? JSON.stringify(
+          await apiCall(`/v1/admin/projects/${encodeURIComponent(projectId)}/evolution-history`),
+          null,
+          2
+        ) : JSON.stringify({ ok: false, error: "project_id required" })
       }]
     })
   );
@@ -1700,12 +2103,192 @@ Be specific. No generic advice.`
     // 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",
+    {
+      title: titleOf("ask_codebase", CODEBASE_TOOL_CATALOG),
+      description: descOf("ask_codebase", CODEBASE_TOOL_CATALOG),
+      annotations: annotationsFor("ask_codebase", CODEBASE_TOOL_CATALOG),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
+        question: z.string().describe("Plain-English question about the repo"),
+        thread_id: z.string().optional().describe("Optional thread UUID to continue a conversation"),
+        file_path: z.string().optional().describe("Optional file path focus"),
+        symbol_name: z.string().optional().describe("Optional symbol name focus")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
+      const body = {
+        messages: [{ role: "user", content: args.question }]
+      };
+      if (args.thread_id) body.threadId = args.thread_id;
+      if (args.file_path) {
+        body.fileFocus = {
+          file_path: args.file_path,
+          symbol_name: args.symbol_name ?? null
+        };
+      }
+      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/chat`, {
+        method: "POST",
+        body: JSON.stringify(body)
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_file_summary",
+    {
+      title: titleOf("get_file_summary", CODEBASE_TOOL_CATALOG),
+      description: descOf("get_file_summary", CODEBASE_TOOL_CATALOG),
+      annotations: annotationsFor("get_file_summary", CODEBASE_TOOL_CATALOG),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
+        file_path: z.string().describe("Indexed file path"),
+        symbol_name: z.string().optional().describe("Optional symbol name within the file"),
+        force: z.boolean().optional().describe("Bypass cache and regenerate")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
+      const qs = new URLSearchParams({ file_path: args.file_path });
+      if (args.symbol_name) qs.set("symbol_name", args.symbol_name);
+      if (args.force) qs.set("force", "1");
+      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/summary?${qs}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_codebase_tour",
+    {
+      title: titleOf("get_codebase_tour", CODEBASE_TOOL_CATALOG),
+      description: descOf("get_codebase_tour", CODEBASE_TOOL_CATALOG),
+      annotations: annotationsFor("get_codebase_tour", CODEBASE_TOOL_CATALOG),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
+        force: z.boolean().optional().describe("Bypass cache and regenerate")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
+      const qs = args.force ? "?force=1" : "";
+      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/tour${qs}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "search_codebase",
+    {
+      title: titleOf("search_codebase", CODEBASE_TOOL_CATALOG),
+      description: descOf("search_codebase", CODEBASE_TOOL_CATALOG),
+      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")
+      }
+    },
+    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);
+    }
+  );
+  server.registerTool(
+    "get_codebase_domains",
+    {
+      title: titleOf("get_codebase_domains", CODEBASE_TOOL_CATALOG),
+      description: descOf("get_codebase_domains", CODEBASE_TOOL_CATALOG),
+      annotations: annotationsFor("get_codebase_domains", CODEBASE_TOOL_CATALOG),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
+        force: z.boolean().optional().describe("Bypass cache and regenerate"),
+        scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
+      const qs = new URLSearchParams();
+      if (args.force) qs.set("force", "1");
+      if (args.scope_prefix) qs.set("scope_prefix", args.scope_prefix);
+      const suffix = qs.toString() ? `?${qs}` : "";
+      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/domains${suffix}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "analyze_codebase_impact",
+    {
+      title: titleOf("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
+      description: descOf("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
+      annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
+      inputSchema: {
+        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")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
+      const qs = new URLSearchParams();
+      if (args.paths?.length) qs.set("paths", args.paths.join(","));
+      if (args.source === "last_push") qs.set("ref", "last_push");
+      if (args.compare) qs.set("compare", args.compare);
+      if (args.fix_id) qs.set("fix_id", args.fix_id);
+      if (!qs.toString()) {
+        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);
+    }
+  );
+  server.registerTool(
+    "analyze_wiki_knowledge",
+    {
+      title: titleOf("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
+      description: descOf("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
+      annotations: annotationsFor("analyze_wiki_knowledge", CODEBASE_TOOL_CATALOG),
+      inputSchema: {
+        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", "project_id is required");
+      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/knowledge/graph`);
+      return jsonText(data);
+    }
+  );
   const grantedScopes = config.scopes;
-  if (grantedScopes !== void 0) {
+  const featureFilter = config.features ?? "all";
+  if (grantedScopes !== void 0 || featureFilter !== "all") {
     const toolRegistry = server._registeredTools;
-    const allSpecs = [...TOOL_CATALOG, ...TDD_TOOL_CATALOG];
+    const allSpecs = [
+      ...TOOL_CATALOG,
+      ...TDD_TOOL_CATALOG,
+      ...CODEBASE_TOOL_CATALOG
+    ];
     for (const spec of allSpecs) {
-      if (!grantedScopes.includes(spec.scope)) {
+      if (grantedScopes !== void 0 && !grantedScopes.includes(spec.scope)) {
+        toolRegistry[spec.name]?.remove();
+      }
+      if (featureFilter !== "all" && !toolMatchesFeatures(spec.name, featureFilter)) {
         toolRegistry[spec.name]?.remove();
       }
     }