zopkit-bug-resolution-mcp 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# 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.
+
+## 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.
+
+2. **Register the server:**
+
+   ```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"
+   ```
+
+   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`.
+
+3. Restart Claude Code and approve `bug-resolution` when prompted.
+
+## 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`.
+
+## Notes
+
+- Not part of the pnpm workspace (`pnpm-workspace.yaml`) or the deployed
+  backend image — a standalone dev tool, installed with plain `npm install`.
+- 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.

package/index.js

@@ -0,0 +1,87 @@
+#!/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.
+//
+// Setup: see README.md in this directory.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const API_KEY = process.env.BUG_REPORT_API_KEY;
+const BASE_URL = (process.env.BUG_REPORT_API_BASE_URL || 'https://api.zopkit.com').replace(/\/$/, '');
+
+if (!API_KEY) {
+  console.error('[bug-resolution-mcp] BUG_REPORT_API_KEY is not set — every call will fail. ' +
+    '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' });
+
+server.registerTool(
+  'submit_bug_resolution',
+  {
+    title: 'Submit bug resolution',
+    description:
+      "Report how a Zopkit bug report was fixed. Sets the report's resolution notes to the given " +
+      "Markdown writeup and moves its status straight to 'resolved'. Use the bug report's id " +
+      '(a UUID, given to you by whoever asked you to fix it, or visible in its admin-panel URL).',
+    inputSchema: {
+      bugReportId: z.string().min(1).describe("The bug report's id (UUID)."),
+      markdown: z
+        .string()
+        .min(1)
+        .describe(
+          'The resolution writeup, as Markdown — root cause, the fix, files touched, ' +
+          'verification steps, links to the commit/PR. No length limit; be as thorough as warranted.'
+        ),
+    },
+  },
+  async ({ bugReportId, markdown }) => {
+    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/resolution/${encodeURIComponent(bugReportId)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
+        body: JSON.stringify({ markdown }),
+      });
+    } 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 submit resolution: ${message}` }] };
+    }
+
+    const report = body?.data;
+    return {
+      content: [{
+        type: 'text',
+        text: report
+          ? `Resolution submitted. "${report.title}" is now ${report.status}.`
+          : 'Resolution submitted.',
+      }],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "zopkit-bug-resolution-mcp",
+  "version": "1.0.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.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "index.js",
+  "bin": {
+    "zopkit-bug-resolution-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.24.0"
+  }
+}