@mushi-mushi/mcp 0.3.8 → 0.4.0

package/README.md

@@ -50,6 +50,27 @@ MUSHI_API_KEY=key_xxx MUSHI_PROJECT_ID=proj_xxx npx -y @mushi-mushi/mcp@latest
 
 The server speaks stdio MCP transport by default — your client launches it as a subprocess.
 
+### 4. Hosted Streamable HTTP (no subprocess) — 2026-05-09 release
+
+The Mushi backend now exposes the same tool catalog over the **Streamable HTTP** transport from the MCP 2025-03-26 spec at `/functions/v1/mcp`. Use this when you want to skip the local subprocess — typical for OpenAI Agents SDK, ChatGPT Agent, hosted CrewAI, or any orchestrator that talks remote MCP:
+
+```jsonc
+// .cursor/mcp.json — example
+{
+  "mcpServers": {
+    "mushi-mushi-hosted": {
+      "url": "https://api.mushimushi.dev/functions/v1/mcp",
+      "headers": {
+        "X-Mushi-Api-Key": "mushi_live_…",
+        "X-Mushi-Project-Id": "proj_…"
+      }
+    }
+  }
+}
+```
+
+The endpoint accepts JSON-RPC 2.0 over POST (returns `application/json` or `text/event-stream` per content negotiation), opens an SSE stream on GET for server-pushed notifications, and accepts DELETE for session termination. Auth is the same dual-mode API-key / JWT used everywhere else on `/v1/admin/*`.
+
 ## Tools
 
 ### Read
@@ -188,9 +209,10 @@ Honest scorecard against the MCP 2025-10 spec:
 - ✅ **Progress notifications** — wired on `dispatch_fix` (the one genuinely long-running call). Sends `notifications/progress` the moment the orchestrator accepts the job.
 - ✅ **Scope-aware errors** — `[INSUFFICIENT_SCOPE]` surfaces verbatim so agents don't silently retry.
 - ✅ **Stdio transport** — default for local editor integration.
+- ✅ **Streamable HTTP transport (2025-03-26 spec)** — hosted at `/functions/v1/mcp` on the Mushi backend; same tool catalog, no local subprocess. The previous "⏳" entry shipped in the 2026-05-09 release.
+- ✅ **Spec traceability for `dispatch_fix`** — the `dispatch_fix` tool input schema now accepts `inventoryActionNodeId`, and `get_fix_context` surfaces the inventory `Action` (with `expected_outcome`) the report was classified against. External orchestrators can read the contract before drafting a fix and pass the anchor back at dispatch time.
 - ⏳ **Resource subscriptions / `notifications/resources/list_changed`** — the spec supports live-updating resources (e.g. dashboard numbers that push rather than poll). Worth adding once Cursor + Claude Desktop both ship client support (currently patchy).
 - ⏳ **Sampling / elicitation** — letting the server ask the client to run an LLM call (e.g. to draft a commit message from the fix context). Not yet wired; would let us move some orchestrator LLM spend from server-side to the user's own subscription.
-- ⏳ **Streamable HTTP transport** — the spec's alternative to stdio for remote hosting. Relevant if we ever host the MCP server on behalf of customers; irrelevant for the local-install path that 95% of users want.
 
 If you want a feature from the "⏳" column, open an issue — we're holding them back on "MCP client support has shipped in ≥2 major clients", not on implementation effort.
 

package/SECURITY.md

@@ -19,15 +19,59 @@ If you discover a security vulnerability, please report it responsibly.
 
 **Do NOT open a public GitHub issue.**
 
-Instead, email: **kensaurus@gmail.com**
+Use either channel below:
+
+1. **GitHub Private Vulnerability Reporting** — strongly preferred.
+   <https://github.com/kensaurus/mushi-mushi/security/advisories/new>
+   Routes the report into a private advisory with built-in CVE issuance,
+   patch coordination, and contributor-credit workflow.
+2. **Email** — `kensaurus@gmail.com`, subject prefix `[mushi-security]`.
+   PGP welcome but not required.
 
 Include:
 - Description of the vulnerability
-- Steps to reproduce
-- Impact assessment
+- Steps to reproduce (smallest reproducer wins)
+- Impact assessment (what an attacker gains)
 - Suggested fix (if any)
+- Whether you want public credit (and how to spell your name)
+
+### Coordinated-disclosure timeline
+
+| Day | Action |
+|-----|--------|
+| 0 | Report received |
+| ≤ 2 | Acknowledgment + assigned a tracking ID |
+| ≤ 7 | Triage complete: severity assigned (CVSS 3.1) and target patch date communicated |
+| ≤ 30 | Patch released for critical / high (CVSS ≥ 7.0); ≤ 60 days for medium; best-effort for low |
+| Patch + 7 | Public advisory + CVE published; reporter credited unless they declined |
+| Patch + 90 | Embargo expires regardless; if upstream is unresponsive, the reporter is free to publish |
+
+### Safe harbor
+
+Good-faith security research on Mushi Mushi is welcome. If you stay
+within the rules below, we will not pursue legal action, will not ask
+your hosting provider to take you offline, and will publicly credit your
+work:
+
+- Test only against your own self-hosted instance, the public demo at
+  <https://kensaur.us/mushi-mushi/admin/>, or accounts you own.
+- Do not access, exfiltrate, or modify data belonging to other users.
+- Do not run automated scanning that affects availability for others
+  (rate-limit your tooling, exclude `/health`).
+- Disclose privately first (channels above); do not publish before the
+  embargo above expires.
+- Do not intentionally exploit a finding to escalate beyond proving it
+  exists.
+
+If a finding requires touching production data to confirm, **stop and
+ask first** — describe what you'd need to do and we'll spin up a sandbox.
+
+### Hall of fame
 
-We will acknowledge receipt within 48 hours and aim to release a patch within 7 days for critical issues.
+Researchers who report a confirmed vulnerability are credited in the
+release notes for the patched version and added to
+[`docs/SECURITY_HALL_OF_FAME.md`](./docs/SECURITY_HALL_OF_FAME.md) (with
+permission).
 
 ## Scope
 
@@ -48,6 +92,125 @@ We will acknowledge receipt within 48 hours and aim to release a patch within 7
 - **Rotate API keys** regularly via the admin console
 - **Enable SSO** for team projects (Enterprise tier)
 - **Review audit logs** periodically for suspicious activity
+- **Verify SDK integrity** with `npm audit signatures` after install
+- **Set `Content-Security-Policy`** on any page embedding the Mushi widget;
+  the widget itself ships with `script-src 'self'` and does not load
+  remote scripts.
+
+## Threat model
+
+What we treat as in-scope attacker capabilities, and what we don't.
+
+| Capability | In scope | Notes |
+|-----------|----------|-------|
+| Unauthenticated network attacker hitting public endpoints | ✅ | Rate-limit + HMAC + replay protection on every webhook endpoint (`packages/server/supabase/functions/_shared/webhook-middleware.ts`). |
+| Authenticated user trying to read another tenant's data | ✅ | Postgres RLS on every `public.*` table; advisor lints reviewed monthly. |
+| Authenticated user trying to escalate to super-admin | ✅ | Role lives in `auth.users.raw_app_meta_data.role`; cannot be self-edited via PostgREST. |
+| Compromised dependency (npm supply-chain attack) | ✅ | 7-day cooldown + provenance + Harden-Runner + pinned SHAs (see "Supply-chain hardening" below). |
+| Stolen API key | ✅ | Per-key scopes (`api_key_has_scope`), revocation via admin console, audit log of every use. |
+| User pasting a Stripe / OpenAI / GitHub PAT into a bug report | ✅ | PII scrubber redacts ~15 vendor token formats client-side before the report leaves the device. Mirrors `packages/core/src/pii-scrubber.ts` across iOS, Android, Flutter, React Native. |
+| Stolen end-user device with the SDK installed | ⚠️ partial | Offline queue is AsyncStorage / Keychain / SharedPreferences — no app-level encryption beyond the OS default. Reports waiting to flush are vulnerable to a forensic attacker. |
+| 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. |
+
+## Data handling and PII
+
+### What the SDK collects by default
+
+| Field | Scope | PII risk |
+|-------|-------|----------|
+| URL / route the user was on | Always | Low — strip query strings if your routes encode user IDs. |
+| Browser / OS / device | Always | None |
+| Console errors (last 50) | Opt-in via `captureConsole: true` | Medium — can include user data your code logs. |
+| Network failures (URL + status) | Opt-in via `captureNetwork: true` | Medium — query params logged as-is unless you redact in-app. |
+| User id / email / role | Only if you call `setUser()` | High — only set what you need; we do not auto-discover. |
+| Session replay frames | Off by default | High — handled by the masking layer; passwords / cards / opted-out elements never leave the page. |
+| Free-text bug description | Always | Medium — passed through the PII scrubber (see below). |
+
+### What the PII scrubber redacts before send
+
+Implemented identically across `@mushi-mushi/core`, the iOS, Android,
+Flutter, and React Native SDKs. Defaults are below — every category can
+be toggled off, but `secretTokens` is on by default and we recommend
+keeping it that way.
+
+| Category | Default | Patterns |
+|----------|---------|----------|
+| `ssns` | on | `123-45-6789` |
+| `creditCards` | on | 12–19 digit Luhn-shaped sequences with optional separators |
+| `secretTokens` | on | AWS access key (`AKIA…` / `ASIA…`), AWS secret (`aws_secret_access_key=…`), Stripe (`sk_live_…`, `sk_test_…`, `rk_…`, `pk_…`), Slack (`xox[abpor]-…`), GitHub PAT (`ghp_…`, `github_pat_…`), OpenAI (`sk-…`, `sk-proj-…`), Anthropic (`sk-ant-…`), Google API (`AIza…`), JWT (`eyJ…` 3-segment) |
+| `emails` | on | RFC-5322 lite |
+| `phones` | on | E.164 with optional country code |
+| `ipAddresses` | off | IPv4 (off because internal IPs are usually not PII and noise hurts triage) |
+| `ipv6` | off | Same |
+
+The fields scrubbed are:
+
+- `description` — primary free-text field of every bug report
+- `summary` — short summary, in the same composer
+- `breadcrumbs[].message` — auto-captured user-action trail (clicks, route changes, console messages)
+
+Structured fields you set explicitly (`metadata.userEmail`,
+`metadata.userId`, etc.) are intentionally **not** scrubbed — those are
+opt-in attribution data, and silently rewriting them would break
+support workflows.
+
+### Where data lives
+
+- **Reports & telemetry** — Supabase Postgres in the `us-west-1` region.
+- **Session replays** — Supabase Storage, same region. Lifecycle policy
+  trims replays older than 30 days unless explicitly retained from the
+  admin console.
+- **Inbound webhook bodies** — only a SHA-256 hash + `delivery_id` of
+  the body is persisted (`webhook_audit_log`). The full body is
+  processed in memory and discarded.
+- **Outbound integrations** (Slack, Jira, …) — Mushi is a sender only;
+  the receiving system's retention applies.
+
+### Encryption
+
+| Surface | At rest | In transit |
+|---------|---------|------------|
+| Postgres (Supabase) | AES-256 (Supabase default) | TLS 1.2+ |
+| Supabase Storage (replays) | AES-256 | TLS 1.2+ |
+| Edge Function ↔ Postgres | — | TLS via the Supavisor pooler |
+| SDK ↔ ingest endpoint | — | TLS 1.2+ enforced; HSTS preload on `kensaur.us` |
+| Inbound webhooks | — | TLS terminated at CloudFront / Supabase edge |
+| Audit log integrity | append-only by RLS; no in-row signing | — |
+
+### Cryptographic primitives
+
+| Use | Algorithm | Implementation |
+|-----|-----------|---------------|
+| Webhook HMAC verification (Sentry, GitHub, Datadog, Honeycomb, Grafana, Bugsnag, Rollbar, Crashlytics) | HMAC-SHA256, constant-time compare | Web Crypto in Deno; `crypto.subtle.timingSafeEqual` analogue |
+| AWS SNS subscription confirmation | RSA-SHA1 / RSA-SHA256 | Deno `crypto.subtle.verify` with the cert from `SigningCertURL` (URL allow-listed to `*.sns.*.amazonaws.com`) |
+| Opsgenie JWT shared-token | HS256 with `aud` claim verification | `jose` (Deno-compatible) |
+| API-key hashing (database) | SHA-256 prefix + bcrypt secret half | `pgcrypto` |
+| Provenance attestations (npm) | Sigstore (Fulcio + Rekor) | `npm publish --provenance` |
+
+We deliberately do not roll our own crypto. If you find an algorithm or
+library above that has been deprecated, please file a security advisory.
+
+### Operator security checklist
+
+When you provision a new self-hosted Mushi instance:
+
+- [ ] Set `auth_leaked_password_protection = true` in Supabase Auth
+      (HaveIBeenPwned blocklist; flagged as `auth_leaked_password_protection`
+      in the security advisor).
+- [ ] Enable at least two MFA factors in Supabase Auth (`auth_insufficient_mfa_options`).
+- [ ] Rotate the service-role key on day 1, then quarterly.
+- [ ] Restrict Postgres direct connections to your CI / migration runners
+      via Supabase network restrictions.
+- [ ] Run `pnpm dlx supabase advisors --project-ref <ref>` after every
+      migration; aim for zero ERROR-level findings.
+- [ ] Configure a Supabase log drain to your SIEM if you are subject to
+      SOC 2 / ISO 27001.
+- [ ] Set CSP `frame-ancestors` on the host page if you embed the Mushi
+      widget (the widget is iframe-friendly but does not enforce
+      framing constraints itself).
 
 ## Supply-chain hardening (how this package is protected)
 

package/dist/index.js

@@ -570,7 +570,9 @@ 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"]).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.")
       }
     },
     async (args, extra) => {
@@ -590,9 +592,11 @@ function createMushiServer(config) {
       }
       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 } : {}
         })
       });
@@ -686,6 +690,37 @@ function createMushiServer(config) {
       contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
     })
   );
+  server.resource(
+    "project_integration_health",
+    "project://integration-health",
+    {
+      description: "Live health status of every configured BYOK channel (Sentry, GitHub, LangFuse, PagerDuty, \u2026). Orchestrators should check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run."
+    },
+    async () => ({
+      contents: [{
+        uri: "project://integration-health",
+        mimeType: "application/json",
+        text: JSON.stringify(await apiCall("/v1/admin/integrations/health"), null, 2)
+      }]
+    })
+  );
+  server.resource(
+    "inventory_current",
+    "inventory://current",
+    {
+      description: "Current inventory snapshot for the active project \u2014 all Action nodes with their spec contract (expected_outcome), build-gate status, linked reports, and fix attempts. Subscribe to this resource to receive notifications/resources/updated when the inventory is re-crawled (e.g. after a PR merge or manual trigger). Orchestrators can use this to enumerate work items and pick the next Action to fix."
+    },
+    async () => {
+      const path = projectId ? `/v1/admin/inventory/${projectId}` : "/v1/admin/inventory";
+      return {
+        contents: [{
+          uri: "inventory://current",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall(path), null, 2)
+        }]
+      };
+    }
+  );
   server.prompt(
     "summarize_report_for_fix",
     "Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. Use before asking an agent to write the patch.",
@@ -762,7 +797,7 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
 var require2 = createRequire(import.meta.url);
 var VERSION = require2("../package.json").version;
 var log = createLogger({ scope: "mushi:mcp", level: "info" });
-var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "https://api.mushimushi.dev";
+var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "";
 var API_KEY = process.env.MUSHI_API_KEY ?? "";
 var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
 async function main() {
@@ -770,7 +805,12 @@ async function main() {
     log.fatal("MUSHI_API_KEY environment variable is required");
     process.exit(1);
   }
-  log.info("Starting Mushi MCP server", { version: VERSION, endpoint: API_ENDPOINT, hasProjectId: !!PROJECT_ID });
+  if (!API_ENDPOINT) {
+    console.error(
+      "[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"
+    );
+  }
+  log.info("Starting Mushi MCP server", { version: VERSION, endpoint: API_ENDPOINT || "(unset)", hasProjectId: !!PROJECT_ID });
   const server = createMushiServer({
     version: VERSION,
     apiEndpoint: API_ENDPOINT,
@@ -779,6 +819,36 @@ async function main() {
   });
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  if (PROJECT_ID && API_ENDPOINT) {
+    let lastInventoryAt = null;
+    const POLL_INTERVAL_MS = 6e4;
+    const pollInventory = async () => {
+      try {
+        const res = await fetch(`${API_ENDPOINT}/v1/admin/inventory/${PROJECT_ID}`, {
+          headers: {
+            "X-Mushi-Api-Key": API_KEY,
+            "X-Mushi-Project": PROJECT_ID
+          },
+          signal: AbortSignal.timeout(1e4)
+        });
+        if (!res.ok) return;
+        const data = await res.json();
+        const updatedAt = data?.data?.updatedAt ?? null;
+        if (updatedAt && updatedAt !== lastInventoryAt) {
+          if (lastInventoryAt !== null) {
+            await server.server.sendResourceUpdated({ uri: "inventory://current" });
+            log.info("inventory://current updated \u2014 notified subscribers", { updatedAt });
+          }
+          lastInventoryAt = updatedAt;
+        }
+      } catch {
+      }
+    };
+    void pollInventory();
+    setInterval(() => {
+      void pollInventory();
+    }, POLL_INTERVAL_MS);
+  }
 }
 main().catch((err) => {
   log.fatal("MCP server crashed", { err: String(err) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -26,7 +26,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^4.3.6",
-    "@mushi-mushi/core": "^0.9.0"
+    "@mushi-mushi/core": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",