@mushi-mushi/mcp 0.18.0 → 0.18.2

package/README.md

@@ -87,9 +87,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 Restart Claude Desktop. You should see a hammer icon in the chat input — click it to see the Mushi Mushi tools.
 
 > **Where do I find these values?**
-> - **`MUSHI_API_KEY`**: [Admin console](https://kensaur.us/mushi-mushi/settings) → **Settings → API Keys**
+> - **`MUSHI_API_KEY`**: [Admin → Connect](https://kensaur.us/mushi-mushi/admin/connect) or **MCP** setup — mint an `mcp:read` / `mcp:write` key. This is **not** the SDK ingest key from **Setup → Verify** (`report:write`) and **not** a BYOK key from **Settings → API Keys**.
 > - **`MUSHI_PROJECT_ID`**: [Admin console](https://kensaur.us/mushi-mushi/projects) → click your project → copy the UUID below the project name (e.g. `542b34e0-019e-41fe-b900-7b637717bb86`)
-> - **`MUSHI_API_ENDPOINT`**: [Admin console](https://kensaur.us/mushi-mushi/settings) → **Settings → API Keys** — shown alongside your key
+> - **`MUSHI_API_ENDPOINT`**: Shown when you mint the MCP key, or use your project's API base (`https://<ref>.supabase.co/functions/v1/api`)
 >
 > Or visit **Admin → MCP** in the console for a one-click pre-filled config snippet.
 
@@ -105,9 +105,9 @@ Then set the same three environment variables:
 
 | Variable | Where to find it |
 |---|---|
-| `MUSHI_API_KEY` | Admin console → Settings → API Keys |
+| `MUSHI_API_KEY` | **Connect** or **MCP** tab — mint `mcp:read` / `mcp:write` (not Setup → Verify ingest key; not Settings → BYOK) |
 | `MUSHI_PROJECT_ID` | Admin console → Projects → click project → UUID below the name |
-| `MUSHI_API_ENDPOINT` | Admin console → Settings → API Keys (shown alongside your key) |
+| `MUSHI_API_ENDPOINT` | Shown at key mint, or your Supabase `.../functions/v1/api` base |
 
 Without `MUSHI_PROJECT_ID` the server starts but scoped tools return an empty result with a message pointing you here.
 

package/dist/catalog.js

@@ -5,7 +5,7 @@ import {
   RESOURCE_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-KNVB6HA7.js";
+} from "./chunk-DSOPGMDX.js";
 export {
   ALL_SCOPES,
   CODEBASE_TOOL_CATALOG,

package/dist/{chunk-KNVB6HA7.js → chunk-DSOPGMDX.js}

@@ -68,7 +68,7 @@ var TOOL_CATALOG = [
   {
     name: "get_knowledge_graph",
     title: "Knowledge graph traversal",
-    description: "Traverse the knowledge graph from a seed component or page. Returns { nodes: [{ id, label, type }], edges } within a depth budget (default 2, max 4 hops). Read-only. Use to see how a component connects to the rest of the app; use get_blast_radius for a bug's impact area, or get_graph_neighborhood for a tighter BFS around one node.",
+    description: "Traverse the knowledge graph from a seed component or page. Returns { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4 hops). Read-only. Use to see how a component connects to the rest of the app; use get_blast_radius for a bug's impact area, or get_graph_neighborhood for a tighter BFS around one node.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me how this component connects to the rest of the app."
@@ -101,7 +101,7 @@ var TOOL_CATALOG = [
   {
     name: "list_gate_findings",
     title: "Gate findings",
-    description: 'List the most recent inventory gate findings for a project, newest run first. Returns rows of { gate, severity, status, message, node_ref }; "latest" = the most recent run per gate by created_at. Filter by gate (dead-handler | mock-leak | crawl | status-claim) or minimum severity (low|medium|high|critical). Read-only. Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot.',
+    description: "List recent inventory gate runs and their findings for a project, newest first. Returns { runs: [{ id, gate, status, findings_count, \u2026 }], findings: [{ severity, rule_id, message, file_path, node_id, \u2026 }] }. Filter by gate (dead-handler | mock-leak | crawl | status-claim) or minimum severity (low|medium|high|critical). Read-only. Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me what CI gates failed on the last run."
@@ -109,7 +109,7 @@ var TOOL_CATALOG = [
   {
     name: "get_graph_neighborhood",
     title: "Graph neighborhood",
-    description: `Return the BFS neighborhood around one graph node by id or label: { nodes: [{ id, label, type }], edges } within a depth budget (default 2, max 4). Read-only. Tuned for "what touches this action?"; use get_knowledge_graph to traverse from a component seed, or get_graph_node for a single node's row.`,
+    description: `Return the BFS neighborhood around one graph node by id or label: { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4). Read-only. Tuned for "what touches this action?"; use get_knowledge_graph to traverse from a component seed, or get_graph_node for a single node's row.`,
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What nodes connect to this inventory Action within 2 hops?"
@@ -117,7 +117,7 @@ var TOOL_CATALOG = [
   {
     name: "get_graph_node",
     title: "Graph node detail",
-    description: "Fetch one knowledge-graph node row by id: { id, label, type, metadata } including the v2 derived status on Action nodes (ok | stale | broken). Read-only. Use to inspect a single node's status; use get_graph_neighborhood to see what connects to it.",
+    description: "Fetch one knowledge-graph node row by id. Returns { node: { id, node_type, label, metadata } } including the v2 derived status on Action nodes (ok | stale | broken). Read-only. Use to inspect a single node's status; use get_graph_neighborhood to see what connects to it.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What status does the graph store on this node id?"
@@ -168,7 +168,7 @@ var TOOL_CATALOG = [
   {
     name: "trigger_judge",
     title: "Run Sonnet-as-Judge",
-    description: "Queue the Sonnet-as-Judge to grade the quality of recent fixes across a batch of classified reports. Returns { batchId }; graded scores land asynchronously in the judge_results table (read them back with run_nl_query). Write; consumes LLM budget. Idempotent within a short window \u2014 re-running for the same batch re-grades rather than duplicating. Use before shipping to vet fix quality; use get_fix_timeline to inspect a single attempt instead.",
+    description: "Queue the Sonnet-as-Judge to grade recent fix quality across accessible projects. Returns { dispatched: number } \u2014 one judge-batch job per project; scores land asynchronously in judge_results (read back with run_nl_query). Write; consumes LLM budget. Idempotent within a short window. Use before shipping to vet fix quality; use get_fix_timeline to inspect a single attempt instead.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Grade the latest batch of fixes before I ship."
@@ -192,7 +192,7 @@ var TOOL_CATALOG = [
   {
     name: "merge_fix",
     title: "Merge fix PR",
-    description: "Squash-merge the GitHub PR for a fix attempt, mark the linked report fixed, and notify the reporter. Re-readies the PR first if it is still a draft. Returns { merged, reportStatus }. Write; destructive (mutates the target repo's default branch); idempotent \u2014 re-running an already-merged attempt is a safe no-op. Prerequisite: CI green (check with refresh_ci). Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging.",
+    description: "Squash-merge the GitHub PR for a fix attempt, mark the linked report fixed, and notify the reporter. Re-readies the PR first if it is still a draft. Returns { merged, reportStatus }. Write; destructive and irreversible from Mushi's side \u2014 once GitHub merges into the target repo's default branch there is no unmerge endpoint, only a manual revert PR outside this tool. Idempotent \u2014 re-running an already-merged attempt is a safe no-op. Prerequisite: CI green (check with refresh_ci); confirm the diff and CI status with the user before calling on a PR you have not reviewed. Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Merge the draft PR and notify the reporter."
@@ -200,9 +200,9 @@ var TOOL_CATALOG = [
   {
     name: "refresh_ci",
     title: "Refresh fix CI status",
-    description: "Re-poll GitHub for the latest check-run status of a fix attempt's PR and persist it. Returns { ciStatus: pending|success|failure|neutral, checks: [{ name, conclusion }] }. Read-only (mutates nothing on GitHub). Use right before merge_fix to confirm CI is green; use get_fix_timeline for the full attempt lifecycle.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
+    description: "Re-poll GitHub for the latest check-run status of a fix attempt's PR and persist it on the fix_attempt row (does not merge or mutate GitHub). Returns { check_run_status, check_run_conclusion, check_run_updated_at }. Write; idempotent. Use right before merge_fix to confirm CI is green; use get_fix_timeline for the full attempt lifecycle.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Check whether CI is green before merging."
   },
   {
@@ -225,17 +225,17 @@ var TOOL_CATALOG = [
   {
     name: "award_bonus_points",
     title: "Award bonus points",
-    description: "Award ad-hoc bonus points to a contributor by their external user id (as passed to Mushi.identify()). Points are applied server-side, audit-logged, and trigger tier re-evaluation. Requires mcp:write scope. Use this to thank a contributor who found a critical bug or to run a one-off promotional campaign.",
+    description: "Award ad-hoc bonus points (1-50000, positive only \u2014 there is no way to subtract via this tool) to a contributor by their external user id (as passed to Mushi.identify()). Points post immediately to their total and are audit-logged as bonus_manual. Destructive and effectively irreversible: there is no reversal endpoint, so confirm the amount and recipient with the user before calling. Tier re-evaluation (and any host-side reward_webhooks grant tied to crossing a threshold) is NOT immediate \u2014 it only runs on the contributor's next tracked activity, not on this call. Requires mcp:write scope. Use this to thank a contributor who found a critical bug or to run a one-off promotional campaign.",
     scope: "mcp:write",
-    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    hints: { readOnly: false, destructive: true, idempotent: false, openWorld: true },
     useCase: "Give this contributor 500 bonus points for the critical bug they found."
   },
   {
     name: "set_tier",
     title: "Override contributor tier",
-    description: `Override a contributor's tier by tier slug (e.g. "champion"). This is an admin escape hatch for manual promotions \u2014 normal tier transitions happen automatically via point thresholds. The override is logged in end_user_activity with action=tier_override_manual. Requires mcp:write scope.`,
+    description: `Override a contributor's tier by tier slug (e.g. "champion"), bypassing the normal points-threshold logic entirely. This is an admin escape hatch for manual promotions \u2014 normal tier transitions happen automatically via point thresholds instead. Destructive: it is a label-only override that does NOT replay the automatic tier-evaluation path, so any host_credit_payload grant (Stripe perk, badge, etc.) normally tied to reaching that tier via points will NOT fire \u2014 confirm with the user whether they also need the perk granted another way. The override persists until another set_tier call changes it; the prior override stays in the end_user_activity audit trail either way, logged as tier_override_manual. Requires mcp:write scope.`,
     scope: "mcp:write",
-    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Manually promote this user to Champion tier as a thank-you."
   },
   {
@@ -307,7 +307,7 @@ var TOOL_CATALOG = [
   {
     name: "list_lessons",
     title: "List project lessons",
-    description: 'List the promoted learning rules ("lessons") for the current project, newest first. Each lesson is a named pattern of mistakes encoded from past bug reports. Returns { lessons: [{ id, title, rule, severity, source_report_ids }] }. Read-only. Use to see the full catalog of encoded heuristics; use query_lessons to retrieve only the lessons relevant to a specific diff or PR within a token budget.',
+    description: 'List promoted learning rules ("lessons") for the current project, highest-frequency first. Returns { lessons: [{ id, rule_text, severity, frequency, anti_pattern, \u2026 }] }. Read-only. Use to browse the full catalog of encoded heuristics; use query_lessons to retrieve only lessons relevant to a specific diff or PR within a token budget.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What systemic patterns has Mushi identified for this project?"
@@ -614,7 +614,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "search_codebase",
     title: "Semantic codebase search",
-    description: 'Search the indexed repo by plain-English meaning via embeddings. Returns top-k { results: [{ path, startLine, endLine, snippet, similarity }] } ordered by similarity. Requires codebase indexing enabled. Read-only. Use to locate where something lives ("where do we verify webhooks?"); use ask_codebase for a synthesized answer with citations, or analyze_codebase_impact to find dependents of a file.',
+    description: 'Search the indexed repo by plain-English meaning via embeddings. Returns { results: [{ file_path, line_start, line_end, content_preview, similarity, \u2026 }], query, mode } ordered by similarity. Requires codebase indexing enabled. Read-only. Use to locate where something lives ("where do we verify webhooks?"); use ask_codebase for a synthesized answer with citations, or analyze_codebase_impact to find dependents of a file.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Find files related to authentication or payment handling."
@@ -630,7 +630,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "analyze_codebase_impact",
     title: "Diff impact analysis",
-    description: "Find the files that depend on a set of changed paths by walking the reverse import graph. Source the paths from: manual list, the last push, a GitHub compare range, or a fix PR's files. Returns { impacted: [{ path, importedBy }], depth }. Requires codebase indexing. Read-only. Use to gauge a diff's blast radius before merging; use get_blast_radius for a bug's component impact, or search_codebase to locate files.",
+    description: "Find files that depend on a set of changed paths by walking the reverse import graph. Source paths from: manual list, last push, a GitHub compare range, or a fix PR's files. Returns { changed_paths, source, affected_file_paths, affected_node_ids, meta }. Requires codebase indexing. Read-only. Use to gauge a diff's blast radius before merging; use get_blast_radius for a bug's component impact, or search_codebase to locate files.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What breaks if I change lib/auth.ts?"

package/dist/index.js

@@ -75,7 +75,7 @@ var TOOL_CATALOG = [
   {
     name: "get_knowledge_graph",
     title: "Knowledge graph traversal",
-    description: "Traverse the knowledge graph from a seed component or page. Returns { nodes: [{ id, label, type }], edges } within a depth budget (default 2, max 4 hops). Read-only. Use to see how a component connects to the rest of the app; use get_blast_radius for a bug's impact area, or get_graph_neighborhood for a tighter BFS around one node.",
+    description: "Traverse the knowledge graph from a seed component or page. Returns { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4 hops). Read-only. Use to see how a component connects to the rest of the app; use get_blast_radius for a bug's impact area, or get_graph_neighborhood for a tighter BFS around one node.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me how this component connects to the rest of the app."
@@ -108,7 +108,7 @@ var TOOL_CATALOG = [
   {
     name: "list_gate_findings",
     title: "Gate findings",
-    description: 'List the most recent inventory gate findings for a project, newest run first. Returns rows of { gate, severity, status, message, node_ref }; "latest" = the most recent run per gate by created_at. Filter by gate (dead-handler | mock-leak | crawl | status-claim) or minimum severity (low|medium|high|critical). Read-only. Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot.',
+    description: "List recent inventory gate runs and their findings for a project, newest first. Returns { runs: [{ id, gate, status, findings_count, \u2026 }], findings: [{ severity, rule_id, message, file_path, node_id, \u2026 }] }. Filter by gate (dead-handler | mock-leak | crawl | status-claim) or minimum severity (low|medium|high|critical). Read-only. Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me what CI gates failed on the last run."
@@ -116,7 +116,7 @@ var TOOL_CATALOG = [
   {
     name: "get_graph_neighborhood",
     title: "Graph neighborhood",
-    description: `Return the BFS neighborhood around one graph node by id or label: { nodes: [{ id, label, type }], edges } within a depth budget (default 2, max 4). Read-only. Tuned for "what touches this action?"; use get_knowledge_graph to traverse from a component seed, or get_graph_node for a single node's row.`,
+    description: `Return the BFS neighborhood around one graph node by id or label: { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4). Read-only. Tuned for "what touches this action?"; use get_knowledge_graph to traverse from a component seed, or get_graph_node for a single node's row.`,
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What nodes connect to this inventory Action within 2 hops?"
@@ -124,7 +124,7 @@ var TOOL_CATALOG = [
   {
     name: "get_graph_node",
     title: "Graph node detail",
-    description: "Fetch one knowledge-graph node row by id: { id, label, type, metadata } including the v2 derived status on Action nodes (ok | stale | broken). Read-only. Use to inspect a single node's status; use get_graph_neighborhood to see what connects to it.",
+    description: "Fetch one knowledge-graph node row by id. Returns { node: { id, node_type, label, metadata } } including the v2 derived status on Action nodes (ok | stale | broken). Read-only. Use to inspect a single node's status; use get_graph_neighborhood to see what connects to it.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What status does the graph store on this node id?"
@@ -175,7 +175,7 @@ var TOOL_CATALOG = [
   {
     name: "trigger_judge",
     title: "Run Sonnet-as-Judge",
-    description: "Queue the Sonnet-as-Judge to grade the quality of recent fixes across a batch of classified reports. Returns { batchId }; graded scores land asynchronously in the judge_results table (read them back with run_nl_query). Write; consumes LLM budget. Idempotent within a short window \u2014 re-running for the same batch re-grades rather than duplicating. Use before shipping to vet fix quality; use get_fix_timeline to inspect a single attempt instead.",
+    description: "Queue the Sonnet-as-Judge to grade recent fix quality across accessible projects. Returns { dispatched: number } \u2014 one judge-batch job per project; scores land asynchronously in judge_results (read back with run_nl_query). Write; consumes LLM budget. Idempotent within a short window. Use before shipping to vet fix quality; use get_fix_timeline to inspect a single attempt instead.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Grade the latest batch of fixes before I ship."
@@ -199,7 +199,7 @@ var TOOL_CATALOG = [
   {
     name: "merge_fix",
     title: "Merge fix PR",
-    description: "Squash-merge the GitHub PR for a fix attempt, mark the linked report fixed, and notify the reporter. Re-readies the PR first if it is still a draft. Returns { merged, reportStatus }. Write; destructive (mutates the target repo's default branch); idempotent \u2014 re-running an already-merged attempt is a safe no-op. Prerequisite: CI green (check with refresh_ci). Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging.",
+    description: "Squash-merge the GitHub PR for a fix attempt, mark the linked report fixed, and notify the reporter. Re-readies the PR first if it is still a draft. Returns { merged, reportStatus }. Write; destructive and irreversible from Mushi's side \u2014 once GitHub merges into the target repo's default branch there is no unmerge endpoint, only a manual revert PR outside this tool. Idempotent \u2014 re-running an already-merged attempt is a safe no-op. Prerequisite: CI green (check with refresh_ci); confirm the diff and CI status with the user before calling on a PR you have not reviewed. Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging.",
     scope: "mcp:write",
     hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Merge the draft PR and notify the reporter."
@@ -207,9 +207,9 @@ var TOOL_CATALOG = [
   {
     name: "refresh_ci",
     title: "Refresh fix CI status",
-    description: "Re-poll GitHub for the latest check-run status of a fix attempt's PR and persist it. Returns { ciStatus: pending|success|failure|neutral, checks: [{ name, conclusion }] }. Read-only (mutates nothing on GitHub). Use right before merge_fix to confirm CI is green; use get_fix_timeline for the full attempt lifecycle.",
-    scope: "mcp:read",
-    hints: { readOnly: true, idempotent: true, openWorld: true },
+    description: "Re-poll GitHub for the latest check-run status of a fix attempt's PR and persist it on the fix_attempt row (does not merge or mutate GitHub). Returns { check_run_status, check_run_conclusion, check_run_updated_at }. Write; idempotent. Use right before merge_fix to confirm CI is green; use get_fix_timeline for the full attempt lifecycle.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Check whether CI is green before merging."
   },
   {
@@ -232,17 +232,17 @@ var TOOL_CATALOG = [
   {
     name: "award_bonus_points",
     title: "Award bonus points",
-    description: "Award ad-hoc bonus points to a contributor by their external user id (as passed to Mushi.identify()). Points are applied server-side, audit-logged, and trigger tier re-evaluation. Requires mcp:write scope. Use this to thank a contributor who found a critical bug or to run a one-off promotional campaign.",
+    description: "Award ad-hoc bonus points (1-50000, positive only \u2014 there is no way to subtract via this tool) to a contributor by their external user id (as passed to Mushi.identify()). Points post immediately to their total and are audit-logged as bonus_manual. Destructive and effectively irreversible: there is no reversal endpoint, so confirm the amount and recipient with the user before calling. Tier re-evaluation (and any host-side reward_webhooks grant tied to crossing a threshold) is NOT immediate \u2014 it only runs on the contributor's next tracked activity, not on this call. Requires mcp:write scope. Use this to thank a contributor who found a critical bug or to run a one-off promotional campaign.",
     scope: "mcp:write",
-    hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
+    hints: { readOnly: false, destructive: true, idempotent: false, openWorld: true },
     useCase: "Give this contributor 500 bonus points for the critical bug they found."
   },
   {
     name: "set_tier",
     title: "Override contributor tier",
-    description: `Override a contributor's tier by tier slug (e.g. "champion"). This is an admin escape hatch for manual promotions \u2014 normal tier transitions happen automatically via point thresholds. The override is logged in end_user_activity with action=tier_override_manual. Requires mcp:write scope.`,
+    description: `Override a contributor's tier by tier slug (e.g. "champion"), bypassing the normal points-threshold logic entirely. This is an admin escape hatch for manual promotions \u2014 normal tier transitions happen automatically via point thresholds instead. Destructive: it is a label-only override that does NOT replay the automatic tier-evaluation path, so any host_credit_payload grant (Stripe perk, badge, etc.) normally tied to reaching that tier via points will NOT fire \u2014 confirm with the user whether they also need the perk granted another way. The override persists until another set_tier call changes it; the prior override stays in the end_user_activity audit trail either way, logged as tier_override_manual. Requires mcp:write scope.`,
     scope: "mcp:write",
-    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Manually promote this user to Champion tier as a thank-you."
   },
   {
@@ -314,7 +314,7 @@ var TOOL_CATALOG = [
   {
     name: "list_lessons",
     title: "List project lessons",
-    description: 'List the promoted learning rules ("lessons") for the current project, newest first. Each lesson is a named pattern of mistakes encoded from past bug reports. Returns { lessons: [{ id, title, rule, severity, source_report_ids }] }. Read-only. Use to see the full catalog of encoded heuristics; use query_lessons to retrieve only the lessons relevant to a specific diff or PR within a token budget.',
+    description: 'List promoted learning rules ("lessons") for the current project, highest-frequency first. Returns { lessons: [{ id, rule_text, severity, frequency, anti_pattern, \u2026 }] }. Read-only. Use to browse the full catalog of encoded heuristics; use query_lessons to retrieve only lessons relevant to a specific diff or PR within a token budget.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What systemic patterns has Mushi identified for this project?"
@@ -537,7 +537,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "search_codebase",
     title: "Semantic codebase search",
-    description: 'Search the indexed repo by plain-English meaning via embeddings. Returns top-k { results: [{ path, startLine, endLine, snippet, similarity }] } ordered by similarity. Requires codebase indexing enabled. Read-only. Use to locate where something lives ("where do we verify webhooks?"); use ask_codebase for a synthesized answer with citations, or analyze_codebase_impact to find dependents of a file.',
+    description: 'Search the indexed repo by plain-English meaning via embeddings. Returns { results: [{ file_path, line_start, line_end, content_preview, similarity, \u2026 }], query, mode } ordered by similarity. Requires codebase indexing enabled. Read-only. Use to locate where something lives ("where do we verify webhooks?"); use ask_codebase for a synthesized answer with citations, or analyze_codebase_impact to find dependents of a file.',
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Find files related to authentication or payment handling."
@@ -553,7 +553,7 @@ var CODEBASE_TOOL_CATALOG = [
   {
     name: "analyze_codebase_impact",
     title: "Diff impact analysis",
-    description: "Find the files that depend on a set of changed paths by walking the reverse import graph. Source the paths from: manual list, the last push, a GitHub compare range, or a fix PR's files. Returns { impacted: [{ path, importedBy }], depth }. Requires codebase indexing. Read-only. Use to gauge a diff's blast radius before merging; use get_blast_radius for a bug's component impact, or search_codebase to locate files.",
+    description: "Find files that depend on a set of changed paths by walking the reverse import graph. Source paths from: manual list, last push, a GitHub compare range, or a fix PR's files. Returns { changed_paths, source, affected_file_paths, affected_node_ids, meta }. Requires codebase indexing. Read-only. Use to gauge a diff's blast radius before merging; use get_blast_radius for a bug's component impact, or search_codebase to locate files.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What breaks if I change lib/auth.ts?"
@@ -1222,8 +1222,12 @@ function createMushiServer(config) {
       description: descOf("get_knowledge_graph"),
       annotations: annotationsFor("get_knowledge_graph"),
       inputSchema: {
-        seed: z.string().describe("Starting node id or label"),
-        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+        seed: z.string().describe("Starting graph node id or human-readable label to traverse from"),
+        depth: z.number().optional().describe("BFS hops outward from seed \u2014 clamped to 4 in the handler (default 2)")
+      },
+      outputSchema: {
+        nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
+        edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
       }
     },
     async (args) => {
@@ -1231,7 +1235,8 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1243,6 +1248,10 @@ function createMushiServer(config) {
       inputSchema: {
         seed: z.string().describe("Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"),
         depth: z.number().int().min(1).max(4).optional().describe("BFS hops to traverse outward. Default 2; clamped to a max of 4.")
+      },
+      outputSchema: {
+        nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
+        edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
       }
     },
     async (args) => {
@@ -1250,7 +1259,8 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1259,9 +1269,15 @@ function createMushiServer(config) {
       title: titleOf("get_graph_node"),
       description: descOf("get_graph_node"),
       annotations: annotationsFor("get_graph_node"),
-      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") }
+      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") },
+      outputSchema: {
+        node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
+      }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
+    async (args) => {
+      const data = await apiCall(`/v1/admin/graph/node/${args.nodeId}`);
+      return jsonResult(data);
+    }
   );
   server.registerTool(
     "get_inventory",
@@ -1308,6 +1324,10 @@ function createMushiServer(config) {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
         gate: z.string().optional().describe("Filter to one gate id: dead-handler | mock-leak | crawl | status-claim"),
         severity: z.string().optional().describe("Minimum severity to include: low | medium | high | critical")
+      },
+      outputSchema: {
+        runs: z.array(z.unknown()).describe("Recent gate_runs rows, newest first"),
+        findings: z.array(z.unknown()).describe("gate_findings rows for those runs")
       }
     },
     async (args) => {
@@ -1317,7 +1337,8 @@ function createMushiServer(config) {
       if (args.gate) q.set("gate", args.gate);
       if (args.severity) q.set("severity", args.severity);
       const suffix = q.toString() ? `?${q}` : "";
-      return jsonText(await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`));
+      const data = await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1806,13 +1827,17 @@ function createMushiServer(config) {
       description: descOf("submit_fix_result"),
       annotations: annotationsFor("submit_fix_result"),
       inputSchema: {
-        reportId: z.string().describe("The report UUID"),
-        branch: z.string().describe("Git branch name"),
-        prUrl: z.string().optional().describe("GitHub PR URL"),
-        filesChanged: z.array(z.string()).describe("Files modified"),
-        linesChanged: z.number().describe("Total lines changed"),
-        summary: z.string().describe("Fix summary"),
+        reportId: z.string().describe("Report UUID to attach this external fix attempt to"),
+        branch: z.string().describe("Git branch name where the fix was implemented"),
+        prUrl: z.string().optional().describe("GitHub pull request URL, if a PR was opened"),
+        filesChanged: z.array(z.string()).describe("Repo-relative paths modified by the fix"),
+        linesChanged: z.number().describe("Total lines added + removed across filesChanged"),
+        summary: z.string().describe("One-line human summary of what the fix changed"),
         idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
+      },
+      outputSchema: {
+        ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
+        fixId: z.string().describe("UUID of the new fix_attempt row")
       }
     },
     async (args) => {
@@ -1834,7 +1859,7 @@ function createMushiServer(config) {
           completed_at: (/* @__PURE__ */ new Date()).toISOString()
         })
       });
-      return jsonText({ ok: true, fixId: created.fixId });
+      return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
   server.registerTool(
@@ -1891,6 +1916,9 @@ function createMushiServer(config) {
       inputSchema: {
         limit: z.number().optional().describe("Max reports to judge in this batch (default 25, max 100)"),
         projectId: z.string().optional().describe("Restrict to one project when the API key owns multiple")
+      },
+      outputSchema: {
+        dispatched: z.number().describe("Number of judge-batch jobs dispatched (one per accessible project)")
       }
     },
     async (args) => {
@@ -1901,7 +1929,7 @@ function createMushiServer(config) {
           projectId: args.projectId ?? projectId ?? void 0
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1932,8 +1960,14 @@ function createMushiServer(config) {
       description: descOf("merge_fix"),
       annotations: annotationsFor("merge_fix"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID"),
-        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method")
+        fixId: z.string().describe("Fix attempt UUID whose GitHub PR should be squash-merged"),
+        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method (default squash)")
+      },
+      outputSchema: {
+        merged: z.boolean().optional().describe("True when GitHub accepted the merge in this call"),
+        alreadyMerged: z.boolean().optional().describe("True when the PR was already merged (idempotent no-op)"),
+        reportId: z.string().describe("Report UUID linked to this fix attempt"),
+        reportStatus: z.string().describe("Report workflow status after merge bookkeeping")
       }
     },
     async (args) => {
@@ -1941,7 +1975,7 @@ function createMushiServer(config) {
         method: "POST",
         body: JSON.stringify({ mergeMethod: args.mergeMethod ?? "squash" })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1951,12 +1985,17 @@ function createMushiServer(config) {
       description: descOf("refresh_ci"),
       annotations: annotationsFor("refresh_ci"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID")
+        fixId: z.string().describe("Fix attempt UUID whose PR check-runs should be re-polled")
+      },
+      outputSchema: {
+        check_run_status: z.string().nullable().describe("GitHub check run status after refresh"),
+        check_run_conclusion: z.string().nullable().describe("success | failure | neutral | null while pending"),
+        check_run_updated_at: z.string().nullable().describe("ISO timestamp when CI status was last persisted")
       }
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1966,16 +2005,19 @@ function createMushiServer(config) {
       description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
       inputSchema: {
-        reportId: z.string().describe("Report UUID"),
-        note: z.string().optional().describe("Triage note")
+        reportId: z.string().describe("Report UUID to move back to reopened status"),
+        note: z.string().optional().describe("Operator note recorded on the reopen transition")
+      },
+      outputSchema: {
+        report: z.unknown().describe("Updated report row with status=reopened")
       }
     },
     async (args) => {
-      const data = await apiCall(`/v1/sync/reports/${args.reportId}`, {
+      const report = await apiCall(`/v1/sync/reports/${args.reportId}`, {
         method: "PATCH",
         body: JSON.stringify({ status: "reopened", note: args.note })
       });
-      return jsonText(data);
+      return jsonResult({ report });
     }
   );
   server.registerTool(
@@ -2052,9 +2094,12 @@ function createMushiServer(config) {
       description: descOf("list_lessons"),
       annotations: annotationsFor("list_lessons"),
       inputSchema: {
-        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter by severity level."),
-        limit: z.number().optional().describe("Max number of lessons to return (default 50, max 200)."),
-        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter to one severity level"),
+        limit: z.number().optional().describe("Max lessons to return (default 50, max 200)"),
+        project_id: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
+      },
+      outputSchema: {
+        lessons: z.array(z.unknown()).describe("Promoted lesson rows ordered by frequency")
       }
     },
     async (args) => {
@@ -2063,8 +2108,8 @@ function createMushiServer(config) {
       if (args.severity) params.set("severity", args.severity);
       params.set("limit", String(Math.min(args.limit ?? 50, 200)));
       if (pid) params.set("projectId", pid);
-      const data = await apiCall(`/v1/admin/lessons?${params}`);
-      return jsonText(data);
+      const lessons = await apiCall(`/v1/admin/lessons?${params}`);
+      return jsonResult({ lessons });
     }
   );
   server.resource(
@@ -2402,11 +2447,17 @@ Be specific. No generic advice.`
       description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
       inputSchema: {
-        projectId: z.string().describe("Project id"),
-        storyNodeId: z.string().describe("User story id slug from the accepted inventory"),
-        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Gate mode for the generated test (default: review)"),
-        baseUrl: z.string().url().optional().describe("Override the app base URL"),
-        openPr: z.boolean().optional().describe("Open a draft GitHub PR (default: true)")
+        projectId: z.string().describe("Project UUID that owns the inventory story"),
+        storyNodeId: z.string().describe("User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"),
+        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Approval gate for the generated qa_story (default review \u2192 pending_review)"),
+        baseUrl: z.string().url().optional().describe("Override the live app URL the Playwright test should target"),
+        openPr: z.boolean().optional().describe("Open a draft GitHub PR with the generated spec (default true)")
+      },
+      outputSchema: {
+        qaStoryId: z.string().describe("UUID of the inserted qa_stories row"),
+        prUrl: z.string().nullable().describe("GitHub PR URL when openPr=true and GitHub is connected"),
+        approvalStatus: z.string().describe("pending_review | approved \u2014 follows automationMode and project defaults"),
+        needsHumanReview: z.boolean().describe("True when the story requires operator approval before scheduled runs")
       }
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
@@ -2415,7 +2466,7 @@ Be specific. No generic advice.`
         `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
         { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
       );
-      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2861,23 +2912,31 @@ Be specific. No generic advice.`
       annotations: annotationsFor("search_codebase", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        query: z.string().describe("Plain-English search query"),
-        k: z.number().optional().describe("Number of results (default 8, max 20)"),
-        scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
+        query: z.string().describe("Plain-English search query against indexed source files"),
+        k: z.number().int().min(1).max(20).optional().describe("Max hits to return (default 8, max 20)"),
+        scope_prefix: z.string().optional().describe("Optional repo subdirectory prefix to limit search scope")
+      },
+      outputSchema: {
+        results: z.array(z.unknown()).describe("Ranked file/symbol hits with paths, line ranges, and similarity"),
+        query: z.string().describe("Normalized query string that was searched"),
+        mode: z.string().optional().describe("semantic (embeddings) or name (path/symbol match)")
       }
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
       if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
-      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/search`, {
-        method: "POST",
-        body: JSON.stringify({
-          query: args.query,
-          k: args.k ?? 8,
-          scope_prefix: args.scope_prefix ?? void 0
-        })
-      });
-      return jsonText(data);
+      const data = await apiCall(
+        `/v1/admin/projects/${pid}/codebase/search`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            query: args.query,
+            k: args.k ?? 8,
+            scope_prefix: args.scope_prefix ?? void 0
+          })
+        }
+      );
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2911,10 +2970,17 @@ Be specific. No generic advice.`
       annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        paths: z.array(z.string()).optional().describe("Changed file paths"),
-        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths"),
-        compare: z.string().optional().describe("GitHub compare range base...head"),
-        fix_id: z.string().optional().describe("Fix attempt UUID for PR changed files")
+        paths: z.array(z.string()).optional().describe("Changed repo-relative file paths to analyze"),
+        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths instead of manual paths"),
+        compare: z.string().optional().describe("GitHub compare range base...head when source=compare"),
+        fix_id: z.string().optional().describe("Fix attempt UUID \u2014 uses that PR's changed files when source=fix")
+      },
+      outputSchema: {
+        changed_paths: z.array(z.string()).describe("Resolved set of changed paths analyzed"),
+        source: z.string().describe("How changed_paths were resolved (manual, last_push, compare, fix, \u2026)"),
+        affected_file_paths: z.array(z.string()).describe("Indexed files that import or depend on changed paths"),
+        affected_node_ids: z.array(z.string()).describe("Codebase graph node ids impacted by the change"),
+        meta: z.unknown().nullable().optional().describe("Extra resolution metadata when auto-sourced")
       }
     },
     async (args) => {
@@ -2929,7 +2995,7 @@ Be specific. No generic advice.`
         throw new MushiApiError(400, "BAD_REQUEST", "Provide paths, source=last_push, compare, or fix_id");
       }
       const data = await apiCall(`/v1/admin/projects/${pid}/codebase/impact?${qs}`);
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(

package/dist/server.js

@@ -2,7 +2,7 @@ import {
   CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-KNVB6HA7.js";
+} from "./chunk-DSOPGMDX.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EANW5YTI.js";
@@ -490,8 +490,12 @@ function createMushiServer(config) {
       description: descOf("get_knowledge_graph"),
       annotations: annotationsFor("get_knowledge_graph"),
       inputSchema: {
-        seed: z.string().describe("Starting node id or label"),
-        depth: z.number().optional().describe("Traversal depth (default 2, max 4)")
+        seed: z.string().describe("Starting graph node id or human-readable label to traverse from"),
+        depth: z.number().optional().describe("BFS hops outward from seed \u2014 clamped to 4 in the handler (default 2)")
+      },
+      outputSchema: {
+        nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
+        edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
       }
     },
     async (args) => {
@@ -499,7 +503,8 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -511,6 +516,10 @@ function createMushiServer(config) {
       inputSchema: {
         seed: z.string().describe("Starting graph node id or label to expand around (e.g. an inventory Action id or component name)"),
         depth: z.number().int().min(1).max(4).optional().describe("BFS hops to traverse outward. Default 2; clamped to a max of 4.")
+      },
+      outputSchema: {
+        nodes: z.array(z.unknown()).describe("Graph nodes within the depth budget"),
+        edges: z.array(z.unknown()).describe("Edges connecting the returned nodes")
       }
     },
     async (args) => {
@@ -518,7 +527,8 @@ function createMushiServer(config) {
         seed: args.seed,
         depth: String(Math.min(args.depth ?? 2, 4))
       });
-      return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
+      const data = await apiCall(`/v1/admin/graph/traverse?${params}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -527,9 +537,15 @@ function createMushiServer(config) {
       title: titleOf("get_graph_node"),
       description: descOf("get_graph_node"),
       annotations: annotationsFor("get_graph_node"),
-      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") }
+      inputSchema: { nodeId: z.string().describe("The graph_nodes.id of the node to fetch (UUID).") },
+      outputSchema: {
+        node: z.unknown().describe("Single graph_nodes row including metadata (Action nodes carry v2 status)")
+      }
     },
-    async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
+    async (args) => {
+      const data = await apiCall(`/v1/admin/graph/node/${args.nodeId}`);
+      return jsonResult(data);
+    }
   );
   server.registerTool(
     "get_inventory",
@@ -576,6 +592,10 @@ function createMushiServer(config) {
         projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project"),
         gate: z.string().optional().describe("Filter to one gate id: dead-handler | mock-leak | crawl | status-claim"),
         severity: z.string().optional().describe("Minimum severity to include: low | medium | high | critical")
+      },
+      outputSchema: {
+        runs: z.array(z.unknown()).describe("Recent gate_runs rows, newest first"),
+        findings: z.array(z.unknown()).describe("gate_findings rows for those runs")
       }
     },
     async (args) => {
@@ -585,7 +605,8 @@ function createMushiServer(config) {
       if (args.gate) q.set("gate", args.gate);
       if (args.severity) q.set("severity", args.severity);
       const suffix = q.toString() ? `?${q}` : "";
-      return jsonText(await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`));
+      const data = await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1074,13 +1095,17 @@ function createMushiServer(config) {
       description: descOf("submit_fix_result"),
       annotations: annotationsFor("submit_fix_result"),
       inputSchema: {
-        reportId: z.string().describe("The report UUID"),
-        branch: z.string().describe("Git branch name"),
-        prUrl: z.string().optional().describe("GitHub PR URL"),
-        filesChanged: z.array(z.string()).describe("Files modified"),
-        linesChanged: z.number().describe("Total lines changed"),
-        summary: z.string().describe("Fix summary"),
+        reportId: z.string().describe("Report UUID to attach this external fix attempt to"),
+        branch: z.string().describe("Git branch name where the fix was implemented"),
+        prUrl: z.string().optional().describe("GitHub pull request URL, if a PR was opened"),
+        filesChanged: z.array(z.string()).describe("Repo-relative paths modified by the fix"),
+        linesChanged: z.number().describe("Total lines added + removed across filesChanged"),
+        summary: z.string().describe("One-line human summary of what the fix changed"),
         idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
+      },
+      outputSchema: {
+        ok: z.boolean().describe("True when the fix_attempt row was created and marked completed"),
+        fixId: z.string().describe("UUID of the new fix_attempt row")
       }
     },
     async (args) => {
@@ -1102,7 +1127,7 @@ function createMushiServer(config) {
           completed_at: (/* @__PURE__ */ new Date()).toISOString()
         })
       });
-      return jsonText({ ok: true, fixId: created.fixId });
+      return jsonResult({ ok: true, fixId: created.fixId });
     }
   );
   server.registerTool(
@@ -1159,6 +1184,9 @@ function createMushiServer(config) {
       inputSchema: {
         limit: z.number().optional().describe("Max reports to judge in this batch (default 25, max 100)"),
         projectId: z.string().optional().describe("Restrict to one project when the API key owns multiple")
+      },
+      outputSchema: {
+        dispatched: z.number().describe("Number of judge-batch jobs dispatched (one per accessible project)")
       }
     },
     async (args) => {
@@ -1169,7 +1197,7 @@ function createMushiServer(config) {
           projectId: args.projectId ?? projectId ?? void 0
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1200,8 +1228,14 @@ function createMushiServer(config) {
       description: descOf("merge_fix"),
       annotations: annotationsFor("merge_fix"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID"),
-        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method")
+        fixId: z.string().describe("Fix attempt UUID whose GitHub PR should be squash-merged"),
+        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method (default squash)")
+      },
+      outputSchema: {
+        merged: z.boolean().optional().describe("True when GitHub accepted the merge in this call"),
+        alreadyMerged: z.boolean().optional().describe("True when the PR was already merged (idempotent no-op)"),
+        reportId: z.string().describe("Report UUID linked to this fix attempt"),
+        reportStatus: z.string().describe("Report workflow status after merge bookkeeping")
       }
     },
     async (args) => {
@@ -1209,7 +1243,7 @@ function createMushiServer(config) {
         method: "POST",
         body: JSON.stringify({ mergeMethod: args.mergeMethod ?? "squash" })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1219,12 +1253,17 @@ function createMushiServer(config) {
       description: descOf("refresh_ci"),
       annotations: annotationsFor("refresh_ci"),
       inputSchema: {
-        fixId: z.string().describe("Fix attempt UUID")
+        fixId: z.string().describe("Fix attempt UUID whose PR check-runs should be re-polled")
+      },
+      outputSchema: {
+        check_run_status: z.string().nullable().describe("GitHub check run status after refresh"),
+        check_run_conclusion: z.string().nullable().describe("success | failure | neutral | null while pending"),
+        check_run_updated_at: z.string().nullable().describe("ISO timestamp when CI status was last persisted")
       }
     },
     async (args) => {
       const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -1234,16 +1273,19 @@ function createMushiServer(config) {
       description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
       inputSchema: {
-        reportId: z.string().describe("Report UUID"),
-        note: z.string().optional().describe("Triage note")
+        reportId: z.string().describe("Report UUID to move back to reopened status"),
+        note: z.string().optional().describe("Operator note recorded on the reopen transition")
+      },
+      outputSchema: {
+        report: z.unknown().describe("Updated report row with status=reopened")
       }
     },
     async (args) => {
-      const data = await apiCall(`/v1/sync/reports/${args.reportId}`, {
+      const report = await apiCall(`/v1/sync/reports/${args.reportId}`, {
         method: "PATCH",
         body: JSON.stringify({ status: "reopened", note: args.note })
       });
-      return jsonText(data);
+      return jsonResult({ report });
     }
   );
   server.registerTool(
@@ -1320,9 +1362,12 @@ function createMushiServer(config) {
       description: descOf("list_lessons"),
       annotations: annotationsFor("list_lessons"),
       inputSchema: {
-        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter by severity level."),
-        limit: z.number().optional().describe("Max number of lessons to return (default 50, max 200)."),
-        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter to one severity level"),
+        limit: z.number().optional().describe("Max lessons to return (default 50, max 200)"),
+        project_id: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
+      },
+      outputSchema: {
+        lessons: z.array(z.unknown()).describe("Promoted lesson rows ordered by frequency")
       }
     },
     async (args) => {
@@ -1331,8 +1376,8 @@ function createMushiServer(config) {
       if (args.severity) params.set("severity", args.severity);
       params.set("limit", String(Math.min(args.limit ?? 50, 200)));
       if (pid) params.set("projectId", pid);
-      const data = await apiCall(`/v1/admin/lessons?${params}`);
-      return jsonText(data);
+      const lessons = await apiCall(`/v1/admin/lessons?${params}`);
+      return jsonResult({ lessons });
     }
   );
   server.resource(
@@ -1670,11 +1715,17 @@ Be specific. No generic advice.`
       description: descOf("generate_tdd_from_story", TDD_TOOL_CATALOG),
       annotations: annotationsFor("generate_tdd_from_story", TDD_TOOL_CATALOG),
       inputSchema: {
-        projectId: z.string().describe("Project id"),
-        storyNodeId: z.string().describe("User story id slug from the accepted inventory"),
-        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Gate mode for the generated test (default: review)"),
-        baseUrl: z.string().url().optional().describe("Override the app base URL"),
-        openPr: z.boolean().optional().describe("Open a draft GitHub PR (default: true)")
+        projectId: z.string().describe("Project UUID that owns the inventory story"),
+        storyNodeId: z.string().describe("User story node id/slug from accepted inventory (from map_user_stories or inventory.yaml)"),
+        automationMode: z.enum(["auto", "review", "approve"]).optional().describe("Approval gate for the generated qa_story (default review \u2192 pending_review)"),
+        baseUrl: z.string().url().optional().describe("Override the live app URL the Playwright test should target"),
+        openPr: z.boolean().optional().describe("Open a draft GitHub PR with the generated spec (default true)")
+      },
+      outputSchema: {
+        qaStoryId: z.string().describe("UUID of the inserted qa_stories row"),
+        prUrl: z.string().nullable().describe("GitHub PR URL when openPr=true and GitHub is connected"),
+        approvalStatus: z.string().describe("pending_review | approved \u2014 follows automationMode and project defaults"),
+        needsHumanReview: z.boolean().describe("True when the story requires operator approval before scheduled runs")
       }
     },
     async ({ projectId: projectId2, storyNodeId, automationMode, baseUrl, openPr }) => {
@@ -1683,7 +1734,7 @@ Be specific. No generic advice.`
         `/v1/admin/inventory/${projectId2}/stories/${storyNodeId}/generate-test`,
         { method: "POST", body: JSON.stringify({ automation_mode: automationMode, base_url: baseUrl, open_pr: openPr }) }
       );
-      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2129,23 +2180,31 @@ Be specific. No generic advice.`
       annotations: annotationsFor("search_codebase", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        query: z.string().describe("Plain-English search query"),
-        k: z.number().optional().describe("Number of results (default 8, max 20)"),
-        scope_prefix: z.string().optional().describe("Optional subdirectory scope prefix")
+        query: z.string().describe("Plain-English search query against indexed source files"),
+        k: z.number().int().min(1).max(20).optional().describe("Max hits to return (default 8, max 20)"),
+        scope_prefix: z.string().optional().describe("Optional repo subdirectory prefix to limit search scope")
+      },
+      outputSchema: {
+        results: z.array(z.unknown()).describe("Ranked file/symbol hits with paths, line ranges, and similarity"),
+        query: z.string().describe("Normalized query string that was searched"),
+        mode: z.string().optional().describe("semantic (embeddings) or name (path/symbol match)")
       }
     },
     async (args) => {
       const pid = args.project_id ?? projectId;
       if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "project_id is required");
-      const data = await apiCall(`/v1/admin/projects/${pid}/codebase/search`, {
-        method: "POST",
-        body: JSON.stringify({
-          query: args.query,
-          k: args.k ?? 8,
-          scope_prefix: args.scope_prefix ?? void 0
-        })
-      });
-      return jsonText(data);
+      const data = await apiCall(
+        `/v1/admin/projects/${pid}/codebase/search`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            query: args.query,
+            k: args.k ?? 8,
+            scope_prefix: args.scope_prefix ?? void 0
+          })
+        }
+      );
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -2179,10 +2238,17 @@ Be specific. No generic advice.`
       annotations: annotationsFor("analyze_codebase_impact", CODEBASE_TOOL_CATALOG),
       inputSchema: {
         project_id: z.string().optional().describe("Project UUID (defaults to configured project)"),
-        paths: z.array(z.string()).optional().describe("Changed file paths"),
-        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths"),
-        compare: z.string().optional().describe("GitHub compare range base...head"),
-        fix_id: z.string().optional().describe("Fix attempt UUID for PR changed files")
+        paths: z.array(z.string()).optional().describe("Changed repo-relative file paths to analyze"),
+        source: z.enum(["last_push", "compare", "fix"]).optional().describe("Auto-resolve changed paths instead of manual paths"),
+        compare: z.string().optional().describe("GitHub compare range base...head when source=compare"),
+        fix_id: z.string().optional().describe("Fix attempt UUID \u2014 uses that PR's changed files when source=fix")
+      },
+      outputSchema: {
+        changed_paths: z.array(z.string()).describe("Resolved set of changed paths analyzed"),
+        source: z.string().describe("How changed_paths were resolved (manual, last_push, compare, fix, \u2026)"),
+        affected_file_paths: z.array(z.string()).describe("Indexed files that import or depend on changed paths"),
+        affected_node_ids: z.array(z.string()).describe("Codebase graph node ids impacted by the change"),
+        meta: z.unknown().nullable().optional().describe("Extra resolution metadata when auto-sourced")
       }
     },
     async (args) => {
@@ -2197,7 +2263,7 @@ Be specific. No generic advice.`
         throw new MushiApiError(400, "BAD_REQUEST", "Provide paths, source=last_push, compare, or fix_id");
       }
       const data = await apiCall(`/v1/admin/projects/${pid}/codebase/impact?${qs}`);
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
   "mcpName": "io.github.kensaurus/mushi-mushi",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "license": "MIT",
   "description": "MCP server for Mushi Mushi — triage user-felt bugs, pull evidence (screenshots, console logs, network requests), check blast radius, and dispatch fix PRs, all from your AI coding agent",
   "type": "module",
@@ -48,7 +48,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sentry/node": "^10.57.0",
     "zod": "^4.4.3",
-    "@mushi-mushi/core": "^1.22.1"
+    "@mushi-mushi/core": "^1.22.5"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",