@mushi-mushi/mcp 0.6.0 → 0.8.0

package/CONTRIBUTING.md

@@ -101,6 +101,17 @@ Releases are fully automated. Maintainers don't run `npm publish` by hand.
 
 If GitHub's anti-loop protection suppresses the auto re-fire (the squash merge can be attributed to `github-actions[bot]`), trigger the workflow manually: **Actions → release → Run workflow → master**.
 
+### Known CI/CD quirks and their automatic safeguards
+
+A handful of GitHub-Actions × Changesets edge cases have caused release-pipeline stalls in the past. Each is now caught automatically — keep these in mind when you see the symptom:
+
+| Symptom | Root cause | Automatic safeguard |
+| --- | --- | --- |
+| The `Build & Test` required check never registers on the `chore: version packages` PR — the PR stays "Required check missing" forever | `changeset-release/master` is pushed by `github-actions[bot]`. GitHub silently drops the downstream `pull_request` event to prevent bot loops (observed on PR #45, #102, #124). | `ci.yml` now also triggers on `push` to `changeset-release/master`, so `Build & Test` reports against the head commit directly. No empty-commit nudge needed. |
+| Release workflow fails with `No commits between master and changeset-release/master` after merging a PR with a new changeset. | A `.changeset/*.md` file whose YAML frontmatter only targets packages listed in `.changeset/config.json#ignore` (e.g. `@mushi-mushi/server`, `@mushi-mushi/admin`). `changeset version` produces no bumps, the version PR is empty, the next push errors (PR #102 / #121, 2026-05-19). | `pnpm check:changeset-orphans` runs in both `ci.yml` and `release.yml`. PR CI fails with an actionable message naming the orphan file *before* it can reach master. If you legitimately need to record an internal-only change, omit the changeset entirely — the diff lives in git history. |
+| Release workflow's `Audit signatures of installed dependencies` step fails with `npm ETARGET / No matching version found for @mushi-mushi/<pkg>@<ver>` seconds after the publish step succeeded. | npm's registry CDN can take up to ~30s to propagate a freshly-published manifest. The audit step shells out to `npm install` against the just-published version and races the CDN (observed 2026-05-20, run 26149167393). | The audit step retries with exponential backoff (1, 2, 4, 8, 16, 32s — 63s total) before failing. Sigstore signatures are written at publish time, so a one-off audit failure never indicates a corrupted package — `pnpm view <pkg> version` is the ground truth. |
+| Push to `master` after merging a PR doesn't fire the `Release` workflow. | Same anti-loop protection: when a squash merge is attributed to `github-actions[bot]`, GitHub may suppress the downstream `push` trigger. Sporadic — observed twice in the last 60 days. | `release.yml` keeps `workflow_dispatch` as the manual fallback. Recovery: **Actions → Release → Run workflow → master**. The `Build & Verify` job re-runs identically to the auto-fired path. |
+
 ### Adding a brand-new publishable package
 
 Trusted Publisher bindings are configured **per package** on `npmjs.com` and require the package to already exist on the registry. New packages therefore need a one-time bootstrap before OIDC can take over.

package/dist/index.js

@@ -5,11 +5,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { createRequire } from "module";
 import { createLogger } from "@mushi-mushi/core";
 
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-
 // src/catalog.ts
+var ALL_SCOPES = ["mcp:read", "mcp:write"];
 var TOOL_CATALOG = [
   {
     name: "get_recent_reports",
@@ -145,10 +142,10 @@ var TOOL_CATALOG = [
   {
     name: "dispatch_fix",
     title: "Dispatch Mushi fix agent",
-    description: "Dispatch the Mushi agentic fix orchestrator for a classified report. Returns a fix_attempt id; poll get_fix_timeline for progress.",
+    description: 'Dispatch the Mushi agentic fix orchestrator for a classified report. Set agent="cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR. Returns a fix_attempt id; poll get_fix_timeline for progress.',
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
-    useCase: "Let the in-repo agent attempt this fix for me."
+    useCase: "Let the in-repo agent attempt this fix for me (or: dispatch a Cursor Cloud Agent)."
   },
   {
     name: "trigger_judge",
@@ -205,6 +202,8 @@ var TOOL_CATALOG = [
 ];
 
 // src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 var MushiApiError = class extends Error {
   constructor(status, code, message) {
     super(`[${code}] ${message}`);
@@ -218,6 +217,7 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const grantedScopes = new Set(config.scopes ?? ALL_SCOPES);
   async function apiCall(path, options) {
     const res = await doFetch(`${apiEndpoint}${path}`, {
       ...options,
@@ -289,7 +289,23 @@ function createMushiServer(config) {
     if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
     return spec.title;
   }
-  server.registerTool(
+  function shouldRegister(name) {
+    const spec = TOOL_CATALOG.find((t) => t.name === name);
+    if (!spec) throw new Error(`[mushi-mcp] tool "${name}" is missing from TOOL_CATALOG`);
+    return grantedScopes.has(spec.scope);
+  }
+  function jsonResult(value) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+      structuredContent: value
+    };
+  }
+  const _serverRegisterTool = server.registerTool.bind(server);
+  const registerScopedTool = ((name, ...rest) => {
+    if (!shouldRegister(name)) return void 0;
+    return _serverRegisterTool(name, ...rest);
+  });
+  registerScopedTool(
     "get_recent_reports",
     {
       title: titleOf("get_recent_reports"),
@@ -300,6 +316,13 @@ function createMushiServer(config) {
         category: z.string().optional().describe("Filter by category: bug, slow, visual, confusing, other"),
         severity: z.string().optional().describe("Filter by severity: critical, high, medium, low"),
         limit: z.number().optional().describe("Max reports to return (default 20, max 100)")
+      },
+      // Output schema (MCP 2025-06-18): when set, the SDK validates the
+      // tool's `structuredContent` and lets typed clients deserialize
+      // without re-parsing the text payload.
+      outputSchema: {
+        reports: z.array(z.record(z.string(), z.unknown())).describe("Array of report rows"),
+        total: z.number().describe("Total matching rows (before limit)")
       }
     },
     async (args) => {
@@ -309,10 +332,13 @@ function createMushiServer(config) {
       if (args.severity) params.set("severity", args.severity);
       params.set("limit", String(Math.min(args.limit ?? 20, 100)));
       const data = await apiCall(`/v1/admin/reports?${params}`);
-      return jsonText(data);
+      return jsonResult({
+        reports: data.reports ?? [],
+        total: data.total ?? 0
+      });
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "get_report_detail",
     {
       title: titleOf("get_report_detail"),
@@ -322,7 +348,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}`))
   );
-  server.registerTool(
+  registerScopedTool(
     "search_reports",
     {
       title: titleOf("search_reports"),
@@ -332,6 +358,9 @@ function createMushiServer(config) {
         query: z.string().describe("Natural-language search text or component path"),
         limit: z.number().optional().describe("Max results (default 10, max 50)"),
         threshold: z.number().optional().describe("Similarity threshold 0..1, default 0.2")
+      },
+      outputSchema: {
+        results: z.array(z.record(z.string(), z.unknown())).describe("Ranked report rows with similarity scores")
       }
     },
     async (args) => {
@@ -344,10 +373,10 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonText(data);
+      return jsonResult({ results: data.results ?? [] });
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "get_similar_bugs",
     {
       title: titleOf("get_similar_bugs"),
@@ -356,6 +385,9 @@ function createMushiServer(config) {
       inputSchema: {
         query: z.string().describe("Component name, page path, or bug description"),
         limit: z.number().optional().describe("Max results (default 5, max 20)")
+      },
+      outputSchema: {
+        results: z.array(z.record(z.string(), z.unknown())).describe("Ranked report rows with similarity scores")
       }
     },
     async (args) => {
@@ -368,10 +400,10 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonText(data);
+      return jsonResult({ results: data.results ?? [] });
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "get_fix_context",
     {
       title: titleOf("get_fix_context"),
@@ -390,7 +422,7 @@ function createMushiServer(config) {
       });
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "get_fix_timeline",
     {
       title: titleOf("get_fix_timeline"),
@@ -400,7 +432,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/fixes/${args.fixId}/timeline`))
   );
-  server.registerTool(
+  registerScopedTool(
     "get_blast_radius",
     {
       title: titleOf("get_blast_radius"),
@@ -410,7 +442,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/graph/blast-radius/${args.nodeId}`))
   );
-  server.registerTool(
+  registerScopedTool(
     "get_knowledge_graph",
     {
       title: titleOf("get_knowledge_graph"),
@@ -429,7 +461,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "graph_neighborhood",
     {
       title: titleOf("graph_neighborhood"),
@@ -448,7 +480,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/graph/traverse?${params}`));
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "graph_node_status",
     {
       title: titleOf("graph_node_status"),
@@ -458,7 +490,7 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/graph/node/${args.nodeId}`))
   );
-  server.registerTool(
+  registerScopedTool(
     "inventory_get",
     {
       title: titleOf("inventory_get"),
@@ -474,7 +506,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}`));
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "inventory_diff",
     {
       title: titleOf("inventory_diff"),
@@ -493,7 +525,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/diff?${q}`));
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "inventory_findings",
     {
       title: titleOf("inventory_findings"),
@@ -515,7 +547,7 @@ function createMushiServer(config) {
       return jsonText(await apiCall(`/v1/admin/inventory/${pid}/findings${suffix}`));
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "fix_suggest",
     {
       title: titleOf("fix_suggest"),
@@ -536,7 +568,7 @@ function createMushiServer(config) {
       });
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "run_nl_query",
     {
       title: titleOf("run_nl_query"),
@@ -552,7 +584,7 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "submit_fix_result",
     {
       title: titleOf("submit_fix_result"),
@@ -587,7 +619,7 @@ function createMushiServer(config) {
       return jsonText({ ok: true, fixId: created.fixId });
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "dispatch_fix",
     {
       title: titleOf("dispatch_fix"),
@@ -595,9 +627,20 @@ function createMushiServer(config) {
       annotations: annotationsFor("dispatch_fix"),
       inputSchema: {
         reportId: z.string().describe("Report UUID to fix"),
-        agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
+        agent: z.enum(["claude_code", "codex", "rest_worker", "mcp", "cursor_cloud"]).optional().describe('Override the agent adapter. Use "cursor_cloud" to dispatch a Cursor Cloud Agent that opens a signed draft PR.'),
+        backend: z.enum(["default", "claude_code", "cursor_cloud", "mcp"]).optional().describe("Alias for agent \u2014 prefer agent. When both are set, agent wins."),
+        cursorModel: z.string().optional().describe('Optional model override when agent=cursor_cloud (e.g. "composer-latest").'),
         idempotencyKey: z.string().uuid().optional().describe("Optional RFC 4122 UUID. Resend the same key to safely retry without dispatching a duplicate fix job (Idempotency-Key IETF draft)."),
         inventoryActionNodeId: z.string().uuid().optional().describe("Optional inventory Action node UUID for spec-traceability (\xA72.10). When provided, the fix-worker embeds the expected_outcome contract in the LLM prompt and runs validateAgainstSpec before opening the PR.")
+      },
+      // Typed write-tool result. fixId is the cursor for get_fix_timeline so
+      // downstream tools can chain without re-parsing the text payload.
+      outputSchema: {
+        fixId: z.string().describe("Newly created fix_attempt UUID"),
+        status: z.string().optional().describe("Initial status (queued, running, delegated, \u2026)"),
+        agentId: z.string().optional().describe("Cursor agent ID (bc-\u2026) when agent=cursor_cloud"),
+        runId: z.string().optional().describe("Cursor run ID when agent=cursor_cloud"),
+        prUrl: z.string().optional().describe("Draft PR URL when agent=cursor_cloud and auto_create_pr=true")
       }
     },
     async (args, extra) => {
@@ -615,20 +658,31 @@ function createMushiServer(config) {
         } catch {
         }
       }
-      const data = await apiCall("/v1/admin/fixes/dispatch", {
-        method: "POST",
-        headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
-        body: JSON.stringify({
-          reportId: args.reportId,
-          agent: args.agent,
-          inventoryActionNodeId: args.inventoryActionNodeId,
-          ...projectId ? { projectId } : {}
-        })
+      const resolvedAgent = args.agent ?? (args.backend !== "default" ? args.backend : void 0);
+      const data = await apiCall(
+        "/v1/admin/fixes/dispatch",
+        {
+          method: "POST",
+          headers: args.idempotencyKey ? { "Idempotency-Key": args.idempotencyKey } : void 0,
+          body: JSON.stringify({
+            reportId: args.reportId,
+            agent: resolvedAgent,
+            inventoryActionNodeId: args.inventoryActionNodeId,
+            ...args.cursorModel ? { cursorModel: args.cursorModel } : {},
+            ...projectId ? { projectId } : {}
+          })
+        }
+      );
+      return jsonResult({
+        fixId: data.fixId ?? "",
+        ...data.status ? { status: data.status } : {},
+        ...data.agentId ? { agentId: data.agentId } : {},
+        ...data.runId ? { runId: data.runId } : {},
+        ...data.prUrl ? { prUrl: data.prUrl } : {}
       });
-      return jsonText(data);
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "trigger_judge",
     {
       title: titleOf("trigger_judge"),
@@ -650,7 +704,7 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "test_gen_from_report",
     {
       title: titleOf("test_gen_from_report"),
@@ -671,7 +725,7 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
-  server.registerTool(
+  registerScopedTool(
     "transition_status",
     {
       title: titleOf("transition_status"),
@@ -715,7 +769,7 @@ function createMushiServer(config) {
       contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
     })
   );
-  server.registerTool(
+  registerScopedTool(
     "list_top_contributors",
     {
       title: titleOf("list_top_contributors"),
@@ -737,7 +791,7 @@ function createMushiServer(config) {
       }]
     })
   );
-  server.registerTool(
+  registerScopedTool(
     "award_bonus_points",
     {
       title: titleOf("award_bonus_points"),
@@ -764,7 +818,7 @@ function createMushiServer(config) {
       }]
     })
   );
-  server.registerTool(
+  registerScopedTool(
     "set_tier",
     {
       title: titleOf("set_tier"),
@@ -901,6 +955,9 @@ var log = createLogger({ scope: "mushi:mcp", level: "info" });
 var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "";
 var API_KEY = process.env.MUSHI_API_KEY ?? "";
 var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
+var SCOPES_RAW = process.env.MUSHI_SCOPES ?? "";
+var parsedScopes = SCOPES_RAW ? SCOPES_RAW.split(",").map((s) => s.trim()).filter((s) => s === "mcp:read" || s === "mcp:write") : ALL_SCOPES;
+var SCOPES = SCOPES_RAW && parsedScopes.length === 0 ? ALL_SCOPES : parsedScopes;
 async function main() {
   if (!API_KEY) {
     log.fatal("MUSHI_API_KEY environment variable is required");
@@ -916,12 +973,18 @@ async function main() {
       "[mushi-mcp] MUSHI_PROJECT_ID is not set.\n\nTools that scope to a project (get_recent_reports, get_report_detail,\nsearch_reports, etc.) will require you to pass projectId explicitly on\nevery call. To set it once and never pass it again:\n\n  1. Open the Mushi admin console \u2192 Projects\n     https://kensaur.us/mushi-mushi/projects\n  2. Click your project \u2014 copy the UUID below the project name.\n  3. Add it to your MCP env config:\n       MUSHI_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n\nOr visit Admin \u2192 MCP for a pre-filled config snippet with your actual UUID."
     );
   }
-  log.info("Starting Mushi MCP server", { version: VERSION, endpoint: API_ENDPOINT || "(unset)", hasProjectId: !!PROJECT_ID });
+  log.info("Starting Mushi MCP server", {
+    version: VERSION,
+    endpoint: API_ENDPOINT || "(unset)",
+    hasProjectId: !!PROJECT_ID,
+    scopes: SCOPES.join(",")
+  });
   const server = createMushiServer({
     version: VERSION,
     apiEndpoint: API_ENDPOINT,
     apiKey: API_KEY,
-    projectId: PROJECT_ID || void 0
+    projectId: PROJECT_ID || void 0,
+    scopes: SCOPES
   });
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -26,7 +26,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.2",
-    "@mushi-mushi/core": "^1.2.0"
+    "@mushi-mushi/core": "^1.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",
@@ -83,6 +83,7 @@
     "test:smoke": "node scripts/smoke-stdio.mjs",
     "test:localhost": "node scripts/localhost-e2e.mjs",
     "demo": "node scripts/demo-terminal-config.mjs",
+    "inspector": "npx --yes @modelcontextprotocol/inspector@latest node ./dist/index.js",
     "typecheck": "tsc --noEmit"
   }
 }