zopkit-bug-resolution-mcp 1.0.0 → 1.2.0

package/README.md

@@ -1,47 +1,116 @@
 # 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 four-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`.
+- **`fetch_assigned_bugs`** — lists reports currently assigned to the API
+  key's owner ("what's on my plate"), optionally filtered by status, via
+  `GET /api/admin/bug-reports/assigned`.
+- **`create_bug_report`** — files a new bug report (plain-text description),
+  optionally self-assigning it, via `POST /api/admin/bug-reports/report`.
+
+All four 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 and approve `bug-resolution` when prompted.
+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>
+
+```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`.
+
+Two more, independent of the fetch/resolve flow above:
+
+- Ask it to call `fetch_assigned_bugs` (optionally with a `status` filter) to
+  see what's currently assigned to you — no id needed.
+- Ask it to call `create_bug_report` with a `title` and plain-text
+  `description` to file something it noticed — pass `assignToSelf: true` to
+  claim it immediately.
 
 ## 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.
+- `fetch_bug_context` and `submit_bug_resolution` still need a report id —
+  this server doesn't search or browse. `fetch_assigned_bugs` is the one tool
+  that doesn't require knowing an id up front.

package/index.js

@@ -1,11 +1,19 @@
 #!/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 — four 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.
+//   - fetch_assigned_bugs: GET /api/admin/bug-reports/assigned — "what's on
+//     my plate", always the API key owner's own assigned reports.
+//   - create_bug_report: POST /api/admin/bug-reports/report — file a new bug
+//     the tool found, optionally self-assigning it.
+// 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 +29,30 @@ 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.2.0' });
+
+const BUG_SEVERITIES = ['low', 'medium', 'high', 'critical'];
+const BUG_STATUSES = ['open', 'in_progress', 'blocked', 'further_discussion', 'resolved'];
+const BUG_PROJECTS = ['wrapper', 'crm', 'fa', 'accounting', 'academy', 'itsm', 'studio'];
+
+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 +114,198 @@ 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 };
+  }
+);
+
+server.registerTool(
+  'fetch_assigned_bugs',
+  {
+    title: 'Fetch bugs assigned to me',
+    description:
+      "List Zopkit bug reports currently assigned to this API key's owner — \"what's on my plate\". " +
+      'Always the key owner\'s own assigned reports, never anyone else\'s, regardless of what the key ' +
+      'can otherwise see. Optionally filter by status.',
+    inputSchema: {
+      status: z.enum(BUG_STATUSES).optional().describe('Only return reports in this status.'),
+    },
+  },
+  async ({ status }) => {
+    if (!API_KEY) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'BUG_REPORT_API_KEY is not set on this MCP server — see README.md.' }],
+      };
+    }
+
+    const url = new URL(`${BASE_URL}/api/admin/bug-reports/assigned`);
+    if (status) url.searchParams.set('status', status);
+
+    let res;
+    try {
+      res = await fetch(url, { 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 assigned bugs: ${message}` }] };
+    }
+
+    const reports = body?.data || [];
+    if (reports.length === 0) {
+      return { content: [{ type: 'text', text: 'No bug reports currently assigned to you.' }] };
+    }
+
+    const summary = reports
+      .map((r) => `- [${r.severity}/${r.status}] ${r.title} (id: ${r.id})${r.project ? ` — project: ${r.project}` : ''}`)
+      .join('\n');
+
+    return { content: [{ type: 'text', text: `${reports.length} assigned report(s):\n${summary}` }] };
+  }
+);
+
+server.registerTool(
+  'create_bug_report',
+  {
+    title: 'Create a bug report',
+    description:
+      'File a new Zopkit bug report — e.g. something this tool noticed while working on something else. ' +
+      'Description is plain text (paragraphs separated by a blank line), not rich-text HTML.',
+    inputSchema: {
+      title: z.string().min(1).max(255).describe('A short, specific summary of the bug.'),
+      description: z.string().min(1).describe('The bug, in plain text — what happened, expected vs actual, repro steps.'),
+      severity: z.enum(BUG_SEVERITIES).optional().describe('Defaults to "medium".'),
+      project: z.enum(BUG_PROJECTS).optional().describe('Which product this bug is in, if known.'),
+      pageUrl: z.string().max(2048).optional().describe('The URL where the bug was observed, if applicable.'),
+      assignToSelf: z.boolean().optional().describe('Self-assign this report to the API key owner. Defaults to false (unassigned).'),
+    },
+  },
+  async ({ title, description, severity, project, pageUrl, assignToSelf }) => {
+    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/report`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
+        body: JSON.stringify({ title, description, severity, project, pageUrl, assignToSelf }),
+      });
+    } 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 create bug report: ${message}` }] };
+    }
+
+    const report = body?.data;
+    return {
+      content: [{
+        type: 'text',
+        text: report
+          ? `Bug report created: "${report.title}" (id: ${report.id}).`
+          : 'Bug report created.',
+      }],
+    };
+  }
+);
+
 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.2.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), submit how a bug was fixed, list bugs assigned to you, and file new bug reports. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) — see README.md.",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=18"