@mushi-mushi/mcp 0.6.0 → 0.9.0

package/README.md

@@ -1,18 +1,44 @@
-# @mushi-mushi/mcp
+# mushi-mcp
 
-[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi Mushi's closed-loop bug intelligence into your AI coding agent — so Cursor, Claude Code, Copilot, and any other MCP-compatible client can read classified reports, query the lesson library, and dispatch AI-generated fixes directly from the editor.
+> **Sentry sees what code throws. Mushi sees what users feel — and closes the loop with AI.**
 
-**The evolutionary angle:** the lesson library (`lessons.query` tool) is the agent's institutional memory. Every bug cluster your team has ever named is available to the agent before it touches a single line of code — so it doesn't repeat the same class of mistake the last agent made. That's the "cumulative selection" loop the [main README](https://www.npmjs.com/package/mushi-mushi) describes, delivered to your IDE.
+[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi's **evolution loop** into your AI coding agent. The loop is already running in your Mushi project:
+
+```
+User feels a bug → Mushi captures it → AI triages → AI opens a PR
+→ QA verifies → Judge scores → Lesson library remembers → next agent is smarter
+```
+
+Wire it into Cursor, Claude Code, or any MCP client in one command:
+
+```bash
+npx mushi-mushi setup --ide cursor
+# or: npx mushi-mushi setup --ide claude
+```
+
+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.
 
 > **What this is, and what it isn't**
 >
-> - **This package** is the MCP **server** — runs locally next to your editor, talks to the Mushi Mushi API, and presents bug reports as MCP tools/resources to your coding agent.
+> - **This package** (`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. The npm package name is `mushi-mcp`; the scoped alias `@mushi-mushi/mcp` still works.
 > - **`@mushi-mushi/agents`** ships the MCP **client adapter** — used by the autofix orchestrator when your project's `autofix_agent = 'mcp'`. See `packages/agents/src/adapters/mcp.ts`.
 > - The `generic_mcp` adapter shipped before V5.3 was a misnomer (it spoke plain REST). It is now `RestFixWorkerAgent`; the old export is kept as a deprecated alias for one more minor.
 
 ## Quick start
 
-### 1. With Claude Desktop
+### 0. One-liner (recommended)
+
+```bash
+# First: make sure you've logged in
+npx mushi-mushi login --api-key mushi_xxx --endpoint https://<ref>.supabase.co/functions/v1/api
+
+# Then wire your IDE
+npx mushi-mushi setup --ide cursor          # Cursor
+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)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 

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",
@@ -132,6 +129,15 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "What did Stage 2 say we should try for this report?"
   },
+  // --- Setup / admin -------------------------------------------------------
+  {
+    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 \u2014 or to validate that the onboarding wizard is complete.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is this project ready to auto-fix bugs? What is blocking me?"
+  },
   // --- Write / agentic ----------------------------------------------------
   {
     name: "submit_fix_result",
@@ -145,10 +151,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",
@@ -201,10 +207,20 @@ var TOOL_CATALOG = [
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "Manually promote this user to Champion tier as a thank-you."
+  },
+  {
+    name: "setup_repo_for_mushi",
+    title: "Bootstrap repo for Mushi",
+    description: "Writes the three Mushi bootstrap files into the current repo root: `.cursorrules` (Cursor evolution-loop coding rules), `.mushi/lessons.json` (initial empty lesson cache), and `MUSHI.md` (one-page project contract for agents). Idempotent \u2014 safe to re-run after lessons sync. Requires mcp:write scope. Call this once after connecting the repo; subsequently use `mushi sync-lessons` from CI to keep lessons current.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: false },
+    useCase: "Set up this repo for the Mushi evolution loop in one step."
   }
 ];
 
 // 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 +234,9 @@ var MushiApiError = class extends Error {
 function createMushiServer(config) {
   const { version, apiEndpoint, apiKey, projectId } = config;
   const doFetch = config.fetch ?? globalThis.fetch;
+  if (config.scopes !== void 0 && config.scopes.length === 0) {
+    return new McpServer({ name: "mushi-mushi", version });
+  }
   async function apiCall(path, options) {
     const res = await doFetch(`${apiEndpoint}${path}`, {
       ...options,
@@ -263,6 +282,12 @@ function createMushiServer(config) {
       content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
     };
   }
+  function jsonResult(value) {
+    return {
+      content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+      structuredContent: value
+    };
+  }
   const server = new McpServer({
     name: "mushi-mushi",
     version
@@ -300,6 +325,10 @@ 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)")
+      },
+      outputSchema: {
+        reports: z.array(z.unknown()),
+        total: z.number()
       }
     },
     async (args) => {
@@ -309,7 +338,7 @@ 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(data);
     }
   );
   server.registerTool(
@@ -332,6 +361,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.unknown())
       }
     },
     async (args) => {
@@ -344,7 +376,7 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -552,6 +584,43 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
+  server.registerTool(
+    "setup_check",
+    {
+      title: titleOf("setup_check"),
+      description: descOf("setup_check"),
+      annotations: annotationsFor("setup_check"),
+      inputSchema: {
+        projectId: z.string().optional().describe(
+          "Project UUID to check. Falls back to the projectId the server was initialised with."
+        )
+      }
+    },
+    async (args) => {
+      const resolvedId = args.projectId ?? projectId;
+      if (!resolvedId) {
+        return jsonText({
+          ok: false,
+          error: "No projectId provided and none configured on the MCP server. Pass projectId explicitly."
+        });
+      }
+      const data = await apiCall(`/v1/admin/projects/${resolvedId}/preflight`);
+      const summary = data.checks.map((c) => ({
+        check: c.key,
+        label: c.label,
+        passed: c.ready,
+        hint: c.hint,
+        fixPath: c.fixHref
+      }));
+      return jsonText({
+        ready: data.ready,
+        repoUrl: data.repoUrl ?? null,
+        checks: summary,
+        // Human-readable summary for agents that paste the result into a prompt
+        summary: data.ready ? `Project ${resolvedId} is ready to dispatch auto-fixes${data.repoUrl ? ` (target: ${data.repoUrl})` : ""}.` : `Project ${resolvedId} cannot dispatch yet \u2014 ${summary.filter((c) => !c.passed).map((c) => c.label).join(", ")}.`
+      });
+    }
+  );
   server.registerTool(
     "submit_fix_result",
     {
@@ -598,6 +667,10 @@ function createMushiServer(config) {
         agent: z.enum(["claude_code", "codex", "rest_worker", "mcp"]).optional().describe("Override the agent adapter"),
         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.")
+      },
+      outputSchema: {
+        fixId: z.string(),
+        status: z.string()
       }
     },
     async (args, extra) => {
@@ -625,7 +698,7 @@ function createMushiServer(config) {
           ...projectId ? { projectId } : {}
         })
       });
-      return jsonText(data);
+      return jsonResult(data);
     }
   );
   server.registerTool(
@@ -691,6 +764,26 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
+  server.registerTool(
+    "setup_repo_for_mushi",
+    {
+      title: titleOf("setup_repo_for_mushi"),
+      description: descOf("setup_repo_for_mushi"),
+      annotations: annotationsFor("setup_repo_for_mushi"),
+      inputSchema: {
+        projectId: z.string().optional().describe("Project UUID \u2014 defaults to configured project")
+      }
+    },
+    async (args) => {
+      const pid = args.projectId ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT", "projectId is required for setup_repo_for_mushi");
+      const data = await apiCall(`/v1/admin/projects/${pid}/repo/bootstrap`, {
+        method: "POST",
+        body: JSON.stringify({})
+      });
+      return jsonText(data);
+    }
+  );
   server.resource(
     "project_stats",
     "project://stats",
@@ -715,17 +808,15 @@ function createMushiServer(config) {
       contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
     })
   );
-  server.registerTool(
+  const rewardsMeta = (name) => annotationsFor(name);
+  server.tool(
     "list_top_contributors",
+    rewardsMeta("list_top_contributors").title,
     {
-      title: titleOf("list_top_contributors"),
-      description: descOf("list_top_contributors"),
-      inputSchema: {
-        limit: z.number().int().min(1).max(100).optional().default(10).describe("Max rows to return (default 10, max 100)"),
-        range: z.enum(["30d", "90d", "all"]).optional().default("30d").describe("Time window for points calculation")
-      },
-      annotations: annotationsFor("list_top_contributors")
+      limit: z.number().int().min(1).max(100).optional().default(10).describe("Max rows to return (default 10, max 100)"),
+      range: z.enum(["30d", "90d", "all"]).optional().default("30d").describe("Time window for points calculation")
     },
+    rewardsMeta("list_top_contributors"),
     async ({ limit, range }) => ({
       content: [{
         type: "text",
@@ -737,18 +828,15 @@ function createMushiServer(config) {
       }]
     })
   );
-  server.registerTool(
+  server.tool(
     "award_bonus_points",
+    rewardsMeta("award_bonus_points").title,
     {
-      title: titleOf("award_bonus_points"),
-      description: descOf("award_bonus_points"),
-      inputSchema: {
-        external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
-        points: z.number().int().min(1).max(5e4).describe("Bonus points to award (max 50,000 per call)"),
-        reason: z.string().max(200).describe("Human-readable reason, logged to end_user_activity")
-      },
-      annotations: annotationsFor("award_bonus_points")
+      external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
+      points: z.number().int().min(1).max(5e4).describe("Bonus points to award (max 50,000 per call)"),
+      reason: z.string().max(200).describe("Human-readable reason, logged to end_user_activity")
     },
+    rewardsMeta("award_bonus_points"),
     async ({ external_user_id, points, reason }) => ({
       content: [{
         type: "text",
@@ -764,18 +852,15 @@ function createMushiServer(config) {
       }]
     })
   );
-  server.registerTool(
+  server.tool(
     "set_tier",
+    rewardsMeta("set_tier").title,
     {
-      title: titleOf("set_tier"),
-      description: descOf("set_tier"),
-      inputSchema: {
-        external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
-        tier_slug: z.string().describe('Tier slug to assign, e.g. "champion", "contributor", "explorer"'),
-        reason: z.string().max(200).optional().describe("Optional reason for manual override")
-      },
-      annotations: annotationsFor("set_tier")
+      external_user_id: z.string().describe("The host-app user id as passed to Mushi.identify()"),
+      tier_slug: z.string().describe('Tier slug to assign, e.g. "champion", "contributor", "explorer"'),
+      reason: z.string().max(200).optional().describe("Optional reason for manual override")
     },
+    rewardsMeta("set_tier"),
     async ({ external_user_id, tier_slug, reason }) => ({
       content: [{
         type: "text",
@@ -791,6 +876,34 @@ function createMushiServer(config) {
       }]
     })
   );
+  server.resource(
+    "privacy_status",
+    "privacy://status",
+    {
+      description: "Returns the privacy posture for this project: storage region, LLM provider, whether BYOK is configured, data retention window, and last audit timestamp."
+    },
+    async () => ({
+      contents: [{
+        uri: "privacy://status",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/privacy/status"), null, 2)
+      }]
+    })
+  );
+  server.resource(
+    "evolution_history",
+    "evolution://history",
+    {
+      description: "Returns the project's last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling."
+    },
+    async () => ({
+      contents: [{
+        uri: "evolution://history",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/evolution/history"), null, 2)
+      }]
+    })
+  );
   server.resource(
     "project_integration_health",
     "project://integration-health",
@@ -891,6 +1004,15 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
       }]
     })
   );
+  const grantedScopes = config.scopes;
+  if (grantedScopes !== void 0) {
+    const toolRegistry = server._registeredTools;
+    for (const spec of TOOL_CATALOG) {
+      if (!grantedScopes.includes(spec.scope)) {
+        toolRegistry[spec.name]?.remove();
+      }
+    }
+  }
   return server;
 }
 
@@ -901,6 +1023,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 +1041,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.9.0",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -23,18 +23,30 @@
     "CODE_OF_CONDUCT.md",
     "SECURITY.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "clean:types": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "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"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.2",
-    "@mushi-mushi/core": "^1.2.0"
+    "@mushi-mushi/core": "workspace:^",
+    "zod": "^4.4.2"
   },
   "devDependencies": {
+    "@mushi-mushi/eslint-config": "workspace:*",
     "@types/node": "^22.19.17",
     "eslint": "^10.3.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "@mushi-mushi/eslint-config": "0.0.0"
+    "vitest": "^4.1.5"
   },
   "repository": {
     "type": "git",
@@ -73,16 +85,5 @@
   ],
   "engines": {
     "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsup",
-    "clean:types": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "dev": "tsup --watch",
-    "lint": "eslint src/",
-    "test": "vitest run",
-    "test:smoke": "node scripts/smoke-stdio.mjs",
-    "test:localhost": "node scripts/localhost-e2e.mjs",
-    "demo": "node scripts/demo-terminal-config.mjs",
-    "typecheck": "tsc --noEmit"
   }
-}
+}