zopkit-bug-resolution-mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,47 +1,103 @@
 # bug-resolution MCP server
 
-A single-tool MCP server so Claude Code (or Cursor, or any other MCP client)
-can report back how it fixed a Zopkit bug report as a native tool call,
-instead of hand-rolling a curl command. It's a thin wrapper around
-`POST /api/admin/bug-reports/resolution/:id` — see
-`backend/src/features/bug-reports/README.md` for what that endpoint
-actually does server-side.
+A two-tool MCP server so Claude Code (or Cursor, or any other MCP client) can
+work a Zopkit bug report end to end as native tool calls, instead of
+hand-rolling curl commands:
+
+- **`fetch_bug_context`** — pulls the full report (title, description,
+  severity, status, page URL, browser info, discussion comments) plus every
+  inline screenshot as real image content, via
+  `GET /api/admin/bug-reports/context/:id`.
+- **`submit_bug_resolution`** — writes back how it was fixed as a Markdown
+  writeup and moves the report to `resolved`, via
+  `POST /api/admin/bug-reports/resolution/:id`.
+
+Both are thin wrappers — see `backend/src/features/bug-reports/README.md`
+for what each endpoint actually does server-side.
+
+Published to npm as
+[`zopkit-bug-resolution-mcp`](https://www.npmjs.com/package/zopkit-bug-resolution-mcp)
+— employees don't need this repo at all, just `npx` and a key.
 
 ## Setup
 
 1. **Get a key.** In the company-admin panel → Bug Reports → **API Keys**
-   (full `bug-reports` staff access only), generate one and copy it — it's
-   shown exactly once.
+   (any platform staff with `bug-reports` or `bug-reports-own` access can
+   generate their own), generate one and copy it — it's shown exactly once.
+   The key's reach (every report, or only reports you created/are assigned
+   to) always tracks your *current* staff role — it's resolved live on every
+   call, not fixed at generation time.
 
-2. **Register the server:**
+2. **Register the server** — either via the CLI:
 
    ```bash
-   cd deploy/mcp/bug-resolution
-   npm install
    claude mcp add bug-resolution \
      --env BUG_REPORT_API_KEY=<the key you copied> \
-     -- node "$(pwd)/index.js"
+     -- npx -y zopkit-bug-resolution-mcp
+   ```
+
+   or by adding this to your MCP config JSON (Claude Desktop's
+   `claude_desktop_config.json`, or Claude Code's own MCP settings):
+
+   ```json
+   {
+     "mcpServers": {
+       "bug-resolution": {
+         "command": "npx",
+         "args": ["-y", "zopkit-bug-resolution-mcp"],
+         "env": {
+           "BUG_REPORT_API_KEY": "<the key you copied>"
+         }
+       }
+     }
+   }
    ```
 
    By default it talks to production (`https://api.zopkit.com`). Point it
-   elsewhere (e.g. a local dev backend) with an extra
-   `--env BUG_REPORT_API_BASE_URL=http://localhost:3000`.
+   elsewhere (e.g. a local dev backend) with an extra env var,
+   `BUG_REPORT_API_BASE_URL=http://localhost:3000`.
+
+3. Restart Claude Code (or Claude Desktop) and approve `bug-resolution` when
+   prompted.
+
+<details>
+<summary>Running from a local checkout instead (this repo, not npm)</summary>
 
-3. Restart Claude Code and approve `bug-resolution` when prompted.
+```bash
+cd deploy/mcp/bug-resolution
+npm install
+claude mcp add bug-resolution \
+  --env BUG_REPORT_API_KEY=<the key you copied> \
+  -- node "$(pwd)/index.js"
+```
+
+Useful if you're changing `index.js` itself — the npm package is what
+everyone else should use.
+</details>
 
 ## Usage
 
-Once registered, ask Claude Code (or whichever tool you fixed the bug with)
-to call `submit_bug_resolution` with the bug report's id (a UUID — from
-whoever asked you to fix it, or the report's admin-panel URL) and a Markdown
-writeup. It sets the report's resolution notes to that writeup and moves its
-status straight to `resolved`.
+Once registered, give Claude Code (or whichever tool) the bug report's id (a
+UUID — copy it from the ID chip in the report's detail panel, or from
+whoever asked you to fix it).
+
+1. Ask it to call `fetch_bug_context` with that id first — you'll get the
+   title, description, severity/status, discussion, and every screenshot
+   actually rendered as images, so the tool can see the bug instead of just
+   reading a URL to it.
+2. After fixing it, ask it to call `submit_bug_resolution` with the same id
+   and a Markdown writeup. It sets the report's resolution notes to that
+   writeup and moves its status straight to `resolved`.
 
 ## Notes
 
 - Not part of the pnpm workspace (`pnpm-workspace.yaml`) or the deployed
-  backend image — a standalone dev tool, installed with plain `npm install`.
+  backend image, and published separately from this repo's release process
+  (`npm publish` from this directory, manually, when `index.js` changes).
+- No secrets in the package itself — the API key is supplied per-installation
+  via the `BUG_REPORT_API_KEY` env var, never embedded.
 - The key is per-developer and individually revocable from the same API Keys
   panel — revoking one never affects any other person's key.
-- This server only exposes the one write it needs. It can't list, search, or
-  read bug reports — the person/tool using it needs the report's id already.
+- This server only exposes the two operations it needs. It can't list or
+  search bug reports — the person/tool using it needs the report's id
+  already.

package/index.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
-// bug-resolution MCP server — a single tool wrapping
-// POST /api/admin/bug-reports/resolution/:id (see backend/src/features/
-// bug-reports/README.md) so a developer's Claude Code / Cursor session can
-// report back how it fixed a bug as a native tool call instead of hand-
-// rolling a curl command. Thin wrapper: all the actual logic (auth, the
-// resolutionNotes/status write) lives server-side: this just forwards
-// {bugReportId, markdown} as the HTTP call the README already documents.
+// bug-resolution MCP server — two tools wrapping the bug-reports resolution
+// API (see backend/src/features/bug-reports/README.md) so a developer's
+// Claude Code / Cursor session can work a bug report end to end as native
+// tool calls instead of hand-rolling curl commands:
+//   - fetch_bug_context: GET /api/admin/bug-reports/context/:id — pulls the
+//     full report (title/description/severity/status/comments) plus every
+//     inline screenshot as real image content.
+//   - submit_bug_resolution: POST /api/admin/bug-reports/resolution/:id —
+//     writes back the fix as a Markdown resolution and marks it resolved.
+// Thin wrapper: all the actual logic (auth, scoping, the DB writes) lives
+// server-side; this just forwards the HTTP calls the README documents.
 //
 // Setup: see README.md in this directory.
 
@@ -21,7 +25,26 @@ if (!API_KEY) {
     'Generate one from the company-admin panel (Bug Reports → API Keys) and set it when registering this server.');
 }
 
-const server = new McpServer({ name: 'zopkit-bug-resolution', version: '1.0.0' });
+const server = new McpServer({ name: 'zopkit-bug-resolution', version: '1.1.0' });
+
+const IMG_SRC = /<img\b[^>]*\bsrc="([^"]+)"[^>]*>/gi;
+
+function extractImageUrls(html) {
+  const urls = [];
+  for (const match of html.matchAll(IMG_SRC)) {
+    const src = match[1];
+    urls.push(src.startsWith('http') ? src : `${BASE_URL}${src}`);
+  }
+  return urls;
+}
+
+async function fetchImageContentBlock(url) {
+  const res = await fetch(url);
+  if (!res.ok) return null;
+  const contentType = res.headers.get('content-type') || 'image/png';
+  const buffer = Buffer.from(await res.arrayBuffer());
+  return { type: 'image', data: buffer.toString('base64'), mimeType: contentType };
+}
 
 server.registerTool(
   'submit_bug_resolution',
@@ -83,5 +106,88 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  'fetch_bug_context',
+  {
+    title: 'Fetch bug report context',
+    description:
+      'Pull the full context for a Zopkit bug report — title, description, severity, status, ' +
+      'page URL, browser info, discussion comments, and every inline screenshot as actual images — ' +
+      'so an AI coding tool has everything it needs to diagnose and fix the bug without ' +
+      'opening the admin panel. Screenshots come back as image content alongside the text summary.',
+    inputSchema: {
+      bugReportId: z.string().min(1).describe("The bug report's id (UUID)."),
+    },
+  },
+  async ({ bugReportId }) => {
+    if (!API_KEY) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'BUG_REPORT_API_KEY is not set on this MCP server — see README.md.' }],
+      };
+    }
+
+    let res;
+    try {
+      res = await fetch(`${BASE_URL}/api/admin/bug-reports/context/${encodeURIComponent(bugReportId)}`, {
+        headers: { 'X-API-Key': API_KEY },
+      });
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Could not reach ${BASE_URL}: ${err instanceof Error ? err.message : String(err)}` }],
+      };
+    }
+
+    const body = await res.json().catch(() => null);
+
+    if (!res.ok) {
+      const message = body?.message || body?.error || `HTTP ${res.status}`;
+      return { isError: true, content: [{ type: 'text', text: `Failed to fetch bug context: ${message}` }] };
+    }
+
+    const report = body?.data;
+    if (!report) {
+      return { isError: true, content: [{ type: 'text', text: 'Bug context response had no data.' }] };
+    }
+
+    const comments = report.comments || [];
+    const commentsText = comments.length
+      ? comments.map((c) => `- ${c.authorName || c.authorEmail} (${c.createdAt}): ${c.body}`).join('\n')
+      : '(no comments)';
+
+    const summary = [
+      `# ${report.title}`,
+      `id: ${report.id}`,
+      `severity: ${report.severity} | status: ${report.status}`,
+      report.pageUrl ? `page: ${report.pageUrl}` : null,
+      report.browserInfo ? `browser: ${report.browserInfo}` : null,
+      '',
+      '## Description',
+      report.description,
+      '',
+      '## Discussion',
+      commentsText,
+    ].filter((line) => line !== null).join('\n');
+
+    const content = [{ type: 'text', text: summary }];
+
+    // Inline screenshots live as <img> tags inside the description HTML —
+    // fetch each (now-public) media URL and hand it back as real image
+    // content so the AI tool actually sees the bug, not just a URL to it.
+    const imageUrls = extractImageUrls(report.description || '');
+    for (const url of imageUrls) {
+      try {
+        const block = await fetchImageContentBlock(url);
+        if (block) content.push(block);
+      } catch {
+        content.push({ type: 'text', text: `(failed to load screenshot: ${url})` });
+      }
+    }
+
+    return { content };
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "zopkit-bug-resolution-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
-  "description": "MCP server: submit how a bug report was fixed to Zopkit wrapper's POST /admin/bug-reports/resolution/:id. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) — see README.md.",
+  "description": "MCP server for Zopkit wrapper bug reports: fetch full bug context (with screenshots) and submit how a bug was fixed. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) — see README.md.",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=18"