@mushi-mushi/mcp 0.12.0 → 0.13.1

package/README.md

@@ -132,6 +132,8 @@ The endpoint accepts JSON-RPC 2.0 over POST (returns `application/json` or `text
 | `get_knowledge_graph` | Traverse the knowledge graph from a seed component or page |
 | `setup_check` | The 4 **dispatch-readiness** checks (GitHub repo, codebase indexed, Anthropic key, autofix enabled) — run before `dispatch_fix` |
 | `ingest_setup_check` | The 4 **required ingest** checks (project, active API key, SDK heartbeat, first report) + `last_sdk_seen_at` diagnostics — run after wiring env vars to confirm the SDK is reporting |
+| `get_activation_status` | Unified setup posture for the active project — required steps, SDK heartbeat, dispatch preflight, and the next best action. Run first when a user says setup is broken |
+| `get_reporter_thread` | Unified report timeline — the reporter/admin comment thread (including verify/reopen signals) plus fix, QA, and status lanes. Use when triaging whether an end user still sees a bug as unfixed |
 
 ### Write / agentic
 

package/dist/index.js

@@ -24,6 +24,14 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Show me everything you know about this report."
   },
+  {
+    name: "get_report_timeline",
+    title: "Unified report timeline",
+    description: "Ordered timeline merging reporter comments, fix events, QA runs, skill pipeline steps, and Ask Mushi turns for one report.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What happened on this report thread end-to-end?"
+  },
   {
     name: "search_reports",
     title: "Search reports",
@@ -146,6 +154,14 @@ var TOOL_CATALOG = [
     hints: { readOnly: true, idempotent: true, openWorld: true },
     useCase: "Is the SDK installed and ingesting reports? Why is my banner still missing?"
   },
+  {
+    name: "diagnose_connection",
+    title: "Connection diagnose (CLI + MCP + SDK)",
+    description: `Validate the MCP server credentials (endpoint, API key, projectId), ping /health, run ingest-setup and dispatch preflight, and return the single best next action when anything fails. Use when the user asks "why aren't my reports showing up?".`,
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Why is my Mushi setup broken \u2014 what exact step should I fix next?"
+  },
   // --- Write / agentic ----------------------------------------------------
   {
     name: "submit_fix_result",
@@ -183,14 +199,35 @@ var TOOL_CATALOG = [
   {
     name: "transition_status",
     title: "Move report between states",
-    description: "Move a report between workflow states (new \u2192 classified \u2192 grouped \u2192 fixing \u2192 fixed \u2192 dismissed). Enforces the same transition rules as the admin UI.",
+    description: "Move a report between workflow states (new \u2192 classified \u2192 grouped \u2192 fixing \u2192 fixed \u2192 verified \u2192 reopened \u2192 dismissed). Enforces the same transition rules as the admin UI.",
     scope: "mcp:write",
-    // Transitioning to `dismissed` is destructive by intent — it removes the
-    // report from triage queues. Flag the whole tool as destructive so the
-    // client prompts the user on every call.
     hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
     useCase: "Dismiss this duplicate / mark it fixed."
   },
+  {
+    name: "merge_fix",
+    title: "Merge fix PR",
+    description: "Squash-merge a fix attempt PR and mark the linked report fixed.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: true, idempotent: true, openWorld: true },
+    useCase: "Merge the draft PR and notify the reporter."
+  },
+  {
+    name: "refresh_ci",
+    title: "Refresh fix CI status",
+    description: "Pull the latest GitHub check-run status for a fix attempt.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Check whether CI is green before merging."
+  },
+  {
+    name: "reopen_report",
+    title: "Reopen report (operator)",
+    description: "Move a report to reopened for regression triage.",
+    scope: "mcp:write",
+    hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
+    useCase: "Reopen a regression the reporter flagged as not fixed."
+  },
   // --- Rewards (P3) -------------------------------------------------------
   {
     name: "list_top_contributors",
@@ -306,6 +343,14 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: false, openWorld: false },
     useCase: "Reply to a reporter asking for more info or confirming a fix."
   },
+  {
+    name: "get_two_way_comms_health",
+    title: "Two-way communication health",
+    description: "Summarize SDK \u2194 admin two-way reporter health for a host app: last SDK heartbeat, app version/platform last seen, unread reporter messages, recent reporter replies, and pending QA/TDD follow-ups. Use after wiring @mushi-mushi/web in a Vite/Capacitor app to confirm reports land in the console and admin/MCP replies reach the in-app widget.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Is two-way reporter communication working for this host app?"
+  },
   {
     name: "list_qa_story_runs",
     title: "Recent QA story runs",
@@ -371,6 +416,22 @@ var TDD_TOOL_CATALOG = [
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: true },
     useCase: "I just opened the PR \u2014 mark step 2 as passed and link the PR."
   },
+  {
+    name: "get_activation_status",
+    title: "Activation cockpit status",
+    description: "Unified setup posture for the active project: required steps, SDK heartbeat, dispatch preflight, and the next best action. Use this first when the user says setup is broken or they cannot connect.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What is blocking this project from going live?"
+  },
+  {
+    name: "get_reporter_thread",
+    title: "Reporter feedback thread",
+    description: "Fetch the unified timeline for a report \u2014 the reporter/admin comment thread (including verify/reopen signals) plus fix, QA, and status lanes. Use when triaging whether an end user still sees a bug as unfixed.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What did the reporter say after we marked this fixed?"
+  },
   // ── Full-Stack Audit tools (Phase 5) ────────────────────────────────────────
   {
     name: "run_fullstack_audit",
@@ -524,6 +585,26 @@ function createMushiServer(config) {
     },
     async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}`))
   );
+  server.registerTool(
+    "get_report_timeline",
+    {
+      title: titleOf("get_report_timeline"),
+      description: descOf("get_report_timeline"),
+      annotations: annotationsFor("get_report_timeline"),
+      inputSchema: { reportId: z.string().describe("The report UUID") }
+    },
+    async (args) => jsonText(await apiCall(`/v1/sync/reports/${args.reportId}/timeline`))
+  );
+  server.registerTool(
+    "get_two_way_comms_health",
+    {
+      title: titleOf("get_two_way_comms_health"),
+      description: descOf("get_two_way_comms_health"),
+      annotations: annotationsFor("get_two_way_comms_health"),
+      inputSchema: {}
+    },
+    async () => jsonText(await apiCall("/v1/sync/two-way-health"))
+  );
   server.registerTool(
     "search_reports",
     {
@@ -824,6 +905,109 @@ function createMushiServer(config) {
       });
     }
   );
+  server.registerTool(
+    "diagnose_connection",
+    {
+      title: titleOf("diagnose_connection"),
+      description: descOf("diagnose_connection"),
+      annotations: annotationsFor("diagnose_connection"),
+      inputSchema: {}
+    },
+    async () => {
+      const issues = [];
+      if (!apiKey?.startsWith("mushi_")) {
+        issues.push({
+          check: "mcp_api_key",
+          detail: "MCP server API key missing or malformed",
+          fix: "Run `mushi connect` to write MUSHI_API_KEY into .cursor/mcp.json, then restart the MCP server."
+        });
+      }
+      if (!projectId) {
+        issues.push({
+          check: "mcp_project_id",
+          detail: "No projectId configured on the MCP server",
+          fix: "Add MUSHI_PROJECT_ID to .cursor/mcp.json (copy UUID from console \u2192 Projects)."
+        });
+      }
+      if (!apiEndpoint) {
+        issues.push({
+          check: "mcp_endpoint",
+          detail: "No API endpoint configured",
+          fix: "Set MUSHI_API_ENDPOINT to your `\u2026/functions/v1/api` URL in .cursor/mcp.json."
+        });
+      }
+      let healthOk = false;
+      if (apiEndpoint) {
+        try {
+          const healthRes = await doFetch(`${apiEndpoint.replace(/\/$/, "")}/health`, {
+            signal: AbortSignal.timeout(5e3)
+          });
+          healthOk = healthRes.status === 200;
+          if (!healthOk) {
+            issues.push({
+              check: "endpoint_health",
+              detail: `GET /health \u2192 HTTP ${healthRes.status}`,
+              fix: "Verify MUSHI_API_ENDPOINT and that the Supabase edge function is deployed."
+            });
+          }
+        } catch (err) {
+          issues.push({
+            check: "endpoint_health",
+            detail: err instanceof Error ? err.message : String(err),
+            fix: "Check network connectivity and the endpoint URL in .cursor/mcp.json."
+          });
+        }
+      }
+      let ingestReady = false;
+      let dispatchReady = false;
+      try {
+        const ingest = await apiCall("/v1/sync/ingest-setup");
+        ingestReady = ingest.ready;
+        if (!ingest.ready) {
+          const failed = ingest.steps.filter((s) => s.required && !s.complete);
+          issues.push({
+            check: "ingest_setup",
+            detail: `Incomplete: ${failed.map((s) => s.label).join(", ")}`,
+            fix: failed[0]?.hint ?? "Paste the SDK snippet, start your dev server, submit a test report."
+          });
+        }
+      } catch (err) {
+        issues.push({
+          check: "ingest_setup",
+          detail: err instanceof Error ? err.message : String(err),
+          fix: "Confirm API key is active for this project (Projects \u2192 API Keys)."
+        });
+      }
+      if (projectId) {
+        try {
+          const preflight = await apiCall(`/v1/admin/projects/${projectId}/preflight`);
+          dispatchReady = preflight.ready;
+          if (!preflight.ready) {
+            const failed = preflight.checks.filter((c) => !c.ready);
+            issues.push({
+              check: "dispatch_preflight",
+              detail: `Blocked: ${failed.map((c) => c.label).join(", ")}`,
+              fix: failed[0]?.hint ?? "Open Settings \u2192 Integrations and complete GitHub + BYOK setup."
+            });
+          }
+        } catch {
+        }
+      }
+      const ready = issues.length === 0 && healthOk && ingestReady;
+      const nextAction = issues[0]?.fix ?? (ready ? "Connection healthy \u2014 SDK ingest is working. Submit a report to confirm end-to-end." : "Run `mushi doctor` in your app repo for a full local checklist.");
+      return jsonText({
+        ready,
+        healthOk,
+        ingestReady,
+        dispatchReady,
+        endpoint: apiEndpoint ?? null,
+        projectId: projectId ?? null,
+        issues,
+        nextAction,
+        summary: ready ? "MCP credentials valid; ingest pipeline ready." : `Connection issue \u2014 ${issues[0]?.check ?? "unknown"}: ${nextAction}`
+      });
+    }
+  );
   server.registerTool(
     "submit_fix_result",
     {
@@ -836,12 +1020,15 @@ function createMushiServer(config) {
         prUrl: z.string().optional().describe("GitHub PR URL"),
         filesChanged: z.array(z.string()).describe("Files modified"),
         linesChanged: z.number().describe("Total lines changed"),
-        summary: z.string().describe("Fix summary")
+        summary: z.string().describe("Fix summary"),
+        idempotencyKey: z.string().uuid().optional().describe("Optional UUID \u2014 resend the same key to safely retry without creating duplicate fix rows")
       }
     },
     async (args) => {
+      const idemKey = args.idempotencyKey ?? crypto.randomUUID();
       const created = await apiCall("/v1/admin/fixes", {
         method: "POST",
+        headers: { "Idempotency-Key": idemKey },
         body: JSON.stringify({ reportId: args.reportId, agent: "mcp" })
       });
       await apiCall(`/v1/admin/fixes/${created.fixId}`, {
@@ -947,6 +1134,59 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
+  server.registerTool(
+    "merge_fix",
+    {
+      title: "Merge fix PR",
+      description: "Squash-merge a fix attempt PR and mark the linked report fixed.",
+      annotations: annotationsFor("merge_fix"),
+      inputSchema: {
+        fixId: z.string().describe("Fix attempt UUID"),
+        mergeMethod: z.enum(["squash", "merge", "rebase"]).optional().describe("GitHub merge method")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/fixes/${args.fixId}/merge`, {
+        method: "POST",
+        body: JSON.stringify({ mergeMethod: args.mergeMethod ?? "squash" })
+      });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "refresh_ci",
+    {
+      title: "Refresh fix CI status",
+      description: "Pull the latest GitHub check-run status for a fix attempt.",
+      annotations: annotationsFor("refresh_ci"),
+      inputSchema: {
+        fixId: z.string().describe("Fix attempt UUID")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/admin/fixes/${args.fixId}/refresh-ci`, { method: "POST" });
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "reopen_report",
+    {
+      title: "Reopen report (operator)",
+      description: "Operator alias to move a report back to new for regression triage.",
+      annotations: annotationsFor("reopen_report"),
+      inputSchema: {
+        reportId: z.string().describe("Report UUID"),
+        note: z.string().optional().describe("Triage note")
+      }
+    },
+    async (args) => {
+      const data = await apiCall(`/v1/sync/reports/${args.reportId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status: "reopened", note: args.note })
+      });
+      return jsonText(data);
+    }
+  );
   server.registerTool(
     "transition_status",
     {
@@ -955,7 +1195,7 @@ function createMushiServer(config) {
       annotations: annotationsFor("transition_status"),
       inputSchema: {
         reportId: z.string().describe("Report UUID"),
-        status: z.enum(["pending", "classified", "grouped", "fixing", "fixed", "dismissed"]).describe("Target status"),
+        status: z.enum(["pending", "classified", "grouped", "fixing", "fixed", "resolved", "verified", "reopened", "dismissed"]).describe("Target status"),
         reason: z.string().optional().describe("Reason for the transition (audit trail)")
       }
     },
@@ -1138,6 +1378,23 @@ function createMushiServer(config) {
       };
     }
   );
+  server.resource(
+    "activation_status",
+    "mushi://activation",
+    {
+      description: "Unified setup posture \u2014 SDK heartbeat, reports, GitHub, MCP readiness, QA stories, and the next best action."
+    },
+    async () => {
+      const qs = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
+      return {
+        contents: [{
+          uri: "mushi://activation",
+          mimeType: "application/json",
+          text: JSON.stringify(await apiCall(`/v1/admin/activation${qs}`), 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.",
@@ -1207,6 +1464,31 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
       }]
     })
   );
+  server.prompt(
+    "mushi_setup",
+    "Diagnose why Mushi setup is stuck and return the single next command or console step to unblock it.",
+    {},
+    () => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `You are a Mushi onboarding copilot. Use the MCP tools:
+1. Read mushi://activation for unified setup posture.
+2. Read project://integration-health if GitHub or Sentry looks blocked.
+3. Call get_activation_status if the resource is unavailable.
+
+Then output:
+- **Status:** one sentence on what is done vs blocked
+- **Next step:** the single highest-leverage action (console link or CLI command)
+- **Prove it:** how the user verifies the step worked
+- **If still stuck:** one diagnostic command (e.g. mushi doctor --fix)
+
+Be specific. No generic advice.`
+        }
+      }]
+    })
+  );
   server.registerTool(
     "map_user_stories",
     {
@@ -1610,6 +1892,36 @@ Prefer items that are bottlenecks or critical severity. Skip filler.`
       return jsonText({ ok: true, message: `Step ${step_index} \u2192 ${args.status}` });
     }
   );
+  server.registerTool(
+    "get_activation_status",
+    {
+      title: titleOf("get_activation_status"),
+      description: descOf("get_activation_status"),
+      annotations: annotationsFor("get_activation_status"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Optional project UUID override")
+      }
+    },
+    async (args) => {
+      const qs = args.project_id ? `?project_id=${encodeURIComponent(args.project_id)}` : "";
+      const data = await apiCall(`/v1/admin/activation${qs}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_reporter_thread",
+    {
+      title: titleOf("get_reporter_thread"),
+      description: descOf("get_reporter_thread"),
+      annotations: annotationsFor("get_reporter_thread"),
+      inputSchema: { reportId: z.string().describe("The report UUID") }
+    },
+    // The reporter thread is the `comments` lane of the unified report
+    // timeline. There is no standalone admin `/comments` route (only the
+    // reporter-token-gated `/v1/reporter/reports/:id/comments`), so we read the
+    // admin-authed timeline, which also carries fix / QA / status lanes.
+    async (args) => jsonText(await apiCall(`/v1/admin/reports/${args.reportId}/timeline`))
+  );
   const grantedScopes = config.scopes;
   if (grantedScopes !== void 0) {
     const toolRegistry = server._registeredTools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/mcp",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "license": "MIT",
   "description": "MCP server exposing Mushi Mushi reports to coding agents",
   "type": "module",
@@ -25,8 +25,8 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@mushi-mushi/core": "^1.9.0",
-    "zod": "^4.4.2"
+    "zod": "^4.4.2",
+    "@mushi-mushi/core": "^1.12.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",