tokenwatch-sdk 0.2.0 → 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.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import './suppress-warnings.js';

package/dist/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
+import './suppress-warnings.js';
 import { mkdirSync } from 'node:fs';
 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';
@@ -27,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(/\/$/, ''),
@@ -42,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.d.ts

@@ -1,8 +1,7 @@
 import { Hono } from 'hono';
-import { DatabaseSync } from 'node:sqlite';
 export declare function createApp(dbPath: string): {
     app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
-    db: DatabaseSync;
+    db: import("node:sqlite").DatabaseSync;
 };
 export declare function startServer(opts: {
     port: number;

package/dist/server.js

@@ -1,29 +1,12 @@
 import { Hono } from 'hono';
 import { serve } from '@hono/node-server';
-import { DatabaseSync } from 'node:sqlite';
+import { createRequire } from 'node:module';
 import { computeCostUsd } from './pricing.js';
 import { dashboardHtml } from './dashboard.js';
-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
-);
-`;
+// 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');
+import { SCHEMA } from './schema.js';
 export function createApp(dbPath) {
     const db = new DatabaseSync(dbPath);
     db.exec('PRAGMA journal_mode = WAL;');
@@ -167,6 +150,15 @@ export function createApp(dbPath) {
 export function startServer(opts) {
     const { app } = createApp(opts.dbPath);
     const server = serve({ fetch: app.fetch, port: opts.port });
+    server.on?.('error', (err) => {
+        if (err?.code === 'EADDRINUSE') {
+            console.error(`\nTokenWatch: port ${opts.port} is already in use.\n` +
+                `Probably another TokenWatch is running — open http://localhost:${opts.port} to check,\n` +
+                `or start on a different port:  tokenwatch serve --port ${opts.port + 1}\n`);
+            process.exit(1);
+        }
+        throw err;
+    });
     console.log(`TokenWatch running → http://localhost:${opts.port}  (db: ${opts.dbPath})`);
     return server;
 }

package/dist/suppress-warnings.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/suppress-warnings.js

@@ -0,0 +1,10 @@
+// Must be imported before any module that loads node:sqlite.
+// node:sqlite is stable for our use; hide the scary first-run ExperimentalWarning.
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+    const text = typeof warning === 'string' ? warning : warning?.message ?? '';
+    if (text.includes('SQLite is an experimental feature'))
+        return;
+    originalEmitWarning(warning, ...rest);
+});
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenwatch-sdk",
-  "version": "0.2.0",
+  "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",