@mushi-mushi/mcp 0.14.1 → 0.15.0

package/README.md

@@ -18,6 +18,20 @@ npx mushi-mushi setup --ide cursor
 
 That command reads `~/.mushirc`, writes `.cursor/mcp.json` with the `mushi` server block, and prints "Done — restart Cursor and ask: `list mushi tools`". No copy-pasting environment variables.
 
+### Codebase Understand tools (indexed repos)
+
+When codebase indexing is enabled on a project, these MCP tools ground on `project_codebase_files` (+ wiki chunks when configured):
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `ask_codebase` | write | Plain-English Q&A with file:line citations |
+| `get_file_summary` | read | Lazy plain-English file/symbol summary |
+| `get_codebase_tour` | read | Dependency-ordered onboarding tour |
+| `search_codebase` | read | Semantic (or scoped) embedding search |
+| `get_codebase_domains` | read | Business domain / flow map |
+| `analyze_codebase_impact` | read | Diff impact (paths, last push, compare, fix PR) |
+| `analyze_wiki_knowledge` | read | Wiki/docs knowledge graph |
+
 > **What this is, and what it isn't**
 >
 > - **This package** (`@mushi-mushi/mcp`) is the MCP **server** — runs locally next to your editor, talks to the Mushi API, and presents bug reports as MCP tools/resources to your coding agent. Always install it by its scoped name (`npx -y @mushi-mushi/mcp@latest`) — the bare `mushi-mcp` name was never published to npm.
@@ -26,7 +40,19 @@ That command reads `~/.mushirc`, writes `.cursor/mcp.json` with the `mushi` serv
 
 ## Quick start
 
-### 0. One-liner (recommended)
+### 0. One-click (fastest) — "Add to Cursor" deeplink
+
+The Mushi admin console (**Admin → MCP → Setup tab**) generates a one-click deeplink that opens Cursor's "Install MCP server?" dialog with your project ID and a freshly-minted `mcp:write` key already embedded:
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=mushi-<project>&config=<base64>
+```
+
+Click **"⚡ Add to Cursor"** (or **"Add to VS Code"**) — Cursor prompts you to confirm, then writes the server block into your global `mcp.json` automatically. No copy-pasting.
+
+> **Security note:** The deeplink mints a dedicated `mcp:write` key (or `mcp:read` for read-only), separate from your app's SDK key. Your SDK key (the `report:write`-scoped key your app sends bug reports with) should never carry `mcp:write` — it would expose admin-level triage and fix dispatch to anyone who extracted it from your browser bundle. The deeplink mint enforces this separation automatically. See [API key scopes](#api-key-scopes) below.
+
+### 1. One-liner CLI (recommended for first-time setup)
 
 ```bash
 # First: make sure you've logged in
@@ -38,7 +64,7 @@ npx mushi-mushi setup --ide claude          # Claude Code / Claude Desktop
 npx mushi-mushi setup --ide cursor --with-rules  # also write .cursorrules
 ```
 
-### 1. With Claude Desktop (manual)
+### 2. With Claude Desktop (manual)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
@@ -67,7 +93,7 @@ Restart Claude Desktop. You should see a hammer icon in the chat input — click
 >
 > Or visit **Admin → MCP** in the console for a one-click pre-filled config snippet.
 
-### 2. With Cursor
+### 3. With Cursor (manual)
 
 In Cursor settings, open **MCP** → **Add new MCP server** and paste:
 
@@ -85,7 +111,7 @@ Then set the same three environment variables:
 
 Without `MUSHI_PROJECT_ID` the server starts but scoped tools return an empty result with a message pointing you here.
 
-### 3. From the command line
+### 4. From the command line
 
 ```bash
 MUSHI_API_KEY=mushi_xxxxxxxxxxxxxxxxxxxx \
@@ -95,25 +121,57 @@ npx -y @mushi-mushi/mcp@latest
 
 The server speaks stdio MCP transport by default — your client launches it as a subprocess.
 
-### 4. Hosted Streamable HTTP (no subprocess) — 2026-05-09 release
+### 5. Hosted Streamable HTTP (no subprocess) — 2026-05-09 release
 
 The Mushi backend now exposes the same tool catalog over the **Streamable HTTP** transport from the MCP 2025-03-26 spec at `/functions/v1/mcp`. Use this when you want to skip the local subprocess — typical for OpenAI Agents SDK, ChatGPT Agent, hosted CrewAI, or any orchestrator that talks remote MCP:
 
 ```jsonc
-// .cursor/mcp.json — example
+// .cursor/mcp.json — example (hosted HTTP)
 {
   "mcpServers": {
     "mushi-mushi-hosted": {
+      "type": "http",
       "url": "https://<your-ref>.supabase.co/functions/v1/mcp",
       "headers": {
+        "Authorization": "Bearer mushi_xxxxxxxxxxxxxxxxxxxx",
         "X-Mushi-Api-Key": "mushi_xxxxxxxxxxxxxxxxxxxx",
-        "X-Mushi-Project": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+        "X-Mushi-Project-Id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       }
     }
   }
 }
 ```
 
+> **Cursor icon:** HTTP MCP URLs on `*.supabase.co` often show the **Supabase favicon** in Cursor settings — not a Mushi bug. Use **stdio** (`command` + `npx @mushi-mushi/mcp`) for the red 虫 stamp, or set `"icon": "https://kensaur.us/mushi-mushi/integrations/mushi-mark-512.png"` in your server block. The hosted endpoint also emits MCP `serverInfo.icons` and serves inline SVG at `?icon=1`.
+
+### Feature groups (`?features=` / `MUSHI_FEATURES`)
+
+Full catalog is **72 tools** (64 core + 8 project-context tools). New installs default to a lean set via:
+
+- **Stdio:** `MUSHI_FEATURES=triage,fixes,inventory,setup,docs`
+- **HTTP:** `?features=triage,fixes,inventory,setup,docs` on the MCP URL
+
+Append `legacy` to keep deprecated aliases (`setup_check`, `ingest_setup_check`, …). Use `features=all` for the full catalog.
+
+New unified tools: `diagnose_setup` (replaces setup trilogy), `search_mushi_docs` (keyword doc search).
+
+Append `?read_only=1` to the URL to hide write tools (Supabase-parity mode).
+
+## Cursor config hygiene
+
+1. **One global MCP config** — keep `mushi` in `~/.cursor/mcp.json` only. Do **not** duplicate `mushi` / `mushi-stdio` in per-project `.cursor/mcp.json` (prevents connection storms). Project repos may ship `{}` or a comment pointing to the global file.
+2. **Windows paths** — use forward slashes in JSON (`C:/Users/...`) or escaped backslashes (`C:\\Users\\...`). Raw `\f`, `\n`, `\t` in paths corrupt JSON.
+3. **Multi-project** — either one HTTP server per project (distinct server name + `X-Mushi-Project-Id`) or one stdio server and pass `project_id` on each tool call.
+4. **After editing global config** — fully restart Cursor (MCP panel must reload).
+
+| Header | Role |
+|--------|------|
+| `Authorization: Bearer <key>` | Auth (optional duplicate of API key) |
+| `X-Mushi-Api-Key` | Auth (preferred for MCP clients) |
+| `X-Mushi-Project-Id` | **Project scope** — required for API-key callers |
+
+~~`X-Mushi-Project`~~ is deprecated for project UUID (collision with legacy slug header).
+
 The endpoint accepts JSON-RPC 2.0 over POST (returns `application/json` or `text/event-stream` per content negotiation), opens an SSE stream on GET for server-pushed notifications, and accepts DELETE for session termination. Auth is the same dual-mode API-key / JWT used everywhere else on `/v1/admin/*`.
 
 ## Tools
@@ -267,6 +325,7 @@ Honest scorecard against the MCP 2025-10 spec:
 - ✅ **Stdio transport** — default for local editor integration.
 - ✅ **Streamable HTTP transport (2025-03-26 spec)** — hosted at `/functions/v1/mcp` on the Mushi backend; same tool catalog, no local subprocess. The previous "⏳" entry shipped in the 2026-05-09 release.
 - ✅ **Spec traceability for `dispatch_fix`** — the `dispatch_fix` tool input schema now accepts `inventoryActionNodeId`, and `get_fix_context` surfaces the inventory `Action` (with `expected_outcome`) the report was classified against. External orchestrators can read the contract before drafting a fix and pass the anchor back at dispatch time.
+- ✅ **Structured output (`outputSchema` + `structuredContent`)** — the four highest-value tools (`triage_issue`, `get_report_detail`, `get_similar_bugs`, `get_fix_context`) now declare a Zod-derived `outputSchema` and return `structuredContent` alongside the text envelope. Clients that support structured output (Cursor, Claude Desktop) can bind the typed result directly; others fall back to the text content unchanged. Also adds `resource_links` on `triage_issue` pointing to the report and dashboard resources so clients can follow up without re-constructing URIs.
 - ⏳ **Resource subscriptions / `notifications/resources/list_changed`** — the spec supports live-updating resources (e.g. dashboard numbers that push rather than poll). Worth adding once Cursor + Claude Desktop both ship client support (currently patchy).
 - ⏳ **Sampling / elicitation** — letting the server ask the client to run an LLM call (e.g. to draft a commit message from the fix context). Not yet wired; would let us move some orchestrator LLM spend from server-side to the user's own subscription.
 
@@ -287,7 +346,8 @@ The page is the recommended first stop for a new team member — it takes about
 
 - The server runs locally; your API key never leaves your machine except in calls to your configured `MUSHI_API_ENDPOINT`.
 - **Scope keys tightly.** Give MCP the smallest scope that works — `mcp:read` is fine for 90% of agent loops.
-- Never paste a service-role key or a `report:write` SDK key — the former bypasses RLS, the latter is rejected by admin routes anyway.
+- **Keep your SDK key (`report:write`) separate from your MCP key.** Your app's Mushi SDK key is embedded in client-side code (e.g. `NEXT_PUBLIC_MUSHI_API_KEY`) and should carry only `report:write` scope. This scope is intentionally rejected by every admin route — so even if extracted from a browser bundle, it cannot triage, dispatch fixes, or mutate report status. Mint a dedicated `mcp:write` key for Cursor/Claude (use the **"⚡ Add to Cursor"** deeplink on the `/mcp` console page — it mints one automatically). If you discover your public SDK key carries `mcp:write`, rotate it immediately.
+- Never paste a service-role key — it bypasses RLS on every table.
 - Rotate keys from the admin console if a laptop is lost — the denormalised owner binding is rebuilt automatically on rotation.
 - The server logs to stderr; redirect to a file if you need an audit trail.
 
@@ -301,7 +361,7 @@ Real `Client ↔ Server` handshake over `InMemoryTransport` with a mocked `fetch
 
 ```bash
 pnpm --filter @mushi-mushi/mcp test
-# 18/18 pass — handshake, tool contracts, envelope unwrapping, scope errors, annotation contract
+# 49/49 pass — handshake, tool contracts, envelope unwrapping, scope errors, annotation contract, outputSchema, catalog parity
 ```
 
 ### Layer 2 — Stdio smoke test (verifies the built bin boots)
@@ -404,4 +464,4 @@ MIT
 <!-- mushi-readme-stats-footer -->
 ---
 
-<sub>Monorepo scale (June 2026): 43 edge functions · 234 SQL migrations · 13 outbound plugins · 11 inbound adapters. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>
+<sub>Monorepo scale (June 2026): 47 edge functions · 256 SQL migrations · 13 outbound plugins · 11 inbound adapters · 18 pipeline agents. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>

package/dist/branding.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical MCP server branding — icons, title, website.
+ * Used by stdio + hosted HTTP initialize payloads (MCP 2025-11 icons spec).
+ *
+ * Cursor often shows the favicon of the HTTP URL host (e.g. supabase.co) when
+ * server icons are absent. Always emit `icons` + recommend stdio or our icon URL.
+ */
+/** Public marketing site — also hosts favicon.svg for the docs app. */
+declare const MUSHI_WEBSITE_URL = "https://kensaur.us/mushi-mushi";
+/** 512×512 stamp mark — safe PNG on CDN (Cursor requires png/jpeg reliably). */
+declare const MUSHI_ICON_PNG_URL = "https://kensaur.us/mushi-mushi/integrations/mushi-mark-512.png";
+/** SVG favicon from the docs app (scalable; some clients sanitize SVG). */
+declare const MUSHI_ICON_SVG_URL = "https://kensaur.us/mushi-mushi/favicon.svg";
+/** Hosted MCP icon route — same origin as the MCP endpoint when proxied. */
+declare function mcpIconUrl(mcpBaseUrl: string): string;
+interface McpIconDescriptor {
+    src: string;
+    mimeType?: string;
+    /** MCP spec expects an array of size strings, e.g. `["512x512"]`. */
+    sizes?: string[];
+}
+declare const MUSHI_SERVER_ICONS: McpIconDescriptor[];
+declare const MUSHI_SERVER_METADATA: {
+    readonly name: "mushi-mushi";
+    readonly title: "Mushi Mushi";
+    readonly description: "User-felt bug triage, fix dispatch, QA stories, and inventory spec traceability for AI coding agents.";
+    readonly websiteUrl: "https://kensaur.us/mushi-mushi";
+    readonly icons: McpIconDescriptor[];
+};
+
+export { MUSHI_ICON_PNG_URL, MUSHI_ICON_SVG_URL, MUSHI_SERVER_ICONS, MUSHI_SERVER_METADATA, MUSHI_WEBSITE_URL, type McpIconDescriptor, mcpIconUrl };

package/dist/branding.js

@@ -0,0 +1,16 @@
+import {
+  MUSHI_ICON_PNG_URL,
+  MUSHI_ICON_SVG_URL,
+  MUSHI_SERVER_ICONS,
+  MUSHI_SERVER_METADATA,
+  MUSHI_WEBSITE_URL,
+  mcpIconUrl
+} from "./chunk-EHB2BGWX.js";
+export {
+  MUSHI_ICON_PNG_URL,
+  MUSHI_ICON_SVG_URL,
+  MUSHI_SERVER_ICONS,
+  MUSHI_SERVER_METADATA,
+  MUSHI_WEBSITE_URL,
+  mcpIconUrl
+};

package/dist/catalog.d.ts

@@ -65,5 +65,6 @@ interface PromptSpec {
 }
 declare const PROMPT_CATALOG: PromptSpec[];
 declare const TDD_TOOL_CATALOG: ToolSpec[];
+declare const CODEBASE_TOOL_CATALOG: ToolSpec[];
 
-export { ALL_SCOPES, type McpScope, PROMPT_CATALOG, type PromptSpec, RESOURCE_CATALOG, type ResourceSpec, TDD_TOOL_CATALOG, TOOL_CATALOG, type ToolHints, type ToolSpec };
+export { ALL_SCOPES, CODEBASE_TOOL_CATALOG, type McpScope, PROMPT_CATALOG, type PromptSpec, RESOURCE_CATALOG, type ResourceSpec, TDD_TOOL_CATALOG, TOOL_CATALOG, type ToolHints, type ToolSpec };

package/dist/catalog.js

@@ -1,12 +1,14 @@
 import {
   ALL_SCOPES,
+  CODEBASE_TOOL_CATALOG,
   PROMPT_CATALOG,
   RESOURCE_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-FQ5WR3PS.js";
+} from "./chunk-FD6GVGQS.js";
 export {
   ALL_SCOPES,
+  CODEBASE_TOOL_CATALOG,
   PROMPT_CATALOG,
   RESOURCE_CATALOG,
   TDD_TOOL_CATALOG,

package/dist/chunk-B2QEG35D.js

@@ -0,0 +1,158 @@
+// 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 DEFAULT_FEATURE_GROUPS = [
+  "triage",
+  "fixes",
+  "inventory",
+  "setup",
+  "docs"
+];
+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"
+};
+var DEPRECATED_TOOL_ALIASES = {
+  setup_check: "diagnose_setup",
+  ingest_setup_check: "diagnose_setup",
+  get_activation_status: "activation_status",
+  get_reporter_thread: "get_report_timeline"
+};
+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);
+}
+function featuresQueryString(groups) {
+  return groups.join(",");
+}
+function appendFeaturesToUrl(baseUrl, groups) {
+  const url = new URL(baseUrl);
+  url.searchParams.set("features", featuresQueryString(groups));
+  return url.toString();
+}
+
+export {
+  FEATURE_GROUPS,
+  DEFAULT_FEATURE_GROUPS,
+  ALL_FEATURE_GROUPS,
+  TOOL_FEATURE_MAP,
+  DEPRECATED_TOOL_ALIASES,
+  parseFeaturesParam,
+  parseFeaturesCsv,
+  toolMatchesFeatures,
+  featuresQueryString,
+  appendFeaturesToUrl
+};

package/dist/chunk-EHB2BGWX.js

@@ -0,0 +1,28 @@
+// 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`;
+function mcpIconUrl(mcpBaseUrl) {
+  const base = mcpBaseUrl.replace(/\/+$/, "");
+  return `${base}?icon=1`;
+}
+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
+};
+
+export {
+  MUSHI_WEBSITE_URL,
+  MUSHI_ICON_PNG_URL,
+  MUSHI_ICON_SVG_URL,
+  mcpIconUrl,
+  MUSHI_SERVER_ICONS,
+  MUSHI_SERVER_METADATA
+};

package/dist/{chunk-FQ5WR3PS.js → chunk-FD6GVGQS.js}

@@ -134,7 +134,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?"
@@ -142,19 +142,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",
@@ -258,11 +274,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",
@@ -554,7 +578,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?"
@@ -562,7 +586,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?"
@@ -585,11 +609,70 @@ 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?"
+  }
+];
 
 export {
   ALL_SCOPES,
   TOOL_CATALOG,
   RESOURCE_CATALOG,
   PROMPT_CATALOG,
-  TDD_TOOL_CATALOG
+  TDD_TOOL_CATALOG,
+  CODEBASE_TOOL_CATALOG
 };

package/dist/feature-groups.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Feature groups for MCP tool filtering — mirrors Supabase MCP `?features=` pattern.
+ *
+ * When `features` is omitted → all tools (backward compatible).
+ * New installs default to DEFAULT_FEATURE_GROUPS via deeplink / docs.
+ */
+declare const FEATURE_GROUPS: readonly ["triage", "fixes", "inventory", "setup", "qa", "skills", "rewards", "admin", "audit", "docs", "legacy"];
+type FeatureGroup = (typeof FEATURE_GROUPS)[number];
+/** Lean default for new Cursor installs (~45 tools vs 70 full). */
+declare const DEFAULT_FEATURE_GROUPS: readonly FeatureGroup[];
+declare const ALL_FEATURE_GROUPS: readonly FeatureGroup[];
+/** Map every tool/resource name → feature group. */
+declare const TOOL_FEATURE_MAP: Record<string, FeatureGroup>;
+/** Tools superseded by another — still registered when legacy/all enabled. */
+declare const DEPRECATED_TOOL_ALIASES: Record<string, string>;
+type FeatureFilter = 'all' | readonly FeatureGroup[];
+declare function parseFeaturesParam(raw: string | null | undefined): FeatureFilter;
+declare function parseFeaturesCsv(raw: string | undefined): FeatureFilter;
+declare function toolMatchesFeatures(toolName: string, filter: FeatureFilter): boolean;
+declare function featuresQueryString(groups: readonly FeatureGroup[]): string;
+declare function appendFeaturesToUrl(baseUrl: string, groups: readonly FeatureGroup[]): string;
+
+export { ALL_FEATURE_GROUPS, DEFAULT_FEATURE_GROUPS, DEPRECATED_TOOL_ALIASES, FEATURE_GROUPS, type FeatureFilter, type FeatureGroup, TOOL_FEATURE_MAP, appendFeaturesToUrl, featuresQueryString, parseFeaturesCsv, parseFeaturesParam, toolMatchesFeatures };

package/dist/feature-groups.js

@@ -0,0 +1,24 @@
+import {
+  ALL_FEATURE_GROUPS,
+  DEFAULT_FEATURE_GROUPS,
+  DEPRECATED_TOOL_ALIASES,
+  FEATURE_GROUPS,
+  TOOL_FEATURE_MAP,
+  appendFeaturesToUrl,
+  featuresQueryString,
+  parseFeaturesCsv,
+  parseFeaturesParam,
+  toolMatchesFeatures
+} from "./chunk-B2QEG35D.js";
+export {
+  ALL_FEATURE_GROUPS,
+  DEFAULT_FEATURE_GROUPS,
+  DEPRECATED_TOOL_ALIASES,
+  FEATURE_GROUPS,
+  TOOL_FEATURE_MAP,
+  appendFeaturesToUrl,
+  featuresQueryString,
+  parseFeaturesCsv,
+  parseFeaturesParam,
+  toolMatchesFeatures
+};