@mushi-mushi/mcp 0.14.1 → 0.15.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "module";
-import { createLogger } from "@mushi-mushi/core";
+import { createLogger as createLogger2 } from "@mushi-mushi/core";
 
 // src/catalog.ts
 var ALL_SCOPES = ["mcp:read", "mcp:write"];
@@ -141,7 +141,7 @@ var TOOL_CATALOG = [
   {
     name: "setup_check",
     title: "Dispatch preflight check",
-    description: "Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, Anthropic BYOK key present, autofix enabled). Also returns the target repo URL when GitHub is connected. Use this before calling dispatch_fix to understand why a dispatch might fail. For SDK ingest health (API key \u2192 heartbeat \u2192 first report), call ingest_setup_check instead.",
+    description: "[Deprecated \u2014 use diagnose_setup with mode=dispatch or diagnose_connection.] Run the 4 **dispatch-readiness** checks for a project and return their pass/fail status (GitHub repo connected, codebase indexed, Anthropic BYOK key present, autofix enabled). Also returns the target repo URL when GitHub is connected.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Is this project ready to auto-fix bugs? What is blocking dispatch?"
@@ -149,19 +149,35 @@ var TOOL_CATALOG = [
   {
     name: "ingest_setup_check",
     title: "Ingest setup check",
-    description: "Run the 4 **required ingest** checks for the project tied to this API key: project exists, active API key, SDK heartbeat (or real report), and at least one ingested report. Returns per-step pass/fail plus last_sdk_seen_at and endpoint host diagnostics. Use after wiring env vars or pasting the SDK snippet to confirm the banner will work.",
+    description: "[Deprecated \u2014 use diagnose_setup with mode=ingest or diagnose_connection.] Run the 4 **required ingest** checks for the project tied to this API key: project exists, active API key, SDK heartbeat (or real report), and at least one ingested report.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Is the SDK installed and ingesting reports? Why is my banner still missing?"
   },
+  {
+    name: "diagnose_setup",
+    title: "Unified setup diagnose",
+    description: "Single entry point for setup health. mode=full (default) runs ingest + dispatch checks and returns the best next action; mode=ingest runs SDK ingest checks only; mode=dispatch runs fix-dispatch preflight only. Prefer this over setup_check, ingest_setup_check, or diagnose_connection alone.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Why is Mushi setup broken \u2014 one call, clear next step."
+  },
   {
     name: "diagnose_connection",
     title: "Connection diagnose (CLI + MCP + SDK)",
-    description: `Validate the MCP server credentials (endpoint, API key, projectId), ping /health, run ingest-setup and dispatch preflight, and return the single best next action when anything fails. Use when the user asks "why aren't my reports showing up?".`,
+    description: `Validate MCP credentials, ping /health, run ingest-setup and dispatch preflight, return the single best next action. For mode-specific checks prefer diagnose_setup. Use when the user asks "why aren't my reports showing up?".`,
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Why is my Mushi setup broken \u2014 what exact step should I fix next?"
   },
+  {
+    name: "search_mushi_docs",
+    title: "Search Mushi documentation",
+    description: "Search official Mushi docs (guides, MCP setup, inventory, QA, skills) by keyword. Returns ranked page titles, URLs, and excerpts \u2014 use before guessing API shapes or RPC names.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: false },
+    useCase: "How do I configure MCP scopes / dispatch a fix / wire QA stories?"
+  },
   // --- Write / agentic ----------------------------------------------------
   {
     name: "submit_fix_result",
@@ -265,11 +281,19 @@ var TOOL_CATALOG = [
   {
     name: "list_projects",
     title: "List accessible projects",
-    description: "List the Mushi projects accessible to this API key. For project-scoped keys (the typical case), returns a single-item list with the bound project's id, name, slug, plan tier, and ingest status. For org-level tokens, returns all projects in the org. Use this when MUSHI_PROJECT_ID is not configured \u2014 call list_projects first, then pass the id to other tools.",
+    description: `List the Mushi projects accessible to this API key. For project-scoped keys (the typical case), returns a single-item list with the bound project's id, name, created_at. Use this when MUSHI_PROJECT_ID is not configured \u2014 call list_projects first, then pass the id to other tools. Multi-project note: each Mushi project uses its own API key. To connect multiple projects, run "Add to Cursor" in the Mushi console for each project \u2014 each deeplink creates a uniquely-named MCP server entry (mushi-{slug}-{id}). You can then call list_projects on each named server to confirm which project it serves.`,
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Which projects can I access with this API key?"
   },
+  {
+    name: "get_account_overview",
+    title: "Account overview \u2014 all projects",
+    description: "Return a summary of every Mushi project accessible to this API key, including report counts, SDK heartbeat status, and the last ingest timestamp for each. For project-scoped keys this is a one-item list; for future org-level keys it lists every project. Also includes a hint explaining how to connect additional projects to your IDE. Call this at the start of a multi-repo or multi-app triage session to orient yourself.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Show me all my Mushi projects and their health at a glance."
+  },
   {
     name: "get_project_context",
     title: "Project context snapshot",
@@ -477,7 +501,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "get_activation_status",
     title: "Activation cockpit status",
-    description: "Unified setup posture for the active project: required steps, SDK heartbeat, dispatch preflight, and the next best action. Use this first when the user says setup is broken or they cannot connect.",
+    description: "[Deprecated \u2014 use activation_status resource or tool on hosted MCP.] Unified setup posture for the active project: required steps, SDK heartbeat, dispatch preflight, and the next best action.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What is blocking this project from going live?"
@@ -485,7 +509,7 @@ var TDD_TOOL_CATALOG = [
   {
     name: "get_reporter_thread",
     title: "Reporter feedback thread",
-    description: "Fetch the unified timeline for a report \u2014 the reporter/admin comment thread (including verify/reopen signals) plus fix, QA, and status lanes. Use when triaging whether an end user still sees a bug as unfixed.",
+    description: "[Deprecated \u2014 use get_report_timeline instead.] Fetch the unified timeline for a report \u2014 reporter comments plus fix, QA, and status lanes.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What did the reporter say after we marked this fixed?"
@@ -508,10 +532,307 @@ var TDD_TOOL_CATALOG = [
     useCase: "Are there any tables without RLS? Show me recent backend errors for this project."
   }
 ];
+var CODEBASE_TOOL_CATALOG = [
+  {
+    name: "ask_codebase",
+    title: "Ask about the indexed codebase",
+    description: "Ask a plain-English question about the connected repo. Grounds on pgvector retrieval over project_codebase_files and returns an answer with file:line citations. Requires codebase indexing enabled and an Anthropic or OpenAI BYOK key.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    useCase: "How does authentication work in this repo?"
+  },
+  {
+    name: "get_file_summary",
+    title: "Plain-English file summary",
+    description: "Lazy-generate (or return cached) plain-English summary for an indexed file or symbol. Cache invalidates when content_hash changes after re-index.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Explain what lib/auth.ts does in plain English."
+  },
+  {
+    name: "get_codebase_tour",
+    title: "Guided codebase tour",
+    description: "Return a dependency-ordered guided tour (~6\u201310 stops) for onboarding \u2014 each stop lists node ids, file paths, layer, and rationale. Cached per index fingerprint.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Give me an onboarding walkthrough of this codebase."
+  },
+  {
+    name: "search_codebase",
+    title: "Semantic codebase search",
+    description: "Search indexed files by plain-English meaning via embeddings. Returns top-k file chunks with similarity scores.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Find files related to authentication or payment handling."
+  },
+  {
+    name: "get_codebase_domains",
+    title: "Business domain map",
+    description: "Extract business domains, flows, and steps mapped to file paths. Cached per index fingerprint.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What business domains does this codebase implement?"
+  },
+  {
+    name: "analyze_codebase_impact",
+    title: "Diff impact analysis",
+    description: "Find files that depend on changed paths (reverse import graph). Supports manual paths, last push, GitHub compare, or fix PR files.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What breaks if I change lib/auth.ts?"
+  },
+  {
+    name: "analyze_wiki_knowledge",
+    title: "Wiki knowledge graph",
+    description: "Return wiki/docs knowledge graph nodes and sources for the project. Use include_wiki on ask_codebase for RAG merge.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What docs entities exist for onboarding?"
+  }
+];
+
+// src/feature-groups.ts
+var FEATURE_GROUPS = [
+  "triage",
+  "fixes",
+  "inventory",
+  "setup",
+  "qa",
+  "skills",
+  "rewards",
+  "admin",
+  "audit",
+  "docs",
+  /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
+  "legacy"
+];
+var ALL_FEATURE_GROUPS = FEATURE_GROUPS.filter(
+  (g) => g !== "legacy"
+);
+var TOOL_FEATURE_MAP = {
+  // triage
+  get_recent_reports: "triage",
+  get_report_detail: "triage",
+  get_report_timeline: "triage",
+  search_reports: "triage",
+  get_similar_bugs: "triage",
+  get_fix_context: "triage",
+  get_fix_timeline: "triage",
+  get_blast_radius: "triage",
+  get_knowledge_graph: "triage",
+  run_nl_query: "triage",
+  get_report_evidence: "triage",
+  triage_issue: "triage",
+  query_lessons: "triage",
+  list_lessons: "triage",
+  fix_suggest: "triage",
+  graph_neighborhood: "triage",
+  graph_node_status: "triage",
+  get_reporter_thread: "legacy",
+  // inventory
+  inventory_get: "inventory",
+  inventory_diff: "inventory",
+  inventory_findings: "inventory",
+  inventory_current: "admin",
+  // setup
+  diagnose_connection: "setup",
+  diagnose_setup: "setup",
+  setup_check: "legacy",
+  ingest_setup_check: "legacy",
+  get_activation_status: "legacy",
+  activation_status: "setup",
+  project_integration_health: "setup",
+  setup_repo_for_mushi: "setup",
+  get_two_way_comms_health: "setup",
+  // fixes
+  submit_fix_result: "fixes",
+  dispatch_fix: "fixes",
+  trigger_judge: "fixes",
+  test_gen_from_report: "fixes",
+  transition_status: "fixes",
+  merge_fix: "fixes",
+  refresh_ci: "fixes",
+  reopen_report: "fixes",
+  reply_to_reporter: "fixes",
+  // rewards
+  list_top_contributors: "rewards",
+  award_bonus_points: "rewards",
+  set_tier: "rewards",
+  // admin / project context
+  list_projects: "admin",
+  get_account_overview: "admin",
+  get_project_context: "admin",
+  get_pipeline_logs: "admin",
+  project_dashboard: "admin",
+  project_stats: "admin",
+  project_settings: "admin",
+  privacy_status: "admin",
+  evolution_history: "admin",
+  // qa / tdd
+  map_user_stories: "qa",
+  get_map_run_status: "qa",
+  generate_tdd_from_story: "qa",
+  improve_qa_story: "qa",
+  run_qa_story: "qa",
+  list_pending_review_stories: "qa",
+  approve_qa_story: "qa",
+  list_qa_story_runs: "qa",
+  get_qa_story_run: "qa",
+  test_notification_channel: "qa",
+  // skills
+  list_skills: "skills",
+  get_skill: "skills",
+  start_skill_pipeline: "skills",
+  get_pipeline_run: "skills",
+  checkin_pipeline_step: "skills",
+  list_byok_keys: "skills",
+  add_byok_key: "skills",
+  // audit
+  run_fullstack_audit: "audit",
+  get_backend_health: "audit",
+  // docs
+  search_mushi_docs: "docs"
+};
+function parseFeaturesParam(raw) {
+  if (raw == null || raw.trim() === "") return "all";
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "all" || normalized === "*") return "all";
+  const groups = normalized.split(",").map((s) => s.trim()).filter(Boolean);
+  const valid = groups.filter((g) => FEATURE_GROUPS.includes(g));
+  if (valid.length === 0) return "all";
+  return valid;
+}
+function parseFeaturesCsv(raw) {
+  if (!raw?.trim()) return "all";
+  return parseFeaturesParam(raw);
+}
+function toolMatchesFeatures(toolName, filter) {
+  if (filter === "all") return true;
+  const group = TOOL_FEATURE_MAP[toolName];
+  if (!group) return true;
+  if (group === "legacy") {
+    return filter.includes("legacy");
+  }
+  return filter.includes(group);
+}
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { createLogger } from "@mushi-mushi/core";
+
+// src/branding.ts
+var MUSHI_WEBSITE_URL = "https://kensaur.us/mushi-mushi";
+var MUSHI_ICON_PNG_URL = `${MUSHI_WEBSITE_URL}/integrations/mushi-mark-512.png`;
+var MUSHI_ICON_SVG_URL = `${MUSHI_WEBSITE_URL}/favicon.svg`;
+var MUSHI_SERVER_ICONS = [
+  { src: MUSHI_ICON_PNG_URL, mimeType: "image/png", sizes: ["512x512"] },
+  { src: MUSHI_ICON_SVG_URL, mimeType: "image/svg+xml", sizes: ["any"] }
+];
+var MUSHI_SERVER_METADATA = {
+  name: "mushi-mushi",
+  title: "Mushi Mushi",
+  description: "User-felt bug triage, fix dispatch, QA stories, and inventory spec traceability for AI coding agents.",
+  websiteUrl: MUSHI_WEBSITE_URL,
+  icons: MUSHI_SERVER_ICONS
+};
+
+// 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"],
+    excerpt: "Wire Mushi MCP into Cursor, Claude, or any MCP client."
+  },
+  {
+    title: "API key scopes",
+    path: `${BASE}/guides/api-keys`,
+    keywords: ["api key", "mcp:read", "mcp:write", "scopes", "security"],
+    excerpt: "Separate SDK ingest keys from MCP read/write keys."
+  },
+  {
+    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}`);
@@ -525,10 +846,22 @@ 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"
+  });
   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: {
@@ -538,10 +871,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) {
@@ -555,6 +890,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;
@@ -562,10 +898,13 @@ 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;
   }
   function jsonText(value) {
@@ -580,10 +919,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`);
@@ -616,7 +958,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()),
@@ -629,7 +974,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 = args.project_id ?? projectId;
+      const extraHeaders = pid && pid !== projectId ? { "X-Mushi-Project-Id": pid } : {};
+      const data = await apiCall(`/v1/admin/reports?${params}`, {
+        headers: extraHeaders
+      });
       return jsonResult(data);
     }
   );
@@ -639,9 +988,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",
@@ -700,6 +1059,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) => {
@@ -712,7 +1074,7 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -721,11 +1083,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,
@@ -963,13 +1332,114 @@ 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(),
+        issues: z.array(z.unknown()),
+        nextAction: z.string(),
+        summary: z.string()
+      }
     },
     async () => {
       const issues = [];
@@ -1053,7 +1523,7 @@ 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,
@@ -1066,17 +1536,77 @@ function createMushiServer(config) {
       });
     }
   );
+  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()),
+        active_project_id: z.string().nullable(),
+        multi_project_hint: z.string()
+      }
+    },
+    async () => {
+      const data = await apiCall("/v1/admin/mcp/projects");
+      const projects = Array.isArray(data?.projects) ? data.projects : [];
+      return jsonResult({
+        projects,
+        active_project_id: projectId ?? null,
+        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(
@@ -1176,6 +1706,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) => {
@@ -1219,7 +1763,7 @@ function createMushiServer(config) {
           args: { reportId: args.report_id }
         });
       }
-      return jsonText({
+      const result = {
         report_id: args.report_id,
         severity,
         category,
@@ -1232,7 +1776,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(
@@ -1613,7 +2165,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)
       }]
     })
   );
@@ -1627,7 +2179,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" })
       }]
     })
   );
@@ -2206,12 +2762,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();
       }
     }
@@ -2222,13 +2958,14 @@ Be specific. No generic advice.`
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var VERSION = require2("../package.json").version;
-var log = createLogger({ scope: "mushi:mcp", level: "info" });
+var log = createLogger2({ scope: "mushi:mcp", level: "info" });
 var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "";
 var API_KEY = process.env.MUSHI_API_KEY ?? "";
 var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
 var SCOPES_RAW = process.env.MUSHI_SCOPES ?? "";
 var parsedScopes = SCOPES_RAW ? SCOPES_RAW.split(",").map((s) => s.trim()).filter((s) => s === "mcp:read" || s === "mcp:write") : ALL_SCOPES;
 var SCOPES = SCOPES_RAW && parsedScopes.length === 0 ? ALL_SCOPES : parsedScopes;
+var FEATURES = parseFeaturesCsv(process.env.MUSHI_FEATURES);
 async function main() {
   if (!API_KEY) {
     log.fatal("MUSHI_API_KEY environment variable is required");
@@ -2255,7 +2992,8 @@ async function main() {
     apiEndpoint: API_ENDPOINT,
     apiKey: API_KEY,
     projectId: PROJECT_ID || void 0,
-    scopes: SCOPES
+    scopes: SCOPES,
+    features: FEATURES
   });
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -2267,7 +3005,7 @@ async function main() {
         const res = await fetch(`${API_ENDPOINT}/v1/admin/inventory/${PROJECT_ID}`, {
           headers: {
             "X-Mushi-Api-Key": API_KEY,
-            "X-Mushi-Project": PROJECT_ID
+            "X-Mushi-Project-Id": PROJECT_ID
           },
           signal: AbortSignal.timeout(1e4)
         });