zopkit-bug-resolution-mcp 1.5.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # bug-resolution MCP server
 
-A five-tool MCP server so Claude Code (or Cursor, or any other MCP client)
+A six-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:
 
@@ -25,8 +25,22 @@ usage status — instead of hand-rolling curl commands:
   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 five are thin wrappers — see `backend/src/features/bug-reports/README.md`
+- **`report_claude_token_usage`** — unlike the one above, this one is NOT
+  self-attested: it scans this developer's own local Claude Code transcripts
+  (`~/.claude/projects/**/*.jsonl`, same machine the MCP server runs on — no
+  `/usage`, no status line, no asking a human) for the last 7 days, dedupes
+  streamed duplicates by `message.id`, and reports real input/output/
+  cache-creation/cache-read token totals, session count, and whether any
+  sessions used web search or spawned subagents, via
+  `POST /api/admin/claude-usage/token-breakdown`. Also runs automatically,
+  fire-and-forget, as a side effect of the four bug-report tools above
+  (`submit_bug_resolution`, `fetch_bug_context`, `fetch_assigned_bugs`,
+  `create_bug_report`) on success — so a developer who never touches this
+  tool directly still gets a token breakdown reported just by doing normal
+  bug-report work. Failures from the auto-report path are swallowed
+  entirely; they never surface as a tool error.
+
+All six 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.
 
@@ -120,7 +134,7 @@ whoever asked you to fix it).
    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:
+Four 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`,
@@ -137,6 +151,15 @@ Three more, independent of the fetch/resolve flow above:
   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").
+- Ask it to call `report_claude_token_usage` (no input needed) to push a
+  real token/session breakdown for the last 7 days up to the same "Claude
+  Usage" tab — distinct from and independent of `report_claude_usage`
+  above. You usually don't need to call this directly: it already fires
+  automatically after every successful `fetch_bug_context`,
+  `submit_bug_resolution`, `fetch_assigned_bugs`, or `create_bug_report`
+  call, and a short note gets appended to that tool's own response telling
+  you it happened (e.g. "Also updated your Claude token usage: 2.1M new
+  tokens across 3 session(s) this week.").
 
 ## Notes
 

package/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// bug-resolution MCP server — five tools wrapping the bug-reports resolution
+// bug-resolution MCP server — six 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:
@@ -14,11 +14,18 @@
 //     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
+//   - report_claude_usage: POST /api/admin/claude-usage — SELF-ATTESTED:
+//     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.
+//   - report_claude_token_usage: POST /api/admin/claude-usage/token-breakdown
+//     — REAL, not self-attested: scans this developer's own local Claude
+//     Code transcripts (~/.claude/projects/**/*.jsonl — this server runs on
+//     the same machine) for a 7-day token/web-search/subagent breakdown. The
+//     other four bug-resolution tools above also trigger this automatically
+//     as a fire-and-forget side effect (see tryAutoReportTokenUsage) — "every
+//     task done in the bug reporter" keeps this fresh with zero extra asks.
 // Thin wrapper: all the actual logic (auth, scoping, the DB writes) lives
 // server-side; this just forwards the HTTP calls the README documents.
 //
@@ -27,6 +34,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 
 const API_KEY = process.env.BUG_REPORT_API_KEY;
 const BASE_URL = (process.env.BUG_REPORT_API_BASE_URL || 'https://api.zopkit.com').replace(/\/$/, '');
@@ -36,7 +46,7 @@ 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.5.0' });
+const server = new McpServer({ name: 'zopkit-bug-resolution', version: '1.6.0' });
 
 const BUG_SEVERITIES = ['low', 'medium', 'high', 'critical'];
 // Keep in sync with BUG_STATUSES in backend/src/db/schema/platform/bug-reports.ts.
@@ -66,6 +76,194 @@ async function fetchImageContentBlock(url) {
   return { type: 'image', data: buffer.toString('base64'), mimeType: contentType };
 }
 
+// ── Token usage breakdown (report_claude_token_usage) ──────────────────────
+// Unlike usagePercent (self-attested, see submit_bug_resolution's comment on
+// why), this is read straight off Claude Code's own local transcript files —
+// this MCP server is a local process on the SAME machine as the Claude Code
+// session using it, so it can read ~/.claude/projects/**/*.jsonl directly.
+// No statusLine setup, no asking a human, no per-seat API that doesn't exist.
+//
+// Each API response gets logged 2-3x in these files (streaming writes the
+// same final usage numbers once per content-block flush) — every count below
+// dedupes by message.id, or totals would be inflated 2-3x.
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+const SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
+
+function listRecentTranscripts(sinceMs) {
+  const files = [];
+  let projectDirs;
+  try {
+    projectDirs = readdirSync(PROJECTS_DIR, { withFileTypes: true });
+  } catch {
+    return files; // no ~/.claude/projects at all — nothing to scan
+  }
+  for (const projectDir of projectDirs) {
+    if (!projectDir.isDirectory()) continue;
+    const dirPath = join(PROJECTS_DIR, projectDir.name);
+    let entries;
+    try {
+      entries = readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+      const filePath = join(dirPath, entry.name);
+      try {
+        if (statSync(filePath).mtimeMs >= sinceMs) files.push(filePath);
+      } catch {
+        // file vanished between readdir and stat — skip
+      }
+    }
+  }
+  return files;
+}
+
+/** One session's token totals + what it used — null if the file had nothing
+ *  in range (e.g. mtime was recent but every logged message predates sinceMs). */
+function scanTranscript(filePath, sinceMs) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const seenMessageIds = new Set();
+  let inputTokens = 0, outputTokens = 0, cacheCreationTokens = 0, cacheReadTokens = 0;
+  let usedWebSearch = false, usedSubagents = false;
+  let startedAt = null, cwd = null;
+
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // truncated/partial last line — skip it, not the whole file
+    }
+    if (entry.type !== 'assistant' || !entry.message) continue;
+    if (entry.timestamp && Date.parse(entry.timestamp) < sinceMs) continue;
+
+    if (cwd === null && entry.cwd) cwd = entry.cwd;
+    if (entry.timestamp && (!startedAt || entry.timestamp < startedAt)) startedAt = entry.timestamp;
+
+    // Tool-use detection runs on every line, duplicates included — setting a
+    // boolean true twice is harmless, unlike double-counting tokens below.
+    if (Array.isArray(entry.message.content)) {
+      for (const block of entry.message.content) {
+        if (block?.type === 'tool_use' && SUBAGENT_TOOL_NAMES.has(block.name)) usedSubagents = true;
+      }
+    }
+
+    const messageId = entry.message.id;
+    if (messageId) {
+      if (seenMessageIds.has(messageId)) continue;
+      seenMessageIds.add(messageId);
+    }
+
+    const usage = entry.message.usage;
+    if (!usage) continue;
+    inputTokens += usage.input_tokens || 0;
+    outputTokens += usage.output_tokens || 0;
+    cacheCreationTokens += usage.cache_creation_input_tokens || 0;
+    cacheReadTokens += usage.cache_read_input_tokens || 0;
+    const serverTools = usage.server_tool_use;
+    if (serverTools && ((serverTools.web_search_requests || 0) > 0 || (serverTools.web_fetch_requests || 0) > 0)) {
+      usedWebSearch = true;
+    }
+  }
+
+  const totalTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
+  if (totalTokens === 0) return null;
+  return { totalTokens, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, usedWebSearch, usedSubagents, startedAt, cwd };
+}
+
+/** Scans every local Claude Code transcript touched in the last `days` days
+ *  and aggregates it into the shape reportClaudeTokenUsageSchema expects.
+ *  Deliberately NOT scoped to this repo/project — the whole point is "how
+ *  much Claude Code usage this week", same scope /usage itself reports. */
+function computeWeeklyTokenBreakdown(days = 7) {
+  const sinceMs = Date.now() - days * 24 * 60 * 60 * 1000;
+  const sessions = listRecentTranscripts(sinceMs)
+    .map((f) => scanTranscript(f, sinceMs))
+    .filter((s) => s !== null);
+
+  const totals = sessions.reduce(
+    (acc, s) => ({
+      inputTokens: acc.inputTokens + s.inputTokens,
+      outputTokens: acc.outputTokens + s.outputTokens,
+      cacheCreationTokens: acc.cacheCreationTokens + s.cacheCreationTokens,
+      cacheReadTokens: acc.cacheReadTokens + s.cacheReadTokens,
+    }),
+    { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 }
+  );
+
+  const topSessions = [...sessions]
+    .sort((a, b) => b.totalTokens - a.totalTokens)
+    .slice(0, 5)
+    .map((s) => ({
+      totalTokens: s.totalTokens,
+      startedAt: s.startedAt || new Date(sinceMs).toISOString(),
+      cwd: s.cwd,
+      usedWebSearch: s.usedWebSearch,
+      usedSubagents: s.usedSubagents,
+    }));
+
+  return {
+    periodStart: new Date(sinceMs).toISOString(),
+    periodEnd: new Date().toISOString(),
+    ...totals,
+    sessionCount: sessions.length,
+    sessionsWithWebSearch: sessions.filter((s) => s.usedWebSearch).length,
+    sessionsWithSubagents: sessions.filter((s) => s.usedSubagents).length,
+    topSessions,
+  };
+}
+
+/** "585k" / "2.3M" / "1.1B" — raw token counts in a long session routinely
+ *  reach the hundreds of millions (every turn re-pays for its whole cached
+ *  context, so cache-read alone compounds fast), so a plain toLocaleString()
+ *  reads as an alarming wall of digits. Still real numbers — just formatted
+ *  for a human skimming a report, not a ledger. */
+function formatTokenCount(n) {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(0)}k`;
+  return String(n);
+}
+
+/** input + output + cache-WRITE tokens — genuinely new content processed
+ *  this period. Deliberately excludes cache-READ: that's a heavily-discounted
+ *  re-read of context already paid for once, and in a long session it
+ *  dwarfs everything else by 10-100x, so folding it into one headline
+ *  number would make "new work this week" unreadable. Still reported
+ *  separately in full (see the schema) — just not what ranks/headlines. */
+function newTokenCount(breakdown) {
+  return breakdown.inputTokens + breakdown.outputTokens + breakdown.cacheCreationTokens;
+}
+
+/** Fire-and-forget: scan + POST the breakdown, swallowing any failure (a
+ *  missing ~/.claude/projects dir, a network blip, whatever) — this must
+ *  never fail or slow down the tool call it's piggybacking on. Returns a
+ *  short status string for an optional footer, or null if it didn't run. */
+async function tryAutoReportTokenUsage() {
+  if (!API_KEY) return null;
+  try {
+    const breakdown = computeWeeklyTokenBreakdown();
+    if (breakdown.sessionCount === 0) return null;
+    const res = await fetch(`${BASE_URL}/api/admin/claude-usage/token-breakdown`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
+      body: JSON.stringify(breakdown),
+    });
+    if (!res.ok) return null;
+    return `${formatTokenCount(newTokenCount(breakdown))} new tokens across ${breakdown.sessionCount} session(s) this week`;
+  } catch {
+    return null; // never let this break the real tool call
+  }
+}
+
 server.registerTool(
   'submit_bug_resolution',
   {
@@ -116,12 +314,13 @@ server.registerTool(
     }
 
     const report = body?.data;
+    const usageNote = await tryAutoReportTokenUsage();
     return {
       content: [{
         type: 'text',
-        text: report
+        text: (report
           ? `Resolution submitted. "${report.title}" is now ${report.status}.`
-          : 'Resolution submitted.',
+          : 'Resolution submitted.') + (usageNote ? `\n\n(Also updated your Claude token usage: ${usageNote}.)` : ''),
       }],
     };
   }
@@ -209,6 +408,9 @@ server.registerTool(
       }
     }
 
+    const usageNote = await tryAutoReportTokenUsage();
+    if (usageNote) content.push({ type: 'text', text: `(Also updated your Claude token usage: ${usageNote}.)` });
+
     return { content };
   }
 );
@@ -282,7 +484,13 @@ server.registerTool(
       ? `${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}` }] };
+    const usageNote = await tryAutoReportTokenUsage();
+    return {
+      content: [{
+        type: 'text',
+        text: `${header}\n${summary}` + (usageNote ? `\n\n(Also updated your Claude token usage: ${usageNote}.)` : ''),
+      }],
+    };
   }
 );
 
@@ -332,12 +540,13 @@ server.registerTool(
     }
 
     const report = body?.data;
+    const usageNote = await tryAutoReportTokenUsage();
     return {
       content: [{
         type: 'text',
-        text: report
+        text: (report
           ? `Bug report created: "${report.title}" (id: ${report.id}).`
-          : 'Bug report created.',
+          : 'Bug report created.') + (usageNote ? `\n\n(Also updated your Claude token usage: ${usageNote}.)` : ''),
       }],
     };
   }
@@ -401,5 +610,68 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  'report_claude_token_usage',
+  {
+    title: 'Report Claude token usage breakdown',
+    description:
+      "Scans this developer's own local Claude Code transcripts " +
+      '(~/.claude/projects/**/*.jsonl — this MCP server runs on the same machine, so it can read them ' +
+      'directly) and reports a real token-usage breakdown for the last 7 days: total tokens, how many ' +
+      'sessions, and how many of those sessions used web search or spawned a subagent. Unlike ' +
+      "report_claude_usage's percentage, nothing here is self-attested — every number is read off real " +
+      'local files, so call this freely with no arguments; it never needs to ask a human for anything. ' +
+      "The other bug-resolution tools already call this automatically as a side effect, so you usually " +
+      "don't need to call it directly — this exists for an explicit, on-demand check.",
+    inputSchema: {},
+  },
+  async () => {
+    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 breakdown = computeWeeklyTokenBreakdown();
+    if (breakdown.sessionCount === 0) {
+      return {
+        content: [{ type: 'text', text: 'No Claude Code transcripts found in the last 7 days under ~/.claude/projects — nothing to report.' }],
+      };
+    }
+
+    let res;
+    try {
+      res = await fetch(`${BASE_URL}/api/admin/claude-usage/token-breakdown`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
+        body: JSON.stringify(breakdown),
+      });
+    } 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 token usage: ${message}` }] };
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Reported ${formatTokenCount(newTokenCount(breakdown))} new tokens ` +
+          `(plus ${formatTokenCount(breakdown.cacheReadTokens)} discounted cache-read re-reads) ` +
+          `across ${breakdown.sessionCount} session(s) this week ` +
+          `(${breakdown.sessionsWithWebSearch} used web search, ${breakdown.sessionsWithSubagents} used subagents).`,
+      }],
+    };
+  }
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "zopkit-bug-resolution-mcp",
-  "version": "1.5.0",
+  "version": "1.6.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, 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.",
+  "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, report your Claude Code usage status, and report a real weekly token-usage breakdown from your local transcripts. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) — see README.md.",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=18"