@mushi-mushi/mcp 0.4.0 → 0.6.0

package/CONTRIBUTING.md

@@ -91,6 +91,33 @@ pnpm changeset
 
 Select the affected packages, the semver bump type, and write a summary. The changeset file gets committed with your PR.
 
+## Release flow
+
+Releases are fully automated. Maintainers don't run `npm publish` by hand.
+
+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.
+
+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**.
+
+### 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.
+
+1. Add the package under `packages/<name>/` with a real `version`, `files`, `publishConfig.access: "public"`, `LICENSE`, and the standard fields enforced by `pnpm check:publish-readiness`.
+2. Build it locally: `pnpm install && pnpm -r build`.
+3. Mint a short-lived granular access token at `https://www.npmjs.com/settings/<your-user>/tokens/granular-access-tokens/new` — **Bypass 2FA: ON**, **Read and write: All packages**, **Expiration: 7 days**.
+4. Bootstrap-publish:
+   ```bash
+   NPM_TOKEN=npm_xxx pnpm bootstrap:new-package
+   ```
+   The script auto-detects which workspace packages are missing on npm and publishes them via `pnpm publish --no-provenance` (so `workspace:^` specifiers get rewritten to real semver in the tarball).
+5. The script prints one URL per freshly-published package. Open each, click **GitHub Actions** under "Trusted Publisher", confirm the auto-filled fields (`<owner>` / `<repo>` / `release.yml`), and tap your security key.
+6. Revoke the bootstrap token at `https://www.npmjs.com/settings/<your-user>/tokens`.
+
+From the next changeset bump onward, that package publishes through the normal `release.yml` flow with full OIDC provenance — same as the rest.
+
 ## Code Style
 
 - **TypeScript strict mode** — no `any` unless absolutely necessary

package/README.md

@@ -1,6 +1,8 @@
 # @mushi-mushi/mcp
 
-[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that exposes Mushi Mushi reports, fixes, and project state to coding agents (Claude Code, Cursor, Codex, Continue, Cline, Zed, Windsurf, and any other MCP-compatible client).
+[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.
+
+**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.
 
 > **What this is, and what it isn't**
 >
@@ -21,9 +23,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
       "command": "npx",
       "args": ["-y", "@mushi-mushi/mcp@latest"],
       "env": {
-        "MUSHI_API_KEY": "key_xxx",
-        "MUSHI_PROJECT_ID": "proj_xxx",
-        "MUSHI_API_ENDPOINT": "https://api.mushimushi.dev"
+        "MUSHI_API_KEY": "mushi_xxxxxxxxxxxxxxxxxxxx",
+        "MUSHI_PROJECT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        "MUSHI_API_ENDPOINT": "https://<your-ref>.supabase.co/functions/v1/api"
       }
     }
   }
@@ -32,6 +34,13 @@ 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_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
+>
+> Or visit **Admin → MCP** in the console for a one-click pre-filled config snippet.
+
 ### 2. With Cursor
 
 In Cursor settings, open **MCP** → **Add new MCP server** and paste:
@@ -40,12 +49,22 @@ In Cursor settings, open **MCP** → **Add new MCP server** and paste:
 npx -y @mushi-mushi/mcp@latest
 ```
 
-Set the same three env vars (`MUSHI_API_KEY`, `MUSHI_PROJECT_ID`, optional `MUSHI_API_ENDPOINT`).
+Then set the same three environment variables:
+
+| Variable | Where to find it |
+|---|---|
+| `MUSHI_API_KEY` | Admin console → Settings → API Keys |
+| `MUSHI_PROJECT_ID` | Admin console → Projects → click project → UUID below the name |
+| `MUSHI_API_ENDPOINT` | Admin console → Settings → API Keys (shown alongside your key) |
+
+Without `MUSHI_PROJECT_ID` the server starts but scoped tools return an empty result with a message pointing you here.
 
 ### 3. From the command line
 
 ```bash
-MUSHI_API_KEY=key_xxx MUSHI_PROJECT_ID=proj_xxx npx -y @mushi-mushi/mcp@latest
+MUSHI_API_KEY=mushi_xxxxxxxxxxxxxxxxxxxx \
+MUSHI_PROJECT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
+npx -y @mushi-mushi/mcp@latest
 ```
 
 The server speaks stdio MCP transport by default — your client launches it as a subprocess.
@@ -59,10 +78,10 @@ The Mushi backend now exposes the same tool catalog over the **Streamable HTTP**
 {
   "mcpServers": {
     "mushi-mushi-hosted": {
-      "url": "https://api.mushimushi.dev/functions/v1/mcp",
+      "url": "https://<your-ref>.supabase.co/functions/v1/mcp",
       "headers": {
-        "X-Mushi-Api-Key": "mushi_live_…",
-        "X-Mushi-Project-Id": "proj_…"
+        "X-Mushi-Api-Key": "mushi_xxxxxxxxxxxxxxxxxxxx",
+        "X-Mushi-Project": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       }
     }
   }

package/dist/index.js

@@ -176,6 +176,31 @@ var TOOL_CATALOG = [
     // client prompts the user on every call.
     hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Dismiss this duplicate / mark it fixed."
+  },
+  // --- Rewards (P3) -------------------------------------------------------
+  {
+    name: "list_top_contributors",
+    title: "Top contributors leaderboard",
+    description: "Return the top N contributors for the organization, ranked by points in a time window (30d | 90d | all). Each row includes display name, tier, total points, report count, and anti-fraud flag. Use this to identify your most engaged power users, write them a thank-you message, or decide who deserves a bonus.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Who are my top 10 contributors this month?"
+  },
+  {
+    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.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, 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.`,
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    useCase: "Manually promote this user to Champion tier as a thank-you."
   }
 ];
 
@@ -690,6 +715,82 @@ function createMushiServer(config) {
       contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
     })
   );
+  server.registerTool(
+    "list_top_contributors",
+    {
+      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")
+    },
+    async ({ limit, range }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(
+          await apiCall(`/v1/admin/rewards/leaderboard?range=${range}&limit=${limit}`),
+          null,
+          2
+        )
+      }]
+    })
+  );
+  server.registerTool(
+    "award_bonus_points",
+    {
+      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")
+    },
+    async ({ external_user_id, points, reason }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(
+          await apiCall("/v1/admin/rewards/bonus-points", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ external_user_id, points, reason })
+          }),
+          null,
+          2
+        )
+      }]
+    })
+  );
+  server.registerTool(
+    "set_tier",
+    {
+      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")
+    },
+    async ({ external_user_id, tier_slug, reason }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(
+          await apiCall("/v1/admin/rewards/set-tier", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ external_user_id, tier_slug, reason })
+          }),
+          null,
+          2
+        )
+      }]
+    })
+  );
   server.resource(
     "project_integration_health",
     "project://integration-health",
@@ -810,6 +911,11 @@ async function main() {
       "[mushi-mcp] MUSHI_API_ENDPOINT is not set. All tool calls will fail.\nSet MUSHI_API_ENDPOINT to your Supabase edge function URL, e.g. https://xyz.supabase.co/functions/v1/api"
     );
   }
+  if (!PROJECT_ID) {
+    console.error(
+      "[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 });
   const server = createMushiServer({
     version: VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -24,16 +24,16 @@
     "SECURITY.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^4.3.6",
-    "@mushi-mushi/core": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.2",
+    "@mushi-mushi/core": "^1.2.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "eslint": "^10.2.0",
-    "tsup": "^8.4.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4",
+    "@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"
   },
   "repository": {