@mushi-mushi/mcp 0.13.0 → 0.14.0

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",
@@ -244,6 +260,64 @@ var TOOL_CATALOG = [
     scope: "mcp:write",
     hints: { readOnly: false, destructive: false, idempotent: true, openWorld: false },
     useCase: "Set up this repo for the Mushi evolution loop in one step."
+  },
+  // ── Sentry-like triage and project context ────────────────────────────────
+  {
+    name: "list_projects",
+    title: "List accessible projects",
+    description: "List the Mushi projects accessible to this API key. For project-scoped keys (the typical case), returns a single-item list with the bound project's id, name, slug, plan tier, and ingest status. For org-level tokens, returns all projects in the org. Use this when MUSHI_PROJECT_ID is not configured \u2014 call list_projects first, then pass the id to other tools.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Which projects can I access with this API key?"
+  },
+  {
+    name: "get_project_context",
+    title: "Project context snapshot",
+    description: "Return a rich context snapshot for a project: name, repo URL, SDK heartbeat, ingest status, open report count, autofix readiness, BYOK LLM config, plan tier, and active integration health. Equivalent to a merged preflight + activation + settings read. Agents should call this at the start of a triage session to orient themselves.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Give me a status overview of this project before I start triaging."
+  },
+  {
+    name: "get_pipeline_logs",
+    title: "Recent pipeline logs",
+    description: "Pull recent log entries from the Mushi pipeline services: classify-report, fix-worker, qa-story-runner, mcp, webhook, api, or all. Accepts project_id, service, since (ISO-8601), limit (max 200), and level (info | warn | error | fatal) filters. Returns structured log rows with timestamp, level, service, message, and a trace_id/report_id when available. Use this when a fix failed, a QA story keeps erroring, or an ingest pipeline went silent.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Why did the last fix attempt fail? Show me recent pipeline errors."
+  },
+  {
+    name: "get_report_evidence",
+    title: "Bug report evidence",
+    description: "Return the full evidence package for a single bug report: screenshot URL, console logs, network excerpts, browser environment (user agent, URL, viewport, SDK version), user replay link if available, breadcrumb trail, and the reporter's own comments thread. This is the same data an engineer would collect for a root-cause investigation. Faster than calling get_report_detail + report timeline separately.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "I need all the evidence for this bug report to diagnose the root cause."
+  },
+  {
+    name: "triage_issue",
+    title: "Triage issue end-to-end",
+    description: 'Read-only orchestration tool: combines report detail, evidence, similar bugs, fix context, blast radius, and recent pipeline logs for a report into a single structured triage packet. Returns a prioritised list of recommended next actions (investigate, dispatch_fix, group_with, dismiss). Equivalent to a Sentry "Analyze with Seer" flow grounded in user-felt reports. Pass report_id to kick off triage. Call this before dispatch_fix.',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "Analyze this bug report end-to-end and tell me what to do."
+  },
+  // ── Lessons / evolution loop ─────────────────────────────────────────────
+  {
+    name: "query_lessons",
+    title: "Query lessons for diff context",
+    description: 'Token-budget retrieval of relevant learning rules (lessons) for a given code diff or PR context. Returns ranked lessons packed within max_tokens using bi-encoder retrieval + severity-weighted scoring. Use this before opening a PR, writing a fix, or asking "what mistakes should I avoid in this area of code?"',
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What past mistakes should I avoid when making this change?"
+  },
+  {
+    name: "list_lessons",
+    title: "List project lessons",
+    description: "List promoted learning rules (lessons) for the current project. Each lesson represents a named pattern of mistakes that has been encoded from bug reports. Use this to understand what systemic issues have been identified and encoded as heuristics.",
+    scope: "mcp:read",
+    hints: { readOnly: true, idempotent: true, openWorld: true },
+    useCase: "What systemic patterns has Mushi identified for this project?"
   }
 ];
 var TDD_TOOL_CATALOG = [
@@ -327,6 +401,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",
@@ -392,6 +474,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",
@@ -545,6 +643,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",
     {
@@ -845,6 +963,278 @@ 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(
+    "list_projects",
+    {
+      title: titleOf("list_projects"),
+      description: descOf("list_projects"),
+      annotations: annotationsFor("list_projects"),
+      inputSchema: {}
+    },
+    async () => {
+      const data = await apiCall("/v1/admin/mcp/projects");
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_project_context",
+    {
+      title: titleOf("get_project_context"),
+      description: descOf("get_project_context"),
+      annotations: annotationsFor("get_project_context"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
+      const [preflightRes, activationRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/projects/${pid}/preflight`),
+        apiCall(`/v1/admin/activation?project_id=${encodeURIComponent(pid)}`)
+      ]);
+      return jsonText({
+        project_id: pid,
+        preflight: preflightRes.status === "fulfilled" ? preflightRes.value : { error: String(preflightRes.reason) },
+        activation: activationRes.status === "fulfilled" ? activationRes.value : { error: String(activationRes.reason) }
+      });
+    }
+  );
+  server.registerTool(
+    "get_pipeline_logs",
+    {
+      title: titleOf("get_pipeline_logs"),
+      description: descOf("get_pipeline_logs"),
+      annotations: annotationsFor("get_pipeline_logs"),
+      inputSchema: {
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
+        service: z.enum(["classify-report", "fix-worker", "qa-story-runner", "mcp", "webhook", "api", "all"]).optional().describe("Pipeline service to filter (default: all)."),
+        since: z.string().optional().describe("ISO-8601 timestamp \u2014 return only entries after this time."),
+        limit: z.number().optional().describe("Max entries to return (default 50, max 200)."),
+        level: z.enum(["info", "warn", "error", "fatal"]).optional().describe("Minimum severity level (default: warn).")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      if (!pid) throw new MushiApiError(400, "MISSING_PROJECT_ID", "project_id is required");
+      const qs = new URLSearchParams();
+      if (args.service && args.service !== "all") qs.set("service", args.service);
+      if (args.since) qs.set("since", args.since);
+      qs.set("limit", String(Math.min(args.limit ?? 50, 200)));
+      if (args.level) qs.set("level", args.level);
+      const data = await apiCall(`/v1/admin/mcp/logs/${pid}?${qs}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "get_report_evidence",
+    {
+      title: titleOf("get_report_evidence"),
+      description: descOf("get_report_evidence"),
+      annotations: annotationsFor("get_report_evidence"),
+      inputSchema: {
+        report_id: z.string().describe("Report UUID.")
+      }
+    },
+    async (args) => {
+      const [reportRes, timelineRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/reports/${args.report_id}`),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`)
+      ]);
+      const report = reportRes.status === "fulfilled" ? reportRes.value : null;
+      const timeline = timelineRes.status === "fulfilled" ? timelineRes.value : null;
+      const evidence = report ? {
+        report_id: args.report_id,
+        description: report.description,
+        summary: report.summary,
+        screenshot_url: report.screenshot_url ?? null,
+        environment: report.environment ?? null,
+        breadcrumbs: report.breadcrumbs ?? null,
+        sentry_replay_id: report.sentry_replay_id ?? null,
+        sentry_trace_id: report.sentry_trace_id ?? null,
+        sentry_event_id: report.sentry_event_id ?? null,
+        session_id: report.session_id ?? null,
+        created_at: report.created_at,
+        tags: report.tags ?? null
+      } : { error: String(reportRes.reason) };
+      return jsonText({
+        evidence,
+        reporter_thread: timeline ?? { error: String(timelineRes.reason) }
+      });
+    }
+  );
+  server.registerTool(
+    "triage_issue",
+    {
+      title: titleOf("triage_issue"),
+      description: descOf("triage_issue"),
+      annotations: annotationsFor("triage_issue"),
+      inputSchema: {
+        report_id: z.string().describe("Report UUID to triage."),
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project."),
+        include_logs: z.boolean().optional().describe("Include recent pipeline logs in triage packet (default: true).")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const includeLogs = args.include_logs !== false;
+      const [reportRes, evidenceRes, similarRes, fixCtxRes, blastRes, logsRes] = await Promise.allSettled([
+        apiCall(`/v1/admin/reports/${args.report_id}`),
+        apiCall(`/v1/admin/reports/${args.report_id}/timeline`),
+        apiCall(`/v1/admin/reports/similarity`, {
+          method: "POST",
+          body: JSON.stringify({ report_id: args.report_id })
+        }).catch(() => null),
+        pid ? apiCall(`/v1/admin/reports/${args.report_id}/fix-context`).catch(() => null) : Promise.resolve(null),
+        pid ? apiCall(`/v1/admin/reports/${args.report_id}/blast-radius`).catch(() => null) : Promise.resolve(null),
+        includeLogs && pid ? apiCall(`/v1/admin/mcp/logs/${pid}?limit=20&level=warn`).catch(() => null) : Promise.resolve(null)
+      ]);
+      const report = reportRes.status === "fulfilled" ? reportRes.value : null;
+      const severity = report ? report.severity : "unknown";
+      const category = report ? report.category : "unknown";
+      const status = report ? report.status : "unknown";
+      const actions = [];
+      if (status === "new" || status === "classified") {
+        actions.push({
+          action: "dispatch_fix",
+          reason: "Report is classified but no fix has been attempted",
+          tool: "dispatch_fix",
+          args: { reportId: args.report_id, agent: "cursor_cloud" }
+        });
+      } else if (status === "fixing") {
+        actions.push({
+          action: "check_fix_progress",
+          reason: "Fix is in progress \u2014 check the fix timeline for latest status",
+          tool: "get_fix_timeline",
+          args: { reportId: args.report_id }
+        });
+      } else if (status === "fixed") {
+        actions.push({
+          action: "verify_fix",
+          reason: "Fix was applied \u2014 verify it resolved the issue",
+          tool: "get_fix_context",
+          args: { reportId: args.report_id }
+        });
+      }
+      return jsonText({
+        report_id: args.report_id,
+        severity,
+        category,
+        status,
+        report: reportRes.status === "fulfilled" ? reportRes.value : { error: String(reportRes.reason) },
+        reporter_thread: evidenceRes.status === "fulfilled" ? evidenceRes.value : null,
+        similar_bugs: similarRes.status === "fulfilled" ? similarRes.value : null,
+        fix_context: fixCtxRes.status === "fulfilled" ? fixCtxRes.value : null,
+        blast_radius: blastRes.status === "fulfilled" ? blastRes.value : null,
+        recent_logs: logsRes.status === "fulfilled" ? logsRes.value : null,
+        recommended_actions: actions,
+        triage_summary: `[${severity}] ${category} \u2014 status: ${status}. ${actions.length > 0 ? `Recommended: ${actions[0]?.action}.` : "No action required."}`
+      });
+    }
+  );
   server.registerTool(
     "submit_fix_result",
     {
@@ -1008,8 +1398,8 @@ function createMushiServer(config) {
   server.registerTool(
     "reopen_report",
     {
-      title: "Reopen report (operator)",
-      description: "Operator alias to move a report back to new for regression triage.",
+      title: titleOf("reopen_report"),
+      description: descOf("reopen_report"),
       annotations: annotationsFor("reopen_report"),
       inputSchema: {
         reportId: z.string().describe("Report UUID"),
@@ -1064,6 +1454,52 @@ function createMushiServer(config) {
       return jsonText(data);
     }
   );
+  server.registerTool(
+    "query_lessons",
+    {
+      title: titleOf("query_lessons"),
+      description: descOf("query_lessons"),
+      annotations: annotationsFor("query_lessons"),
+      inputSchema: {
+        diff_text: z.string().describe("The PR diff, code snippet, or description of the change being made."),
+        max_tokens: z.number().optional().describe("Maximum tokens for returned lessons context (default 3000, max 8000)."),
+        top_k: z.number().optional().describe("Max number of lessons to return (default 15, max 50)."),
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const params = new URLSearchParams();
+      params.set("diff_text", args.diff_text);
+      if (args.max_tokens !== void 0) params.set("max_tokens", String(args.max_tokens));
+      if (args.top_k !== void 0) params.set("top_k", String(args.top_k));
+      if (pid) params.set("projectId", pid);
+      const data = await apiCall(`/v1/admin/lessons/query?${params}`);
+      return jsonText(data);
+    }
+  );
+  server.registerTool(
+    "list_lessons",
+    {
+      title: titleOf("list_lessons"),
+      description: descOf("list_lessons"),
+      annotations: annotationsFor("list_lessons"),
+      inputSchema: {
+        severity: z.enum(["info", "warn", "critical"]).optional().describe("Filter by severity level."),
+        limit: z.number().optional().describe("Max number of lessons to return (default 50, max 200)."),
+        project_id: z.string().optional().describe("Project UUID. Defaults to configured project.")
+      }
+    },
+    async (args) => {
+      const pid = args.project_id ?? projectId;
+      const params = new URLSearchParams();
+      if (args.severity) params.set("severity", args.severity);
+      params.set("limit", String(Math.min(args.limit ?? 50, 200)));
+      if (pid) params.set("projectId", pid);
+      const data = await apiCall(`/v1/admin/lessons?${params}`);
+      return jsonText(data);
+    }
+  );
   server.resource(
     "project_stats",
     "project://stats",
@@ -1088,15 +1524,17 @@ function createMushiServer(config) {
       contents: [{ uri: "project://dashboard", mimeType: "application/json", text: JSON.stringify(await apiCall("/v1/admin/dashboard"), null, 2) }]
     })
   );
-  const rewardsMeta = (name) => annotationsFor(name);
-  server.tool(
+  server.registerTool(
     "list_top_contributors",
-    rewardsMeta("list_top_contributors").title,
     {
-      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")
+      title: titleOf("list_top_contributors"),
+      description: descOf("list_top_contributors"),
+      annotations: annotationsFor("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")
+      }
     },
-    rewardsMeta("list_top_contributors"),
     async ({ limit, range }) => ({
       content: [{
         type: "text",
@@ -1108,15 +1546,18 @@ function createMushiServer(config) {
       }]
     })
   );
-  server.tool(
+  server.registerTool(
     "award_bonus_points",
-    rewardsMeta("award_bonus_points").title,
     {
-      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")
+      title: titleOf("award_bonus_points"),
+      description: descOf("award_bonus_points"),
+      annotations: annotationsFor("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")
+      }
     },
-    rewardsMeta("award_bonus_points"),
     async ({ external_user_id, points, reason }) => ({
       content: [{
         type: "text",
@@ -1132,15 +1573,18 @@ function createMushiServer(config) {
       }]
     })
   );
-  server.tool(
+  server.registerTool(
     "set_tier",
-    rewardsMeta("set_tier").title,
     {
-      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")
+      title: titleOf("set_tier"),
+      description: descOf("set_tier"),
+      annotations: annotationsFor("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")
+      }
     },
-    rewardsMeta("set_tier"),
     async ({ external_user_id, tier_slug, reason }) => ({
       content: [{
         type: "text",
@@ -1215,6 +1659,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.",
@@ -1284,6 +1745,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",
     {
@@ -1687,6 +2173,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;