@mushi-mushi/mcp 0.13.0 → 0.14.0

package/README.md

@@ -132,6 +132,15 @@ 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 |
+| `list_projects` | Discover all Mushi projects accessible to this API key. Returns project id, name, and created date |
+| `get_project_context` | Rich context snapshot: SDK heartbeat, ingest status, autofix readiness, and open report counts |
+| `get_pipeline_logs` | Recent log entries from fix-worker, pipeline, and QA story runner — filterable by service, level, time, and limit |
+| `get_report_evidence` | Focused evidence package for a report: screenshot URL, console logs, network excerpts, environment, and user comments (lighter than `get_report_detail`) |
+| `triage_issue` | **Primary triage entry point** — combines report detail, evidence, similar bugs, fix context, blast radius, pipeline logs, and recommended next actions in one packet |
+| `query_lessons` | Token-budget retrieval of relevant learning rules for a code diff |
+| `list_lessons` | List promoted learning rules (lessons) for the current project |
 
 ### Write / agentic
 
@@ -360,6 +369,28 @@ Rebuild the package (`pnpm --filter @mushi-mushi/mcp build`) after any MCP sourc
 
 In Cursor chat, type `/` — you should see the Mushi Mushi slash-prompts (`/summarize_report_for_fix`, `/explain_judge_result`, `/triage_next_steps`). Or ask the agent directly: _"Use the Mushi MCP to list my recent reports"_. If scope is wrong you'll see the `[INSUFFICIENT_SCOPE]` error text verbatim — rotate the key with the right scope and retry.
 
+## Debug MCP logs in Cursor
+
+If tools are not showing up or returning unexpected errors:
+
+1. **Check the Cursor MCP logs**: Cursor → Help → Toggle Developer Tools → Console. Filter by `mushi`.
+2. **Verify the server started**: In the MCP panel (Cursor → Settings → MCP), look for a green dot next to the Mushi server.
+3. **Check scope errors**: A `INSUFFICIENT_SCOPE` response means your API key lacks the required scope — mint a new key with `mcp:read` (or `mcp:write` for mutating tools).
+4. **Run the health check**: `/test-mushi-mcp` command or call `list_projects` — a clean response confirms auth is working.
+5. **Restart Cursor**: After changing environment variables or `mcp.json`, restart Cursor to pick up the new config.
+
+## Mushi vs Sentry MCP
+
+| | Sentry MCP | Mushi MCP |
+|--|-----------|-----------|
+| Signal source | Thrown exceptions | User-felt bugs (rage-click, console errors, network failures flagged by real users) |
+| Evidence | Stack traces, breadcrumbs | Screenshots, console logs, network excerpts, user comments, replay pointers |
+| Triage tool | `sentry_get_issue` | `triage_issue` (evidence + similar bugs + blast radius + logs + recommended actions) |
+| Fix dispatch | — | `dispatch_fix` → draft GitHub PR → human review |
+| QA coverage | — | QA story runner, PDCA improvement loop |
+
+Both are complementary — use Sentry for exception noise, Mushi for "the user says it's broken" signal.
+
 ## See also
 
 - [V5.3 whitepaper §2.10](../../MushiMushi_Whitepaper_V5.md) — the agentic fix architecture this server feeds into.

package/dist/catalog.d.ts

@@ -0,0 +1,69 @@
+/**
+ * FILE: packages/mcp/src/catalog.ts
+ * PURPOSE: Single source of truth for the MCP tool catalog — names, titles,
+ *          descriptions, annotation hints, and short "use case" strings.
+ *
+ *          Extracted into its own module so two consumers can share it:
+ *            • `server.ts` — feeds `title`, `annotations`, and `description`
+ *              into `registerTool()` so MCP clients (Cursor, Claude Desktop)
+ *              render a proper UI and auto-approve read-only calls.
+ *            • The admin `/mcp` page — renders the same catalog visually so
+ *              humans see exactly what an agent can do with a given API key
+ *              scope, without having to crack open the README.
+ *
+ *          Because the admin imports from this package (via a type-only
+ *          import), anything we add here shows up in both places on the
+ *          next build. Don't fork the list in two.
+ */
+/** Raw-scope vocabulary — must match the CHECK constraint in migration 20260421003000. */
+type McpScope = 'mcp:read' | 'mcp:write';
+/** Set of all defined scopes — convenient default when no caller restricts. */
+declare const ALL_SCOPES: readonly McpScope[];
+/** How a client should treat a tool. Maps 1:1 to MCP `annotations`. */
+interface ToolHints {
+    /** Read-only tool — clients MAY auto-approve. */
+    readOnly: boolean;
+    /** Performs a destructive operation (delete, dismiss). Only meaningful when !readOnly. */
+    destructive?: boolean;
+    /** Running the tool twice with the same args has the same effect. */
+    idempotent?: boolean;
+    /** Tool interacts with an external system whose state can change (the Mushi API). */
+    openWorld?: boolean;
+}
+interface ToolSpec {
+    /** Machine name — matches `tools/list` and `tools/call`. Stable contract. */
+    name: string;
+    /** Human-readable title surfaced in MCP clients + the /mcp admin page. */
+    title: string;
+    /** One-paragraph description for the LLM. Explains when to call the tool. */
+    description: string;
+    /** Scope required to call the tool — gates UI rendering and server auth. */
+    scope: McpScope;
+    /** MCP annotation hints. */
+    hints: ToolHints;
+    /**
+     * One-liner that tells a human "what problem does calling this tool solve?".
+     * Shown on the admin /mcp catalog cards — should be end-user-shaped, not
+     * engineer-shaped ("What should I fix next?" not "GET /v1/admin/reports").
+     */
+    useCase: string;
+}
+declare const TOOL_CATALOG: ToolSpec[];
+interface ResourceSpec {
+    name: string;
+    uri: string;
+    title: string;
+    description: string;
+    scope: McpScope;
+}
+declare const RESOURCE_CATALOG: ResourceSpec[];
+interface PromptSpec {
+    name: string;
+    title: string;
+    description: string;
+    useCase: string;
+}
+declare const PROMPT_CATALOG: PromptSpec[];
+declare const TDD_TOOL_CATALOG: ToolSpec[];
+
+export { ALL_SCOPES, type McpScope, PROMPT_CATALOG, type PromptSpec, RESOURCE_CATALOG, type ResourceSpec, TDD_TOOL_CATALOG, TOOL_CATALOG, type ToolHints, type ToolSpec };

package/dist/catalog.js

@@ -0,0 +1,14 @@
+import {
+  ALL_SCOPES,
+  PROMPT_CATALOG,
+  RESOURCE_CATALOG,
+  TDD_TOOL_CATALOG,
+  TOOL_CATALOG
+} from "./chunk-QWZEQYCN.js";
+export {
+  ALL_SCOPES,
+  PROMPT_CATALOG,
+  RESOURCE_CATALOG,
+  TDD_TOOL_CATALOG,
+  TOOL_CATALOG
+};