@mushi-mushi/mcp 0.4.0 → 0.5.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/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://your-admin-url/projects)\n  2. Find your project \u2014 the UUID chip below the name is the value to use.\n  3. Copy it and set:\n       MUSHI_PROJECT_ID=<paste-uuid-here>\n\nYou can also visit Admin \u2192 MCP for a pre-filled .env.local snippet."
+    );
+  }
   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.5.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.1.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": {