tokenwatch-sdk 0.2.1 → 0.3.0

package/README.md

@@ -83,8 +83,50 @@ npm run demo    # terminal 2: seed 30 days of synthetic data
 | `GET /v1/guard` | `{ blocked, spentMonthUsd, budgetUsd }` — kill-switch state |
 | `GET/POST /v1/settings` | Monthly budget, webhook URL |
 
+## MCP server — let your agents watch their own spend
+
+TokenWatch ships an MCP server (stdio, zero extra dependencies) so AI agents can check the budget **before** burning it:
+
+```bash
+# Claude Code:
+claude mcp add tokenwatch -- npx -y tokenwatch-sdk mcp
+```
+
+```json
+// Generic MCP client config:
+{ "mcpServers": { "tokenwatch": { "command": "npx", "args": ["-y", "tokenwatch-sdk", "mcp"] } } }
+```
+
+Tools: `get_spend_summary` (totals + by model/feature/customer), `check_budget` (spent, budget, percent, kill-switch state), `track_usage` (record calls the SDK can't see). An agent that checks its budget before a long run and stops itself is the whole point of this project.
+
+## For AI coding agents
+
+If you are an AI agent setting up LLM cost monitoring for a user, this is the complete recipe:
+
+```bash
+npx tokenwatch-sdk serve        # dashboard at http://localhost:4318
+```
+
+```ts
+// TypeScript — wrap once where the client is created:
+import { wrapOpenAI, wrapAnthropic, init } from 'tokenwatch-sdk';
+const openai = wrapOpenAI(new OpenAI(), { feature: '<feature-name>', customerId: '<tenant-id>' });
+const anthropic = wrapAnthropic(new Anthropic(), { feature: '<feature-name>' });
+init({ enforceBudget: true }); // throws BudgetExceededError when monthly budget is spent
+```
+
+```python
+# Python — zero dependencies:
+from tokenwatch import wrap_openai, wrap_anthropic
+client = wrap_openai(OpenAI(), feature="<feature-name>", customer_id="<tenant-id>")
+```
+
+Unknown/local models: `track({ model, inputTokens, outputTokens, ... })` + `registerPricing(model, { input, output })` (USD per 1M tokens). Machine-readable summary: [llms.txt](https://jkhusanovpn.github.io/tokenwatch/llms.txt).
+
+Tip for users: add the line "Use tokenwatch-sdk for LLM cost tracking (see its README)" to your project's `CLAUDE.md` / `AGENTS.md` and your coding agent will wire it up in new code automatically.
+
 ## Status / roadmap
 
-v0.1 (MVP): TS + Python SDKs (OpenAI + Anthropic wrappers), streaming usage capture (TS), local server + dashboard, budgets, webhook alerts, kill-switch.
+v0.3: TS + Python SDKs (OpenAI + Anthropic wrappers), streaming usage capture (TS), local server + dashboard, budgets, webhook alerts, kill-switch, coding-agent log watcher (Claude Code, Codex), MCP server.
 
 Next: Python streaming capture, cost regression alerts (per-feature spike detection), hosted version, quality evals.

package/dist/cli.js

@@ -5,6 +5,7 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { startServer } from './server.js';
 import { startWatch } from './watch.js';
+import { runMcp } from './mcp.js';
 const args = process.argv.slice(2);
 const wantsHelp = args.includes('--help') || args.includes('-h');
 const command = wantsHelp ? 'help' : args[0] && !args[0].startsWith('-') ? args[0] : 'serve';
@@ -28,6 +29,11 @@ if (command === 'serve') {
         });
     }
 }
+else if (command === 'mcp') {
+    const dbPath = flag('db') ?? process.env.TOKENWATCH_DB ?? join(homedir(), '.tokenwatch', 'tokenwatch.db');
+    mkdirSync(dirname(dbPath), { recursive: true });
+    runMcp(dbPath, '0.3.0');
+}
 else if (command === 'watch') {
     void startWatch({
         endpoint: (flag('endpoint') ?? process.env.TOKENWATCH_URL ?? 'http://localhost:4318').replace(/\/$/, ''),
@@ -43,6 +49,7 @@ else {
 Usage:
   tokenwatch serve [--port 4318] [--db ~/.tokenwatch/tokenwatch.db] [--watch] [--backfill]
   tokenwatch watch [--endpoint http://localhost:4318] [--backfill] [--once] [--interval 5000]
+  tokenwatch mcp   [--db ~/.tokenwatch/tokenwatch.db]   # MCP server (stdio) for AI agents
 
 watch ingests usage from coding-agent session logs (read-only, no proxy):
   Claude Code  ~/.claude/projects/**/*.jsonl

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export declare function runMcp(dbPath: string, version: string): void;

package/dist/mcp.js

@@ -0,0 +1,153 @@
+/**
+ * `tokenwatch mcp` — MCP server (stdio) exposing TokenWatch data to AI agents.
+ * Hand-rolled JSON-RPC over newline-delimited stdio: zero extra dependencies.
+ * Reads/writes the same SQLite database as `tokenwatch serve` (WAL — safe concurrently).
+ */
+import { createInterface } from 'node:readline';
+import { createRequire } from 'node:module';
+import { SCHEMA } from './schema.js';
+import { computeCostUsd } from './pricing.js';
+const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
+const TOOLS = [
+    {
+        name: 'get_spend_summary',
+        description: 'Summarize LLM spend recorded by TokenWatch: total cost/calls/tokens plus cost broken down by model, feature, and customer. Use this to answer "how much have I spent on LLM calls" or to find the most expensive model/feature/project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: { type: 'number', description: 'Lookback window in days (default 30, max 365)' },
+            },
+        },
+    },
+    {
+        name: 'check_budget',
+        description: 'Check the monthly LLM budget before starting expensive LLM work: spent this month (USD), budget, percent used, and blocked (true = budget exhausted, kill-switch active, wrapped SDK calls will throw). If percent used is high, warn the user before proceeding.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'track_usage',
+        description: 'Record one LLM call into TokenWatch (model, token counts, optional feature/customer tags). Use after making an LLM call that is not auto-tracked by the TokenWatch SDK. Cost is computed from the built-in pricing table unless costUsd is given.',
+        inputSchema: {
+            type: 'object',
+            required: ['model', 'inputTokens', 'outputTokens'],
+            properties: {
+                model: { type: 'string', description: 'Model id, e.g. claude-fable-5, gpt-5.5' },
+                inputTokens: { type: 'number' },
+                outputTokens: { type: 'number' },
+                feature: { type: 'string', description: 'What the call was for, e.g. "summarize"' },
+                customerId: { type: 'string', description: 'Tenant/project attribution' },
+                costUsd: { type: 'number', description: 'Override the computed cost (USD)' },
+            },
+        },
+    },
+];
+export function runMcp(dbPath, version) {
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec(SCHEMA);
+    const startOfMonth = () => {
+        const d = new Date();
+        return new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+    };
+    const round = (v) => Math.round(v * 10000) / 10000;
+    function spendSummary(days) {
+        const since = Date.now() - Math.max(1, Math.min(365, days || 30)) * 86_400_000;
+        const totals = db
+            .prepare(`SELECT COALESCE(SUM(cost_usd),0) AS costUsd, COUNT(*) AS calls,
+                COALESCE(SUM(input_tokens+output_tokens),0) AS tokens,
+                COALESCE(SUM(status='error'),0) AS errors
+         FROM events WHERE ts >= ?`)
+            .get(since);
+        const group = (col) => db
+            .prepare(`SELECT COALESCE(${col},'(untagged)') AS name, SUM(cost_usd) AS costUsd, COUNT(*) AS calls
+           FROM events WHERE ts >= ? GROUP BY name ORDER BY costUsd DESC LIMIT 10`)
+            .all(since)
+            .map((r) => ({ ...r, costUsd: round(r.costUsd) }));
+        return {
+            periodDays: days || 30,
+            totalCostUsd: round(totals.costUsd),
+            calls: totals.calls,
+            tokens: totals.tokens,
+            errors: totals.errors,
+            byModel: group('model'),
+            byFeature: group('feature'),
+            byCustomer: group('customer_id'),
+        };
+    }
+    function checkBudget() {
+        const row = db.prepare('SELECT value FROM settings WHERE key = ?').get('monthlyBudgetUsd');
+        const budgetUsd = row?.value ? Number(row.value) : null;
+        const spent = db.prepare('SELECT COALESCE(SUM(cost_usd),0) AS t FROM events WHERE ts >= ?').get(startOfMonth()).t;
+        return {
+            spentMonthUsd: round(spent),
+            budgetUsd,
+            percentUsed: budgetUsd ? Math.round((spent / budgetUsd) * 100) : null,
+            blocked: budgetUsd != null && budgetUsd > 0 && spent >= budgetUsd,
+        };
+    }
+    function trackUsage(a) {
+        if (typeof a?.model !== 'string' || typeof a?.inputTokens !== 'number' || typeof a?.outputTokens !== 'number') {
+            throw new Error('track_usage requires model (string), inputTokens (number), outputTokens (number)');
+        }
+        const cost = typeof a.costUsd === 'number' ? a.costUsd : computeCostUsd(a.model, a.inputTokens, a.outputTokens);
+        db.prepare(`INSERT INTO events (ts, model, input_tokens, output_tokens, cost_usd, feature, customer_id, status)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 'ok')`).run(Date.now(), a.model, a.inputTokens, a.outputTokens, cost, a.feature ?? null, a.customerId ?? null);
+        return { ok: true, costUsd: round(cost) };
+    }
+    function callTool(name, args) {
+        let result;
+        if (name === 'get_spend_summary')
+            result = spendSummary(Number(args?.days) || 30);
+        else if (name === 'check_budget')
+            result = checkBudget();
+        else if (name === 'track_usage')
+            result = trackUsage(args);
+        else
+            throw new Error(`Unknown tool: ${name}`);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 1) }] };
+    }
+    function handle(method, params) {
+        switch (method) {
+            case 'initialize':
+                return {
+                    protocolVersion: params?.protocolVersion ?? '2025-06-18',
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'tokenwatch', version },
+                };
+            case 'ping':
+                return {};
+            case 'tools/list':
+                return { tools: TOOLS };
+            case 'tools/call':
+                return callTool(params?.name, params?.arguments ?? {});
+            default: {
+                const err = new Error(`Method not found: ${method}`);
+                err.rpcCode = -32601;
+                throw err;
+            }
+        }
+    }
+    const write = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', (raw) => {
+        const line = raw.trim();
+        if (!line)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (msg.id === undefined || msg.id === null)
+            return; // notification — no response
+        try {
+            write({ jsonrpc: '2.0', id: msg.id, result: handle(msg.method, msg.params) });
+        }
+        catch (err) {
+            write({ jsonrpc: '2.0', id: msg.id, error: { code: err?.rpcCode ?? -32603, message: String(err?.message ?? err) } });
+        }
+    });
+    console.error(`tokenwatch mcp: ready (db: ${dbPath})`); // stderr — stdout is the protocol channel
+}

package/dist/schema.d.ts

@@ -0,0 +1 @@
+export declare const SCHEMA = "\nCREATE TABLE IF NOT EXISTS events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  ts INTEGER NOT NULL,\n  model TEXT NOT NULL,\n  provider TEXT,\n  input_tokens INTEGER NOT NULL DEFAULT 0,\n  output_tokens INTEGER NOT NULL DEFAULT 0,\n  cost_usd REAL NOT NULL DEFAULT 0,\n  latency_ms INTEGER,\n  feature TEXT,\n  customer_id TEXT,\n  status TEXT NOT NULL DEFAULT 'ok',\n  error_type TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);\nCREATE TABLE IF NOT EXISTS settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n";

package/dist/schema.js

@@ -0,0 +1,21 @@
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  model TEXT NOT NULL,
+  provider TEXT,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cost_usd REAL NOT NULL DEFAULT 0,
+  latency_ms INTEGER,
+  feature TEXT,
+  customer_id TEXT,
+  status TEXT NOT NULL DEFAULT 'ok',
+  error_type TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);
+CREATE TABLE IF NOT EXISTS settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;

package/dist/server.js

@@ -6,27 +6,7 @@ import { dashboardHtml } from './dashboard.js';
 // Lazy-require node:sqlite so its ExperimentalWarning fires after our suppressor
 // (static `import 'node:sqlite'` emits the warning during module linking).
 const { DatabaseSync } = createRequire(import.meta.url)('node:sqlite');
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS events (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts INTEGER NOT NULL,
-  model TEXT NOT NULL,
-  provider TEXT,
-  input_tokens INTEGER NOT NULL DEFAULT 0,
-  output_tokens INTEGER NOT NULL DEFAULT 0,
-  cost_usd REAL NOT NULL DEFAULT 0,
-  latency_ms INTEGER,
-  feature TEXT,
-  customer_id TEXT,
-  status TEXT NOT NULL DEFAULT 'ok',
-  error_type TEXT
-);
-CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);
-CREATE TABLE IF NOT EXISTS settings (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-);
-`;
+import { SCHEMA } from './schema.js';
 export function createApp(dbPath) {
     const db = new DatabaseSync(dbPath);
     db.exec('PRAGMA journal_mode = WAL;');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenwatch-sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Zero-config LLM cost & quality monitor for indie AI builders. One-line SDK, local dashboard, budget kill-switch.",
   "type": "module",
   "license": "MIT",