zopkit-bug-resolution-mcp 1.2.0 → 1.5.0

package/README.md

@@ -1,24 +1,34 @@
 # bug-resolution MCP server
 
-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:
+A five-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 — plus report
+usage status — 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`.
+  `GET /api/admin/bug-reports/context/:id`. Calling it IS starting work on
+  the ticket: `open`/`failed_testing` auto-moves to `in_progress` as a side
+  effect (anything further along is left untouched).
 - **`submit_bug_resolution`** — writes back how it was fixed as a Markdown
-  writeup and moves the report to `resolved`, via
+  writeup and moves the report to `needs_testing` (not `resolved` — a human
+  still verifies the fix first), 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
+  key's owner ("what's on my plate"), defaulting to everything but
+  `resolved` and sorted by what needs attention soonest, optionally filtered
+  to specific statuses and paginated, 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`.
+- **`report_claude_usage`** — self-reports this developer's current Claude
+  Code usage percentage (there's no API to fetch it on your behalf — see
+  `backend/src/features/claude-usage/README.md`), shown on the
+  company-admin panel's "Claude Usage" tab, via `POST /api/admin/claude-usage`.
 
-All four are thin wrappers — see `backend/src/features/bug-reports/README.md`
-for what each endpoint actually does server-side.
+All five are thin wrappers — see `backend/src/features/bug-reports/README.md`
+and `backend/src/features/claude-usage/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)
@@ -62,6 +72,19 @@ Published to npm as
    elsewhere (e.g. a local dev backend) with an extra env var,
    `BUG_REPORT_API_BASE_URL=http://localhost:3000`.
 
+   **On Windows**, a bare `npx` command as shown above commonly fails or
+   hangs (MCP client "connection timed out after 30000ms") — Windows needs
+   `npx.cmd` resolved through `cmd.exe`, not the bare `npx` name spawn()
+   looks for on macOS/Linux. Route it through `cmd /c` instead:
+
+   ```bash
+   claude mcp add bug-resolution \
+     --env BUG_REPORT_API_KEY=<the key you copied> \
+     -- cmd /c npx -y zopkit-bug-resolution-mcp
+   ```
+
+   or in the JSON config, `"command": "cmd", "args": ["/c", "npx", "-y", "zopkit-bug-resolution-mcp"]`.
+
 3. Restart Claude Code (or Claude Desktop) and approve `bug-resolution` when
    prompted.
 
@@ -89,18 +112,31 @@ 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.
+   reading a URL to it. This call also moves the board card to `In
+   Progress` if it was sitting at `Open`/`Failed Testing` — the board
+   reflects that work has started without anyone dragging the card by hand.
 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.
+   writeup and moves its status to `needs_testing` — a human still needs to
+   verify it before it's `resolved`.
+
+Three more, independent of the fetch/resolve flow above:
+
+- Ask it to call `fetch_assigned_bugs` to see what's currently assigned to
+  you — no id needed. By default it shows everything except `resolved`,
+  ranked by what needs your attention soonest (a fix QA bounced back first,
+  then active work, then fixes just waiting on QA). Pass
+  `status: ['failed_testing']` etc. to narrow it down, or `status: ['all']`
+  to include resolved history; `limit`/`offset` page past the first batch
+  if it says there's more.
 - 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.
+- Ask it to call `report_claude_usage` with your current usage `%` (from
+  `/usage`, the status line, or the account's billing page — there's no way
+  for the tool to look this up itself) to update the "Claude Usage" tab in
+  the company-admin panel. Pass an optional `note` for context (e.g. "Team
+  plan, resets Monday").
 
 ## Notes
 

package/index.js

@@ -1,17 +1,24 @@
 #!/usr/bin/env node
-// bug-resolution MCP server — four tools wrapping the bug-reports resolution
+// bug-resolution MCP server — five 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.
+//     inline screenshot as real image content. Also IS "starting work on
+//     it": open/failed_testing auto-moves to in_progress as a side effect.
 //   - submit_bug_resolution: POST /api/admin/bug-reports/resolution/:id —
-//     writes back the fix as a Markdown resolution and marks it resolved.
+//     writes back the fix as a Markdown resolution and moves it to
+//     needs_testing (not resolved — a human verifies it first).
 //   - 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.
+//   - report_claude_usage: POST /api/admin/claude-usage — self-reports this
+//     developer's current Claude Code usage percentage (see
+//     backend/src/features/claude-usage/README.md for why this is
+//     self-reported rather than fetched from an Anthropic API), shown on
+//     the company-admin panel's "Claude Usage" tab.
 // Thin wrapper: all the actual logic (auth, scoping, the DB writes) lives
 // server-side; this just forwards the HTTP calls the README documents.
 //
@@ -29,11 +36,16 @@ 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.2.0' });
+const server = new McpServer({ name: 'zopkit-bug-resolution', version: '1.5.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'];
+// Keep in sync with BUG_STATUSES in backend/src/db/schema/platform/bug-reports.ts.
+// This list was missing needs_testing/failed_testing for a while, which meant
+// fetch_assigned_bugs couldn't even be asked to filter to exactly the two
+// statuses a developer cares about most (a fresh fix bounced back by QA, or
+// one still waiting on QA) — the backend has allowed both for a while.
+const BUG_STATUSES = ['open', 'in_progress', 'needs_testing', 'failed_testing', 'blocked', 'further_discussion', 'resolved'];
+const BUG_PROJECTS = ['wrapper', 'crm', 'fa', 'accounting', 'academy', 'itsm', 'studio', 'retail_erp', 'entertainment_erp'];
 
 const IMG_SRC = /<img\b[^>]*\bsrc="([^"]+)"[^>]*>/gi;
 
@@ -60,7 +72,8 @@ server.registerTool(
     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 " +
+      "Markdown writeup and moves its status to 'needs_testing' — NOT 'resolved' directly; a human " +
+      "still needs to verify the fix before it's truly done. 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)."),
@@ -122,7 +135,10 @@ server.registerTool(
       '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.',
+      "opening the admin panel. Screenshots come back as image content alongside the text summary. " +
+      "Calling this IS starting work on it: a report sitting at 'open' or 'failed_testing' moves " +
+      "straight to 'in_progress' as a side effect (anything further along — in_progress itself, " +
+      "needs_testing, blocked, further_discussion, resolved — is left untouched).",
     inputSchema: {
       bugReportId: z.string().min(1).describe("The bug report's id (UUID)."),
     },
@@ -203,13 +219,24 @@ server.registerTool(
     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.',
+      "Always the key owner's own assigned reports, never anyone else's, regardless of what the key " +
+      "can otherwise see. Defaults to every status EXCEPT 'resolved' (pass status: ['all'] to include " +
+      "resolved history too), sorted with whatever needs attention soonest first (a fix QA bounced back " +
+      "via 'failed_testing', then active work, then fixes merely awaiting QA). Paginated — use limit/offset " +
+      'if the result says there are more than fit on one page.',
     inputSchema: {
-      status: z.enum(BUG_STATUSES).optional().describe('Only return reports in this status.'),
+      status: z
+        .array(z.enum([...BUG_STATUSES, 'all']))
+        .optional()
+        .describe(
+          "One or more statuses to filter to. Omit for the default (everything but 'resolved'); " +
+          "pass ['all'] to include resolved history too."
+        ),
+      limit: z.number().int().min(1).max(100).optional().describe('Max reports to return (default 50, max 100).'),
+      offset: z.number().int().min(0).optional().describe('Skip this many reports, for paging past the first batch.'),
     },
   },
-  async ({ status }) => {
+  async ({ status, limit, offset }) => {
     if (!API_KEY) {
       return {
         isError: true,
@@ -218,7 +245,9 @@ server.registerTool(
     }
 
     const url = new URL(`${BASE_URL}/api/admin/bug-reports/assigned`);
-    if (status) url.searchParams.set('status', status);
+    if (status?.length) url.searchParams.set('status', status.join(','));
+    if (limit != null) url.searchParams.set('limit', String(limit));
+    if (offset != null) url.searchParams.set('offset', String(offset));
 
     let res;
     try {
@@ -238,15 +267,22 @@ server.registerTool(
     }
 
     const reports = body?.data || [];
+    const meta = body?.meta;
     if (reports.length === 0) {
-      return { content: [{ type: 'text', text: 'No bug reports currently assigned to you.' }] };
+      return { content: [{ type: 'text', text: 'No bug reports currently assigned to you (in the requested status(es)).' }] };
     }
 
     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}` }] };
+    // meta.total counts everything matching the filter, not just this page —
+    // say so explicitly instead of letting a truncated page read as "that's all of it".
+    const header = meta && meta.total > reports.length
+      ? `${reports.length} of ${meta.total} assigned report(s) (showing offset ${meta.offset}–${meta.offset + reports.length - 1}; pass a higher offset for more):`
+      : `${reports.length} assigned report(s):`;
+
+    return { content: [{ type: 'text', text: `${header}\n${summary}` }] };
   }
 );
 
@@ -307,5 +343,63 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  'report_claude_usage',
+  {
+    title: 'Report Claude usage status',
+    description:
+      "Report this developer's current Claude Code account/session usage percentage, shown on the " +
+      'company-admin panel\'s "Claude Usage" tab. Self-reported — there is no API to fetch this on your ' +
+      'behalf (Anthropic has no per-seat "current usage %" endpoint, and the percentage Claude Code\'s own ' +
+      '/usage shows is computed client-side from this session\'s own rate-limit headers, not retrievable by ' +
+      'a third party). Pass whatever percentage you or the user currently see — e.g. from the /usage ' +
+      "command, the status line, or the account's billing page. Identity (who this is) is resolved from " +
+      'your API key, not from anything passed here.',
+    inputSchema: {
+      usagePercent: z.number().min(0).max(100).describe('Current usage, 0-100 (fractional values like 72.5 are fine).'),
+      note: z.string().max(500).optional().describe('Optional context, e.g. "Team plan, resets Monday".'),
+    },
+  },
+  async ({ usagePercent, note }) => {
+    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/claude-usage`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
+        body: JSON.stringify({ usagePercent, note }),
+      });
+    } 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 report Claude usage: ${message}` }] };
+    }
+
+    const status = body?.data;
+    return {
+      content: [{
+        type: 'text',
+        text: status
+          ? `Reported ${status.usagePercent}% usage for ${status.email}.`
+          : 'Usage reported.',
+      }],
+    };
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "zopkit-bug-resolution-mcp",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "type": "module",
-  "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.",
+  "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, file new bug reports, and report your Claude Code usage status. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) — see README.md.",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=18"