@mushi-mushi/mcp 0.16.0 → 0.16.2

package/CONTRIBUTING.md

@@ -27,12 +27,24 @@ pnpm build
 
 ```bash
 pnpm dev          # Start all dev servers (admin on :6464)
+```
+
+| Surface | URL |
+| --- | --- |
+| Admin console | http://localhost:6464 |
+| Docs site | http://localhost:3000 |
+| CLI console override | `MUSHI_CONSOLE_URL=http://localhost:6464` |
+
+```bash
 pnpm test         # Run Vitest across all packages
 pnpm typecheck    # TypeScript checks
 pnpm lint         # ESLint
 pnpm format       # Prettier
+pnpm smoke:cli-setup   # Playwright: onboarding ?setup=cli + success panel (skips headless if unsigned)
 ```
 
+Set `CLI_SETUP_SMOKE_STRICT=1` to fail the smoke script when Playwright is not signed in (CI gate).
+
 Ad-hoc screenshots captured during UI reviews can live temporarily at the repo
 root, but root-level `*.png` files are intentionally ignored. Canonical
 screenshots that should be versioned belong under `docs/screenshots/`.
@@ -58,9 +70,9 @@ packages/
   react-native/  React Native SDK (MIT)
   cli/           CLI tool (MIT)
   mcp/           MCP server for coding agents (MIT)
-  server/        Supabase Edge Functions (BSL)
-  agents/        Agentic fix pipeline (BSL)
-  verify/        Fix verification (BSL)
+  server/        Supabase Edge Functions (AGPLv3; ee/ is commercial)
+  agents/        Agentic fix pipeline (AGPLv3)
+  verify/        Fix verification (AGPLv3)
 apps/
   admin/         Admin dashboard (React + Tailwind)
   docs/          Documentation site (Nextra — apps/docs)
@@ -69,6 +81,18 @@ tooling/
   tsconfig/      Shared TypeScript configs
 ```
 
+## What we don't accept
+
+Knowing this upfront saves everyone time.
+
+- **Automated / bulk / AI-slop PRs** — any PR that was opened by a script, an LLM agent acting without meaningful human review, or as part of a parallel bounty-farming sweep is closed on sight. The commit history, branch name, or helper scripts included in the PR make this obvious.
+- **PRs that target the wrong base** — all PRs must branch from and target `master`. PRs targeting `main` or any other branch are closed (and will show an inflated diff that is not your work).
+- **One PR per issue, one issue per PR** — splitting or duplicating work just to collect acknowledgements isn't welcome.
+- **Good-first-issues without claiming first** — comment on the issue to claim it before starting. If two people open PRs for the same issue, the one that commented first is prioritised.
+- **Documentation-only PRs that merely duplicate existing content** — if the information already exists (e.g. in another file in this repo), adding a redundant copy adds noise without value.
+
+If a PR violates these policies it will be closed with a brief explanation. No hard feelings — a genuine contribution on the same issue is always welcome.
+
 ## Making Changes
 
 1. Create a feature branch from `master`
@@ -97,8 +121,10 @@ Guardrails (run locally before pushing):
 pnpm check:docs-stats          # root README stat badges
 pnpm check:sdk-version-matrix  # apps/docs/content/sdks/index.mdx versions
 pnpm check:internal-doc-links  # dead /foo links in MDX
+pnpm check:onboarding-drift    # phantom MCP env vars / stale tool names
 pnpm check:bundle-docs         # @mushi-mushi/web size-limit vs README
 pnpm gen:llms-txt              # regenerate apps/docs/public/llms.txt after nav changes
+pnpm gen:mcp-tools-doc         # regenerate sdks/mcp-tools.generated.mdx from catalog.ts
 ```
 
 README changes on npm packages only appear on [npmjs.com](https://www.npmjs.com) after the next **Changesets publish**.
@@ -115,13 +141,30 @@ Select the affected packages, the semver bump type, and write a summary. The cha
 
 ## Release flow
 
-Releases are fully automated. Maintainers don't run `npm publish` by hand.
+Releases are fully automated once the version PR is merged. Maintainers don't run
+`npm publish` by hand for routine bumps. See **[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)**
+for the full production runbook (edge functions, admin SPA, docs site, migrations).
 
 1. PRs land on `master` with one or more changeset files in `.changeset/`.
-2. `release.yml` runs on every push to `master`. It opens (or updates) a `chore: version packages` PR that bumps every affected `package.json`, rolls up the changelogs, and deletes the consumed changesets.
-3. Merging that "Version Packages" PR re-fires `release.yml`. The publish step authenticates to npm via **OpenID Connect (OIDC) Trusted Publishers** — no long-lived `NPM_TOKEN` is exchanged — and every tarball ships with a **Sigstore provenance attestation** uploaded to the public transparency log.
+   Orphaned changesets (only ignored packages) fail `pnpm check:changeset-orphans`.
+2. `release.yml` runs on every push to `master`. It opens (or updates) a
+   **`chore: version packages`** PR on `changeset-release/master` that bumps
+   affected `package.json` files, rolls up changelogs, and deletes consumed
+   changesets.
+3. **Wait for CI on the version PR.** If checks don't appear (bot-branch
+   suppression), push an empty commit to `changeset-release/master`. If
+   `check:sdk-version-matrix` fails, run `pnpm gen:sdk-version-matrix` on that
+   branch and commit `apps/docs/content/sdks/index.mdx`.
+4. Merge the version PR. The publish step uses **OIDC Trusted Publishers** +
+   Sigstore provenance (with `NPM_TOKEN` only for brand-new package bootstrap).
+5. **Manually dispatch Release** unless a run starts within ~2 minutes:
+   **Actions → Release → Run workflow → `master`**. Squash-merges attributed to
+   `github-actions[bot]` usually suppress the auto `push` trigger — manual
+   dispatch is the normal path, not a fallback of last resort.
 
-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**.
+```bash
+gh workflow run release.yml --ref master
+```
 
 ### Adding a brand-new publishable package
 
@@ -168,7 +211,7 @@ chore: bump dependencies
 ## License
 
 - SDK packages are MIT — your contributions will be MIT-licensed
-- Server/agents/verify are BSL 1.1 — contributions to those packages fall under BSL
+- Server/agents/verify are AGPLv3 — contributions to those packages fall under AGPLv3. A [commercial license](./COMMERCIAL-LICENSE.md) is available for hosted-SaaS use cases that cannot publish modifications. The `packages/server/ee/` directory is source-available but commercial (production use needs a license); contributions there are accepted under the same EE terms.
 
 ## Questions?
 

package/README.md

@@ -1,13 +1,8 @@
 # @mushi-mushi/mcp
 
-> **Sentry sees what code throws. Mushi sees what users feel — and closes the loop with AI.**
+> **Your AI wrote it. Mushi tells you why it broke.**
 
-[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
-```
+[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that wires Mushi into Cursor, Claude Code, and any MCP client. Pull fix context, run triage, and dispatch fixes without a second LLM vendor key.
 
 Wire it into Cursor, Claude Code, or any MCP client in one command:
 
@@ -16,7 +11,7 @@ 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.
+That command reads CLI config at **`~/.config/mushi/config.json`** (legacy `~/.mushirc` auto-migrates), writes `.cursor/mcp.json` with the `mushi-<slug>` server block, and prints "Done — restart Cursor and ask: `list mushi tools`". No copy-pasting environment variables.
 
 ### Codebase Understand tools (indexed repos)
 
@@ -146,7 +141,7 @@ The Mushi backend now exposes the same tool catalog over the **Streamable HTTP**
 
 ### Feature groups (`?features=` / `MUSHI_FEATURES`)
 
-Full catalog is **79 tools**. New installs default to a lean set via:
+Full catalog is **71 tools**. New installs default to a lean set via:
 
 - **Stdio:** `MUSHI_FEATURES=triage,fixes,inventory,setup,docs`
 - **HTTP:** `?features=triage,fixes,inventory,setup,docs` on the MCP URL

package/SECURITY.md

@@ -113,7 +113,7 @@ What we treat as in-scope attacker capabilities, and what we don't.
 | Compromised Supabase service-role key | ❌ | Treated as a tier-0 incident; would require key rotation and audit-log forensics. Not defendable in software. |
 | Compromise of `kensaurus@gmail.com` | ❌ | Treated as a project-fork event; downstream consumers should pin to the last known-good version and follow the new release channel. |
 | Physical / OS-level attacker on an end-user device | ❌ | Out of scope. |
-| Malicious fork using the Mushi name to ship malware | ❌ (technical) ✅ (legal) | The MIT/BSL grant lets the fork exist; the trademark policy (`TRADEMARK.md`) makes shipping it under the Mushi name an infringement we will pursue. |
+| Malicious fork using the Mushi name to ship malware | ❌ (technical) ✅ (legal) | The MIT / AGPLv3 grant lets the fork exist; the trademark policy (`TRADEMARK.md`) makes shipping it under the Mushi name an infringement we will pursue. |
 
 ## Data handling and PII
 

package/dist/catalog.js

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

package/dist/{chunk-PZEGN4XD.js → chunk-MM3IMFM4.js}

@@ -44,7 +44,7 @@ var TOOL_CATALOG = [
   {
     name: "get_fix_context",
     title: "Fix context bundle",
-    description: "Bundle the full context an agent needs to fix a bug: report detail, reproduction steps, component, root cause, ontology tags. One call instead of several.",
+    description: "Bundle the full context an agent needs to fix a bug: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, reproduction steps, component, root cause, and ontology tags. One call instead of several. No second LLM key needed.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me everything I need to fix this in one payload."
@@ -534,6 +534,15 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: 'Did "Add to Slack" work? Send a test ping to confirm.'
   },
+  // ── Billing / usage tools ─────────────────────────────────────────────────
+  {
+    name: "get_usage",
+    title: "Usage & billing summary",
+    description: 'Read-only diagnoses quota and billing summary for the current project: diagnoses used / limit / percentage, spend cap, period start/end, plan name, and whether the project is approaching or over its quota. Use this to answer "how many diagnoses do I have left?" or "am I close to my spend cap?".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: false },
+    useCase: "How many diagnoses do I have left this month?"
+  },
   // ── Skill Pipeline tools ─────────────────────────────────────────────────────
   {
     name: "list_skills",

package/dist/{chunk-B2QEG35D.js → chunk-ZX3XIJ7S.js}

@@ -10,6 +10,7 @@ var FEATURE_GROUPS = [
   "admin",
   "audit",
   "docs",
+  "usage",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];
@@ -82,6 +83,8 @@ var TOOL_FEATURE_MAP = {
   project_settings: "admin",
   privacy_status: "admin",
   evolution_history: "admin",
+  // usage / billing
+  get_usage: "usage",
   // qa / tdd
   map_user_stories: "qa",
   get_map_run_status: "qa",

package/dist/feature-groups.d.ts

@@ -4,7 +4,7 @@
  * When `features` is omitted → all tools (backward compatible).
  * New installs default to DEFAULT_FEATURE_GROUPS via deeplink / docs.
  */
-declare const FEATURE_GROUPS: readonly ["triage", "fixes", "inventory", "setup", "qa", "skills", "rewards", "admin", "audit", "docs", "legacy"];
+declare const FEATURE_GROUPS: readonly ["triage", "fixes", "inventory", "setup", "qa", "skills", "rewards", "admin", "audit", "docs", "usage", "legacy"];
 type FeatureGroup = (typeof FEATURE_GROUPS)[number];
 /** Lean default for new Cursor installs (~45 tools vs 70 full). */
 declare const DEFAULT_FEATURE_GROUPS: readonly FeatureGroup[];

package/dist/feature-groups.js

@@ -9,7 +9,7 @@ import {
   parseFeaturesCsv,
   parseFeaturesParam,
   toolMatchesFeatures
-} from "./chunk-B2QEG35D.js";
+} from "./chunk-ZX3XIJ7S.js";
 export {
   ALL_FEATURE_GROUPS,
   DEFAULT_FEATURE_GROUPS,

package/dist/index.js

@@ -51,7 +51,7 @@ var TOOL_CATALOG = [
   {
     name: "get_fix_context",
     title: "Fix context bundle",
-    description: "Bundle the full context an agent needs to fix a bug: report detail, reproduction steps, component, root cause, ontology tags. One call instead of several.",
+    description: "Bundle the full context an agent needs to fix a bug: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, reproduction steps, component, root cause, and ontology tags. One call instead of several. No second LLM key needed.",
     scope: "mcp:read",
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Give me everything I need to fix this in one payload."
@@ -457,6 +457,15 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: true },
     useCase: 'Did "Add to Slack" work? Send a test ping to confirm.'
   },
+  // ── Billing / usage tools ─────────────────────────────────────────────────
+  {
+    name: "get_usage",
+    title: "Usage & billing summary",
+    description: 'Read-only diagnoses quota and billing summary for the current project: diagnoses used / limit / percentage, spend cap, period start/end, plan name, and whether the project is approaching or over its quota. Use this to answer "how many diagnoses do I have left?" or "am I close to my spend cap?".',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: false },
+    useCase: "How many diagnoses do I have left this month?"
+  },
   // ── Skill Pipeline tools ─────────────────────────────────────────────────────
   {
     name: "list_skills",
@@ -603,6 +612,7 @@ var FEATURE_GROUPS = [
   "admin",
   "audit",
   "docs",
+  "usage",
   /** Deprecated aliases kept for one release — hidden unless `legacy` or `all`. */
   "legacy"
 ];
@@ -668,6 +678,8 @@ var TOOL_FEATURE_MAP = {
   project_settings: "admin",
   privacy_status: "admin",
   evolution_history: "admin",
+  // usage / billing
+  get_usage: "usage",
   // qa / tdd
   map_user_stories: "qa",
   get_map_run_status: "qa",
@@ -1131,6 +1143,7 @@ function createMushiServer(config) {
       inputSchema: { reportId: z.string().describe("The report UUID to fix") },
       outputSchema: {
         report: z.unknown(),
+        fixPrompt: z.unknown(),
         reproductionSteps: z.unknown(),
         component: z.unknown(),
         rootCause: z.unknown(),
@@ -1141,6 +1154,10 @@ function createMushiServer(config) {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       return jsonResult({
         report,
+        // Paste-ready fix prompt composed server-side by composeFixPacket()
+        // (diagnosis + repro + suggested fix + relevant code + blast radius).
+        // Hand this straight to the editing agent — no second LLM key needed.
+        fixPrompt: report.fix_packet ?? null,
         reproductionSteps: report.reproduction_steps ?? [],
         component: report.component,
         rootCause: report.stage2_analysis?.rootCause,
@@ -2694,6 +2711,23 @@ Be specific. No generic advice.`
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
+  server.registerTool(
+    "get_usage",
+    {
+      title: titleOf("get_usage"),
+      description: descOf("get_usage"),
+      annotations: annotationsFor("get_usage"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project ID. Defaults to the configured project.")
+      }
+    },
+    async ({ project_id }) => {
+      const pid = project_id ?? config.projectId;
+      const path = pid ? `/v1/admin/billing/stats?project_id=${pid}` : "/v1/admin/billing/stats";
+      const data = await apiCall(path);
+      return jsonText(data);
+    }
+  );
   server.registerTool(
     "list_skills",
     {
@@ -3015,6 +3049,32 @@ Be specific. No generic advice.`
       }
     }
   }
+  const _nativeFetch = globalThis.fetch;
+  let _firstToolCallSignalled = false;
+  const _signalFirstToolCall = () => {
+    if (_firstToolCallSignalled || !projectId) return;
+    _firstToolCallSignalled = true;
+    void _nativeFetch(`${apiEndpoint}/v1/cli/funnel`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mushi-Api-Key": apiKey,
+        "X-Mushi-Project": projectId
+      },
+      body: JSON.stringify({ event: "mcp_first_tool_call" }),
+      signal: AbortSignal.timeout(4e3)
+    }).catch(() => {
+    });
+  };
+  const llServer = server.server;
+  const existingToolsCallHandler = llServer?._requestHandlers?.get("tools/call");
+  if (typeof existingToolsCallHandler === "function") {
+    llServer._requestHandlers.set("tools/call", async (...args) => {
+      const result = await existingToolsCallHandler(...args);
+      _signalFirstToolCall();
+      return result;
+    });
+  }
   return server;
 }
 

package/dist/server.js

@@ -2,13 +2,13 @@ import {
   CODEBASE_TOOL_CATALOG,
   TDD_TOOL_CATALOG,
   TOOL_CATALOG
-} from "./chunk-PZEGN4XD.js";
+} from "./chunk-MM3IMFM4.js";
 import {
   MUSHI_SERVER_METADATA
 } from "./chunk-EHB2BGWX.js";
 import {
   toolMatchesFeatures
-} from "./chunk-B2QEG35D.js";
+} from "./chunk-ZX3XIJ7S.js";
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -409,6 +409,7 @@ function createMushiServer(config) {
       inputSchema: { reportId: z.string().describe("The report UUID to fix") },
       outputSchema: {
         report: z.unknown(),
+        fixPrompt: z.unknown(),
         reproductionSteps: z.unknown(),
         component: z.unknown(),
         rootCause: z.unknown(),
@@ -419,6 +420,10 @@ function createMushiServer(config) {
       const report = await apiCall(`/v1/admin/reports/${args.reportId}`);
       return jsonResult({
         report,
+        // Paste-ready fix prompt composed server-side by composeFixPacket()
+        // (diagnosis + repro + suggested fix + relevant code + blast radius).
+        // Hand this straight to the editing agent — no second LLM key needed.
+        fixPrompt: report.fix_packet ?? null,
         reproductionSteps: report.reproduction_steps ?? [],
         component: report.component,
         rootCause: report.stage2_analysis?.rootCause,
@@ -1972,6 +1977,23 @@ Be specific. No generic advice.`
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
+  server.registerTool(
+    "get_usage",
+    {
+      title: titleOf("get_usage"),
+      description: descOf("get_usage"),
+      annotations: annotationsFor("get_usage"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project ID. Defaults to the configured project.")
+      }
+    },
+    async ({ project_id }) => {
+      const pid = project_id ?? config.projectId;
+      const path = pid ? `/v1/admin/billing/stats?project_id=${pid}` : "/v1/admin/billing/stats";
+      const data = await apiCall(path);
+      return jsonText(data);
+    }
+  );
   server.registerTool(
     "list_skills",
     {
@@ -2293,6 +2315,32 @@ Be specific. No generic advice.`
       }
     }
   }
+  const _nativeFetch = globalThis.fetch;
+  let _firstToolCallSignalled = false;
+  const _signalFirstToolCall = () => {
+    if (_firstToolCallSignalled || !projectId) return;
+    _firstToolCallSignalled = true;
+    void _nativeFetch(`${apiEndpoint}/v1/cli/funnel`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Mushi-Api-Key": apiKey,
+        "X-Mushi-Project": projectId
+      },
+      body: JSON.stringify({ event: "mcp_first_tool_call" }),
+      signal: AbortSignal.timeout(4e3)
+    }).catch(() => {
+    });
+  };
+  const llServer = server.server;
+  const existingToolsCallHandler = llServer?._requestHandlers?.get("tools/call");
+  if (typeof existingToolsCallHandler === "function") {
+    llServer._requestHandlers.set("tools/call", async (...args) => {
+      const result = await existingToolsCallHandler(...args);
+      _signalFirstToolCall();
+      return result;
+    });
+  }
   return server;
 }
 export {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.16.0",
+  "mcpName": "io.github.kensaurus/mushi-mushi",
+  "version": "0.16.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",
@@ -41,15 +42,15 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.4.2",
-    "@mushi-mushi/core": "^1.15.0"
+    "zod": "^4.4.3",
+    "@mushi-mushi/core": "^1.20.0"
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
-    "eslint": "^10.3.0",
+    "@types/node": "^22.19.21",
+    "eslint": "^10.4.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
+    "vitest": "^4.1.8",
     "@mushi-mushi/eslint-config": "0.0.0"
   },
   "repository": {
@@ -57,8 +58,8 @@
     "url": "https://github.com/kensaurus/mushi-mushi.git",
     "directory": "packages/mcp"
   },
-  "author": "Kenji Sakuramoto",
-  "homepage": "https://github.com/kensaurus/mushi-mushi/tree/main/packages/mcp#readme",
+  "author": "Kenji Sakuramoto (https://bsky.app/profile/mushimushi.dev)",
+  "homepage": "https://kensaur.us/mushi-mushi",
   "bugs": {
     "url": "https://github.com/kensaurus/mushi-mushi/issues"
   },
@@ -93,6 +94,10 @@
   "engines": {
     "node": ">=20"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/kensaurus"
+  },
   "scripts": {
     "build": "tsup",
     "clean:types": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",