@mushi-mushi/mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,23 +1,90 @@
 # @mushi-mushi/mcp
 
-MCP (Model Context Protocol) server that exposes Mushi Mushi reports to coding agents.
+[Model Context Protocol](https://spec.modelcontextprotocol.io/) server that exposes Mushi Mushi reports, fixes, and project state to coding agents (Claude Code, Cursor, Codex, Continue, Cline, Zed, Windsurf, and any other MCP-compatible client).
 
-## Usage
+> **What this is, and what it isn't**
+>
+> - **This package** is the MCP **server** — runs locally next to your editor, talks to the Mushi Mushi API, and presents bug reports as MCP tools/resources to your coding agent.
+> - **`@mushi-mushi/agents`** ships the MCP **client adapter** — used by the autofix orchestrator when your project's `autofix_agent = 'mcp'`. See `packages/agents/src/adapters/mcp.ts`.
+> - The `generic_mcp` adapter shipped before V5.3 was a misnomer (it spoke plain REST). It is now `RestFixWorkerAgent`; the old export is kept as a deprecated alias for one more minor.
+
+## Quick start
+
+### 1. With Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "mushi-mushi": {
+      "command": "npx",
+      "args": ["-y", "@mushi-mushi/mcp@latest"],
+      "env": {
+        "MUSHI_API_KEY": "key_xxx",
+        "MUSHI_PROJECT_ID": "proj_xxx",
+        "MUSHI_API_ENDPOINT": "https://api.mushimushi.dev"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see a hammer icon in the chat input — click it to see the Mushi Mushi tools.
+
+### 2. With Cursor
+
+In Cursor settings, open **MCP** → **Add new MCP server** and paste:
 
 ```bash
-MUSHI_API_KEY=key_xxx MUSHI_PROJECT_ID=proj_xxx npx @mushi-mushi/mcp
+npx -y @mushi-mushi/mcp@latest
 ```
 
-### Tools
+Set the same three env vars (`MUSHI_API_KEY`, `MUSHI_PROJECT_ID`, optional `MUSHI_API_ENDPOINT`).
+
+### 3. From the command line
+
+```bash
+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.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_recent_reports` | Fetch the N most recent reports, with optional `status` / `category` / `severity` filters |
+| `get_report_detail` | Full payload for a single report — description, console logs, network requests, screenshot URL, classification result, fix history |
+| `search_reports` | Keyword + semantic search across reports for the configured project |
+
+> Need a tool that isn't here? Open an issue at [github.com/kensaurus/mushi-mushi/issues](https://github.com/kensaurus/mushi-mushi/issues) and tag it `mcp`.
+
+## Resources
+
+| URI | Returns |
+|---|---|
+| `project://settings` | Project config (name, autofix settings, plugins enabled, ontology) |
+| `project://stats` | Counts of new / classified / fixed reports + last 7-day trend |
+
+## Environment variables
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `MUSHI_API_KEY` | yes | — | Project API key. Get one from the admin console → Settings → API keys. |
+| `MUSHI_PROJECT_ID` | yes | — | Found in the admin console URL or Settings page. |
+| `MUSHI_API_ENDPOINT` | no | `https://api.mushimushi.dev` | Override only if you self-host. |
+
+## Security
 
-- `get_recent_reports` — fetch latest reports with optional filters
-- `get_report_detail` — full report with console/network logs
-- `search_reports` — keyword and semantic search
+- The server runs locally; your API key never leaves your machine except in calls to your configured `MUSHI_API_ENDPOINT`.
+- Use a **scoped** API key with read-only or read-write scope — never paste a service-role key.
+- The server logs to stderr; redirect to a file if you need an audit trail.
 
-### Resources
+## See also
 
-- `project://settings` — current project configuration
-- `project://stats` — report counts and trends
+- [V5.3 whitepaper §2.10](../../MushiMushi_Whitepaper_V5.md) — the agentic fix architecture this server feeds into.
+- [`@mushi-mushi/agents`](../agents/README.md) — orchestrator that consumes MCP-exposed fix workers.
 
 ## License
 

package/dist/index.js

@@ -10,10 +10,11 @@ var API_ENDPOINT = process.env.MUSHI_API_ENDPOINT ?? "https://api.mushimushi.dev
 var API_KEY = process.env.MUSHI_API_KEY ?? "";
 var PROJECT_ID = process.env.MUSHI_PROJECT_ID ?? "";
 async function apiCall(path, options) {
-  const res = await fetch(`${API_ENDPOINT}/api${path}`, {
+  const res = await fetch(`${API_ENDPOINT}${path}`, {
     ...options,
     headers: {
       "Content-Type": "application/json",
+      "Authorization": `Bearer ${API_KEY}`,
       "X-Mushi-Api-Key": API_KEY,
       "X-Mushi-Project": PROJECT_ID,
       ...options?.headers ?? {}

package/package.json

@@ -1,61 +1,62 @@
-{
-  "name": "@mushi-mushi/mcp",
-  "version": "0.1.0",
-  "license": "MIT",
-  "description": "MCP server exposing Mushi Mushi reports to coding agents",
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "mushi-mcp": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "eslint src/",
-    "test": "echo 'no tests yet'",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "@mushi-mushi/core": "workspace:*",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@mushi-mushi/eslint-config": "workspace:*",
-    "@types/node": "^22.0.0",
-    "eslint": "^9.39.4",
-    "tsup": "^8.4.0",
-    "typescript": "^5.7.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kensaurus/mushi-mushi.git",
-    "directory": "packages/mcp"
-  },
-  "author": "Kenji Sakuramoto",
-  "homepage": "https://github.com/kensaurus/mushi-mushi/tree/main/packages/mcp#readme",
-  "bugs": {
-    "url": "https://github.com/kensaurus/mushi-mushi/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "sideEffects": false,
-  "keywords": [
-    "mushi-mushi",
-    "bug-reporting",
-    "sdk"
-  ]
-}
+{
+  "name": "@mushi-mushi/mcp",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "MCP server exposing Mushi Mushi reports to coding agents",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mushi-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6",
+    "@mushi-mushi/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^10.2.0",
+    "tsup": "^8.4.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4",
+    "@mushi-mushi/eslint-config": "0.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kensaurus/mushi-mushi.git",
+    "directory": "packages/mcp"
+  },
+  "author": "Kenji Sakuramoto",
+  "homepage": "https://github.com/kensaurus/mushi-mushi/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/kensaurus/mushi-mushi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "mushi-mushi",
+    "bug-reporting",
+    "sdk"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}