@mushi-mushi/mcp 0.13.1 → 0.14.1

package/dist/index.js

@@ -260,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: fix-worker, qa-story-runner, pipeline, 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 = [
@@ -1008,6 +1066,175 @@ function createMushiServer(config) {
       });
     }
   );
+  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(["fix-worker", "qa-story-runner", "pipeline", "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",
     {
@@ -1171,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"),
@@ -1227,6 +1454,55 @@ 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 data = await apiCall("/v1/admin/lessons/query", {
+        method: "POST",
+        body: JSON.stringify({
+          diff_text: args.diff_text,
+          ...args.max_tokens !== void 0 ? { max_tokens: args.max_tokens } : {},
+          ...args.top_k !== void 0 ? { top_k: args.top_k } : {},
+          ...pid ? { project_id: pid } : {}
+        })
+      });
+      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",
@@ -1251,15 +1527,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",
@@ -1271,15 +1549,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",
@@ -1295,15 +1576,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",

package/dist/server.d.ts

@@ -0,0 +1,54 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpScope } from './catalog.js';
+
+/**
+ * FILE: packages/mcp/src/server.ts
+ * PURPOSE: Testable MCP server factory. Exports `createMushiServer()` which
+ *          builds a fully-configured `McpServer` but does not connect to any
+ *          transport — allowing the stdio entry (`src/index.ts`) and the
+ *          in-memory integration tests to share the exact same tool
+ *          implementations. Keeping the module side-effect-free is critical:
+ *          the old design called `main()` at import time, which made it
+ *          impossible to mock `fetch` before the server had wired up its
+ *          closures.
+ *
+ *          Every tool/resource is a thin, typed wrapper over the Mushi REST
+ *          API; auth is an API key sent in two headers so the shared
+ *          `adminOrApiKey` middleware accepts it regardless of which header
+ *          a proxy strips first.
+ */
+
+declare class MushiApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+interface MushiServerConfig {
+    /** Server version — surfaced in MCP handshake. Read from package.json by boot. */
+    version: string;
+    /** Base URL of the Mushi API, e.g. https://xyz.supabase.co/functions/v1/api */
+    apiEndpoint: string;
+    /** Project API key with `mcp:read` or `mcp:write` scope. */
+    apiKey: string;
+    /** Optional project hint. Used to scope multi-project tools. */
+    projectId?: string;
+    /**
+     * Granted scopes from the API key. When provided, only tools/resources that
+     * require a subset of these scopes are registered. Defaults to ALL_SCOPES.
+     */
+    scopes?: readonly McpScope[];
+    /**
+     * Fetch implementation — overridable for tests. Tests pass a spy that
+     * asserts request shape and returns canned envelopes without hitting the
+     * network. Defaults to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Build an MCP server instance pre-wired with every Mushi tool, resource,
+ * and prompt. Does NOT call `server.connect()` — the caller binds whatever
+ * transport they need (stdio for the CLI, InMemoryTransport for tests).
+ */
+declare function createMushiServer(config: MushiServerConfig): McpServer;
+
+export { MushiApiError, type MushiServerConfig, createMushiServer };