getaimeter 0.8.1 → 0.10.0

package/cli.js

@@ -10,7 +10,7 @@ const { startTray, stopTray } = require('./tray');
 const command = process.argv[2] || 'help';
 
 // Version check on interactive commands (non-blocking)
-if (['setup', 'status', 'help', '--help', '-h'].includes(command)) {
+if (['setup', 'status', 'summary', 'help', '--help', '-h'].includes(command)) {
   checkForUpdate();
 }
 
@@ -24,9 +24,12 @@ switch (command) {
   case 'status':  runStatus();    break;
   case 'logs':    runLogs();      break;
   case 'key':     runKey();       break;
+  case 'summary': runSummary();   break;
+  case 'blocks':  runBlocks();    break;
   case 'version': case '--version': case '-v':
     console.log(getCurrentVersion());
     break;
+  case 'mcp':     runMcp();     break;
   case 'help': case '--help': case '-h':
     printHelp();
     break;
@@ -37,6 +40,41 @@ switch (command) {
     break;
 }
 
+// ---------------------------------------------------------------------------
+// fetchFromApi — shared helper for API calls (native https, zero deps)
+// ---------------------------------------------------------------------------
+
+function fetchFromApi(urlPath, apiKey) {
+  return new Promise((resolve, reject) => {
+    const https = require('https');
+    const options = {
+      hostname: 'aimeter-api.fly.dev',
+      port: 443,
+      path: urlPath,
+      method: 'GET',
+      headers: {
+        'X-AIMeter-Key': apiKey,
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try { resolve(JSON.parse(body)); }
+          catch { reject(new Error('Invalid JSON response')); }
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${body.slice(0, 200)}`));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(10000, () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.end();
+  });
+}
+
 // ---------------------------------------------------------------------------
 // setup — full onboarding wizard
 // ---------------------------------------------------------------------------
@@ -390,6 +428,195 @@ function runKey() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// mcp — start MCP server for Claude Code/Desktop
+// ---------------------------------------------------------------------------
+
+function runMcp() {
+  require('./mcp').startMcpServer();
+}
+
+// ---------------------------------------------------------------------------
+// summary — show current usage summary from API
+// ---------------------------------------------------------------------------
+
+async function runSummary() {
+  const https = require('https');
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.log('No API key configured. Run: aimeter setup');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Check for --json flag
+  const jsonMode = process.argv.includes('--json');
+
+  try {
+    // Fetch current usage from API
+    const data = await fetchFromApi('/api/usage/current', apiKey);
+
+    if (jsonMode) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+
+    // Pretty print
+    const fmtTokens = (n) => {
+      if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
+      if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+      return String(n);
+    };
+    const fmtCost = (c) => {
+      if (c >= 1) return `$${c.toFixed(2)}`;
+      if (c >= 0.01) return `$${c.toFixed(3)}`;
+      return `$${c.toFixed(4)}`;
+    };
+
+    // Calculate total cost from byModel
+    const totalCost = (data.byModel || []).reduce((sum, m) => sum + (m.estimatedCost || 0), 0);
+
+    // Reset countdown
+    let resetStr = 'N/A';
+    if (data.nextReset) {
+      const resetMs = new Date(data.nextReset) - Date.now();
+      if (resetMs > 0) {
+        const h = Math.floor(resetMs / 3600000);
+        const m = Math.floor((resetMs % 3600000) / 60000);
+        resetStr = `${h}h ${m}m`;
+      } else {
+        resetStr = 'now';
+      }
+    }
+
+    console.log('');
+    console.log('  AIMeter — Current Usage (5-hour window)');
+    console.log('  ════════════════════════════════════════');
+    console.log('');
+    console.log(`  Cost:        ${fmtCost(totalCost)}`);
+    console.log(`  Input:       ${fmtTokens(data.totalInputTokens || 0)}`);
+    console.log(`  Output:      ${fmtTokens(data.totalOutputTokens || 0)}`);
+    console.log(`  Thinking:    ${fmtTokens(data.totalThinkingTokens || 0)}`);
+    console.log(`  Cache Read:  ${fmtTokens(data.totalCacheReadTokens || 0)}`);
+    console.log(`  Requests:    ${data.windowRequests || 0}`);
+    console.log(`  Reset in:    ${resetStr}`);
+
+    // By source
+    if (data.bySource && data.bySource.length > 0) {
+      console.log('');
+      console.log('  By Source:');
+      const sourceLabels = {
+        cli: 'Terminal', vscode: 'VS Code', desktop_app: 'Desktop',
+        cursor: 'Cursor', codex_cli: 'Codex CLI', codex_vscode: 'Codex VS',
+        gemini_cli: 'Gemini', copilot_cli: 'Copilot', copilot_vscode: 'Copilot VS',
+      };
+      for (const s of data.bySource) {
+        const label = sourceLabels[s.source] || s.source;
+        console.log(`    ${label.padEnd(14)} ${String(s.requests).padStart(4)} req`);
+      }
+    }
+
+    // By model
+    if (data.byModel && data.byModel.length > 0) {
+      console.log('');
+      console.log('  By Model:');
+      for (const m of data.byModel) {
+        const label = m.model.replace(/-\d{8}$/, '');
+        console.log(`    ${label.padEnd(22)} ${String(m.requests).padStart(4)} req  ${fmtCost(m.estimatedCost || 0)}`);
+      }
+    }
+
+    // Previous window comparison
+    if (data.previous && data.previous.totalCost > 0) {
+      const prevCost = data.previous.totalCost;
+      const change = totalCost - prevCost;
+      const pct = prevCost > 0 ? ((change / prevCost) * 100).toFixed(0) : '∞';
+      const arrow = change >= 0 ? '↑' : '↓';
+      console.log('');
+      console.log(`  vs Previous: ${arrow} ${Math.abs(change).toFixed(2)} (${pct}%)`);
+    }
+
+    console.log('');
+  } catch (err) {
+    console.error(`Error fetching usage: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// blocks — show 5-hour billing blocks
+// ---------------------------------------------------------------------------
+
+async function runBlocks() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    console.log('No API key configured. Run: aimeter setup');
+    process.exitCode = 1;
+    return;
+  }
+
+  const jsonMode = process.argv.includes('--json');
+  const days = parseInt(process.argv[3]) || 3;
+
+  try {
+    const data = await fetchFromApi(`/api/usage/blocks?days=${days}`, apiKey);
+
+    if (jsonMode) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+
+    console.log('');
+    console.log(`  AIMeter — Billing Blocks (last ${days} days)`);
+    console.log('  ════════════════════════════════════════');
+    console.log('');
+
+    if (!data.blocks || data.blocks.length === 0) {
+      console.log('  No billing blocks found.');
+      console.log('');
+      return;
+    }
+
+    for (const block of data.blocks) {
+      const start = new Date(block.startTime);
+      const fmtTime = (d) => d.toLocaleString([], { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });
+      const active = block.isActive ? ' ◉ ACTIVE' : '';
+
+      console.log(`  ${fmtTime(start)}${active}`);
+      console.log(`  ────────────────────────────`);
+
+      const fmtCost = (c) => c >= 1 ? `$${c.toFixed(2)}` : `$${c.toFixed(3)}`;
+      const fmtTokens = (n) => {
+        if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+        if (n >= 1_000) return `${(n / 1_000).toFixed(0)}k`;
+        return String(n);
+      };
+
+      console.log(`    Cost: ${fmtCost(block.totalCost)}  |  Requests: ${block.requestCount}  |  Tokens: ${fmtTokens(block.totalInputTokens + block.totalOutputTokens)}`);
+
+      if (block.burnRate) {
+        console.log(`    Burn: ${fmtTokens(block.burnRate.tokensPerMinute)}/min  |  ${fmtCost(block.burnRate.costPerHour)}/hr`);
+      }
+
+      if (block.isActive && block.remainingMinutes > 0) {
+        const h = Math.floor(block.remainingMinutes / 60);
+        const m = Math.round(block.remainingMinutes % 60);
+        console.log(`    Remaining: ${h}h ${m}m`);
+      }
+
+      console.log(`    Sources: ${(block.sources || []).join(', ')}`);
+      console.log(`    Models: ${(block.models || []).join(', ')}`);
+      console.log('');
+    }
+
+    console.log(`  Total: ${data.totalBlocks} blocks, $${data.totalCost.toFixed(2)}`);
+    console.log('');
+  } catch (err) {
+    console.error(`Error fetching blocks: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // help
 // ---------------------------------------------------------------------------
@@ -413,11 +640,18 @@ function printHelp() {
   Manual mode:
     watch        Run watcher in foreground
 
+  Usage insights:
+    summary      Show current usage summary (--json for JSON)
+    blocks [N]   Show 5-hour billing blocks (last N days, default 3)
+
   Info:
     status       Show current configuration
     logs [N]     Tail watcher log (last N lines, default 50)
     key          Print current API key
 
+  Integration:
+    mcp          Start MCP server (for Claude Code/Desktop)
+
   https://getaimeter.com
 `);
 }

package/config-schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AIMeter Configuration",
+  "description": "Configuration file for AIMeter watcher (~/.aimeter/config.json)",
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "type": "string",
+      "description": "Your AIMeter API key (starts with aim_)",
+      "pattern": "^aim_[a-zA-Z0-9]+$"
+    },
+    "apiUrl": {
+      "type": "string",
+      "description": "API server URL (default: https://aimeter-api.fly.dev)",
+      "format": "uri",
+      "default": "https://aimeter-api.fly.dev"
+    },
+    "pollInterval": {
+      "type": "integer",
+      "description": "File polling interval in milliseconds (default: 5000)",
+      "minimum": 1000,
+      "maximum": 60000,
+      "default": 5000
+    },
+    "enableCursor": {
+      "type": "boolean",
+      "description": "Enable Cursor IDE tracking (requires sqlite3)",
+      "default": true
+    },
+    "enableCodex": {
+      "type": "boolean",
+      "description": "Enable OpenAI Codex tracking",
+      "default": true
+    },
+    "enableCopilot": {
+      "type": "boolean",
+      "description": "Enable GitHub Copilot tracking",
+      "default": true
+    },
+    "enableGemini": {
+      "type": "boolean",
+      "description": "Enable Google Gemini tracking",
+      "default": true
+    },
+    "logLevel": {
+      "type": "string",
+      "description": "Logging verbosity",
+      "enum": ["debug", "info", "warn", "error"],
+      "default": "info"
+    },
+    "maxLogSizeMb": {
+      "type": "number",
+      "description": "Maximum log file size in MB before rotation (default: 10)",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 10
+    }
+  },
+  "required": ["apiKey"],
+  "additionalProperties": false
+}

package/mcp.js

@@ -0,0 +1,772 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * AIMeter MCP Server
+ *
+ * Model Context Protocol server that exposes AI usage data to Claude Code/Desktop.
+ * Uses STDIO transport (JSON-RPC 2.0) with zero npm dependencies.
+ *
+ * Usage:
+ *   node mcp.js              — start the MCP server (stdin/stdout)
+ *   aimeter mcp              — same, via CLI
+ *   aimeter-mcp              — same, via bin alias
+ *
+ * Configuration for Claude Code (~/.claude/settings.json):
+ *   {
+ *     "mcpServers": {
+ *       "aimeter": {
+ *         "command": "aimeter-mcp"
+ *       }
+ *     }
+ *   }
+ */
+
+const https = require('https');
+const fs    = require('fs');
+const os    = require('os');
+const path  = require('path');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const API_HOST = 'aimeter-api.fly.dev';
+const CONFIG_FILE = path.join(os.homedir(), '.aimeter', 'config.json');
+const MCP_PROTOCOL_VERSION = '2024-11-05';
+
+const SERVER_INFO = {
+  name: 'aimeter',
+  version: '0.9.0',
+};
+
+// ─── Tool Definitions ────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'get_usage_summary',
+    description:
+      'Get your current AI coding costs across all tools (Claude, Cursor, Codex, Copilot, Gemini) for the active 5-hour billing window. Shows token counts, cost breakdown by model and source, and time until reset.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'get_daily_costs',
+    description:
+      'Get daily cost breakdown showing spend per day across all AI coding tools. Shows date, cost, and request count for each day.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: {
+          type: 'number',
+          description: 'Number of days to look back (default: 7, max: 90)',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_session_blocks',
+    description:
+      'Analyze your usage in 5-hour billing blocks. Shows token consumption and cost for each block to help identify high-usage periods.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        hours: {
+          type: 'number',
+          description: 'Number of hours to look back (default: 24, max: 120)',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_cost_forecast',
+    description:
+      'Get monthly spend projection based on your current usage patterns. Shows spent so far, daily average, and projected monthly total.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'get_optimizations',
+    description:
+      'Get personalized cost optimization recommendations based on your usage patterns. Analyzes model choices, caching efficiency, and usage timing. Requires Pro plan.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: {
+          type: 'number',
+          description: 'Number of days of data to analyze (default: 30)',
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+// ─── API Key ─────────────────────────────────────────────────────────────────
+
+function getApiKey() {
+  // Environment variable takes precedence
+  if (process.env.AIMETER_KEY) return process.env.AIMETER_KEY.trim();
+
+  // Read from config file
+  try {
+    const cfg = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    if (cfg.apiKey) return cfg.apiKey;
+  } catch {
+    // config file doesn't exist or is invalid
+  }
+
+  // Legacy: ~/.claude/aimeter-key
+  try {
+    const legacyPath = path.join(os.homedir(), '.claude', 'aimeter-key');
+    const key = fs.readFileSync(legacyPath, 'utf8').trim();
+    if (key) return key;
+  } catch {}
+
+  return null;
+}
+
+// ─── HTTP Client ─────────────────────────────────────────────────────────────
+
+function callApi(apiPath) {
+  return new Promise((resolve, reject) => {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+      reject(new Error('No AIMeter API key configured. Run: aimeter setup'));
+      return;
+    }
+
+    const options = {
+      hostname: API_HOST,
+      port: 443,
+      path: apiPath,
+      method: 'GET',
+      headers: {
+        'X-AIMeter-Key': apiKey,
+        'Accept': 'application/json',
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            resolve(JSON.parse(body));
+          } catch (e) {
+            reject(new Error(`Invalid JSON response from API: ${e.message}`));
+          }
+        } else if (res.statusCode === 401) {
+          reject(new Error('Invalid API key. Run: aimeter setup'));
+        } else if (res.statusCode === 403) {
+          reject(new Error('Pro plan required for this feature. Upgrade at https://getaimeter.com/dashboard/account'));
+        } else if (res.statusCode === 429) {
+          reject(new Error('Rate limit exceeded. Please wait a moment and try again.'));
+        } else {
+          let errorMsg = `API returned ${res.statusCode}`;
+          try {
+            const parsed = JSON.parse(body);
+            if (parsed.error) errorMsg = parsed.error;
+          } catch {}
+          reject(new Error(errorMsg));
+        }
+      });
+    });
+
+    req.on('error', (err) => reject(new Error(`Network error: ${err.message}`)));
+    req.setTimeout(15000, () => {
+      req.destroy();
+      reject(new Error('API request timed out (15s)'));
+    });
+    req.end();
+  });
+}
+
+// ─── Formatting Helpers ──────────────────────────────────────────────────────
+
+function formatCost(cost) {
+  if (cost == null || isNaN(cost)) return '$0.00';
+  return '$' + Number(cost).toFixed(2);
+}
+
+function formatTokens(count) {
+  if (count == null || isNaN(count)) return '0';
+  count = Number(count);
+  if (count >= 1_000_000) return (count / 1_000_000).toFixed(1) + 'M';
+  if (count >= 1_000) return (count / 1_000).toFixed(1) + 'k';
+  return count.toString();
+}
+
+function formatDuration(ms) {
+  if (ms == null || isNaN(ms) || ms <= 0) return '0m';
+  const totalMinutes = Math.floor(ms / 60000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  return `${minutes}m`;
+}
+
+function padRight(str, len) {
+  str = String(str);
+  while (str.length < len) str += ' ';
+  return str;
+}
+
+function padLeft(str, len) {
+  str = String(str);
+  while (str.length < len) str = ' ' + str;
+  return str;
+}
+
+// ─── Tool Handlers ───────────────────────────────────────────────────────────
+
+async function handleGetUsageSummary() {
+  const data = await callApi('/api/usage/current');
+
+  const totalCost = (data.byModel || []).reduce((sum, m) => sum + (m.estimatedCost || 0), 0);
+
+  // Calculate time until reset
+  let resetText = 'N/A';
+  if (data.nextReset) {
+    const resetTime = new Date(data.nextReset);
+    const now = new Date();
+    const diffMs = resetTime.getTime() - now.getTime();
+    if (diffMs > 0) {
+      resetText = formatDuration(diffMs);
+    } else {
+      resetText = 'Imminent';
+    }
+  }
+
+  let output = '';
+  output += 'Current Usage (5-hour window)\n';
+  output += '='.repeat(40) + '\n';
+  output += `Total Cost:      ${formatCost(totalCost)}\n`;
+  output += `Input Tokens:    ${formatTokens(data.totalInputTokens)}\n`;
+  output += `Output Tokens:   ${formatTokens(data.totalOutputTokens)}\n`;
+  output += `Thinking:        ${formatTokens(data.totalThinkingTokens)}\n`;
+  output += `Cache Read:      ${formatTokens(data.totalCacheReadTokens)}\n`;
+  output += `Requests:        ${data.windowRequests || 0}\n`;
+  output += `Reset in:        ${resetText}\n`;
+
+  // By Source
+  const bySource = data.bySource || [];
+  if (bySource.length > 0) {
+    output += '\nBy Source:\n';
+    output += '-'.repeat(40) + '\n';
+    for (const s of bySource) {
+      const srcName = padRight(s.source || 'unknown', 14);
+      const reqCount = padLeft(String(s.requests || 0), 4);
+      const srcTokens = formatTokens((s.inputTokens || 0) + (s.outputTokens || 0));
+      output += `  ${srcName} ${reqCount} requests  ${padLeft(srcTokens, 8)} tokens\n`;
+    }
+  }
+
+  // By Model
+  const byModel = data.byModel || [];
+  if (byModel.length > 0) {
+    output += '\nBy Model:\n';
+    output += '-'.repeat(40) + '\n';
+    for (const m of byModel) {
+      const modelName = padRight(m.model || 'unknown', 22);
+      const reqCount = padLeft(String(m.requests || 0), 4);
+      output += `  ${modelName} ${reqCount} req  ${padLeft(formatCost(m.estimatedCost), 8)}\n`;
+    }
+  }
+
+  // Previous window comparison
+  if (data.previous) {
+    const prevCost = data.previous.totalCost || 0;
+    const prevReqs = data.previous.totalRequests || 0;
+    output += '\nPrevious Window:\n';
+    output += '-'.repeat(40) + '\n';
+    output += `  Cost: ${formatCost(prevCost)}  |  Requests: ${prevReqs}\n`;
+    if (prevCost > 0 && totalCost > 0) {
+      const change = ((totalCost - prevCost) / prevCost * 100).toFixed(0);
+      const arrow = totalCost > prevCost ? 'UP' : 'DOWN';
+      output += `  Change: ${change > 0 ? '+' : ''}${change}% (${arrow})\n`;
+    }
+  }
+
+  // Weekly summary
+  if (data.weekly) {
+    output += '\nWeekly Rolling (7 days):\n';
+    output += '-'.repeat(40) + '\n';
+    output += `  Total Tokens: ${formatTokens(data.weekly.totalTokens)}  |  Requests: ${data.weekly.requests || 0}\n`;
+  }
+
+  return output;
+}
+
+async function handleGetDailyCosts(args) {
+  const days = Math.min(Math.max(parseInt(args.days) || 7, 1), 90);
+
+  const data = await callApi(`/api/usage/history?days=${days}`);
+
+  const dailyData = data.days || [];
+
+  if (dailyData.length === 0) {
+    return `No usage data found for the last ${days} days.`;
+  }
+
+  // We need cost data from the analytics endpoint for pro users,
+  // but history gives us token counts. Let's present what we have.
+  let output = `Daily Usage (last ${days} days)\n`;
+  output += '='.repeat(50) + '\n';
+  output += `${padRight('Date', 14)} ${padLeft('Input', 10)} ${padLeft('Output', 10)} ${padLeft('Thinking', 10)} ${padLeft('Requests', 10)}\n`;
+  output += '-'.repeat(54) + '\n';
+
+  let totalInput = 0;
+  let totalOutput = 0;
+  let totalThinking = 0;
+  let totalRequests = 0;
+
+  for (const day of dailyData) {
+    const dateStr = day.date ? new Date(day.date).toISOString().slice(0, 10) : 'unknown';
+    const input = day.inputTokens || 0;
+    const output2 = day.outputTokens || 0;
+    const thinking = day.thinkingTokens || 0;
+    const reqs = day.requests || 0;
+
+    totalInput += input;
+    totalOutput += output2;
+    totalThinking += thinking;
+    totalRequests += reqs;
+
+    output += `${padRight(dateStr, 14)} ${padLeft(formatTokens(input), 10)} ${padLeft(formatTokens(output2), 10)} ${padLeft(formatTokens(thinking), 10)} ${padLeft(String(reqs), 10)}\n`;
+  }
+
+  output += '-'.repeat(54) + '\n';
+  output += `${padRight('TOTAL', 14)} ${padLeft(formatTokens(totalInput), 10)} ${padLeft(formatTokens(totalOutput), 10)} ${padLeft(formatTokens(totalThinking), 10)} ${padLeft(String(totalRequests), 10)}\n`;
+
+  const avgReqs = Math.round(totalRequests / dailyData.length);
+  output += `\nAverage: ${avgReqs} requests/day\n`;
+
+  return output;
+}
+
+async function handleGetSessionBlocks(args) {
+  const hours = Math.min(Math.max(parseInt(args.hours) || 24, 1), 120);
+
+  // Fetch recent events to analyze blocks
+  const limit = 200;
+  const data = await callApi(`/api/usage/events?limit=${limit}&offset=0`);
+
+  const events = (data.events || []).filter((e) => {
+    if (!e.timestamp) return false;
+    const eventTime = new Date(e.timestamp);
+    const cutoff = new Date(Date.now() - hours * 3600000);
+    return eventTime >= cutoff;
+  });
+
+  if (events.length === 0) {
+    return `No usage events found in the last ${hours} hours.`;
+  }
+
+  // Group events into 5-hour blocks
+  const blockSize = 5 * 3600000; // 5 hours in ms
+  const now = Date.now();
+  const blocks = new Map();
+
+  for (const event of events) {
+    const eventTime = new Date(event.timestamp).getTime();
+    const blockIndex = Math.floor((now - eventTime) / blockSize);
+    const blockStart = now - (blockIndex + 1) * blockSize;
+    const blockEnd = now - blockIndex * blockSize;
+    const key = blockIndex;
+
+    if (!blocks.has(key)) {
+      blocks.set(key, {
+        start: new Date(blockStart),
+        end: new Date(blockEnd),
+        inputTokens: 0,
+        outputTokens: 0,
+        thinkingTokens: 0,
+        cost: 0,
+        requests: 0,
+        models: new Set(),
+      });
+    }
+
+    const block = blocks.get(key);
+    block.inputTokens += event.inputTokens || 0;
+    block.outputTokens += event.outputTokens || 0;
+    block.thinkingTokens += event.thinkingTokens || 0;
+    block.cost += event.estimatedCost || 0;
+    block.requests += 1;
+    if (event.model) block.models.add(event.model);
+  }
+
+  // Sort blocks by time (most recent first)
+  const sortedBlocks = Array.from(blocks.entries())
+    .sort((a, b) => a[0] - b[0])
+    .map((entry) => entry[1]);
+
+  let output = `5-Hour Billing Blocks (last ${hours}h)\n`;
+  output += '='.repeat(55) + '\n';
+
+  for (const block of sortedBlocks) {
+    const startStr = block.start.toISOString().slice(11, 16);
+    const endStr = block.end.toISOString().slice(11, 16);
+    const dateStr = block.start.toISOString().slice(0, 10);
+
+    output += `\n[${dateStr} ${startStr} - ${endStr} UTC]\n`;
+    output += '-'.repeat(40) + '\n';
+    output += `  Cost:      ${formatCost(block.cost)}\n`;
+    output += `  Requests:  ${block.requests}\n`;
+    output += `  Input:     ${formatTokens(block.inputTokens)}\n`;
+    output += `  Output:    ${formatTokens(block.outputTokens)}\n`;
+    output += `  Thinking:  ${formatTokens(block.thinkingTokens)}\n`;
+    output += `  Models:    ${Array.from(block.models).join(', ') || 'N/A'}\n`;
+  }
+
+  output += '\n' + '='.repeat(55) + '\n';
+  output += `Total: ${sortedBlocks.length} block(s), ${events.length} events\n`;
+
+  return output;
+}
+
+async function handleGetCostForecast() {
+  const data = await callApi('/api/analytics/forecast');
+
+  let output = 'Monthly Cost Forecast\n';
+  output += '='.repeat(40) + '\n';
+  output += `Spent so far:      ${formatCost(data.spentSoFar)}\n`;
+  output += `Daily average:     ${formatCost(data.dailyAverage)}\n`;
+  output += `Projected monthly: ${formatCost(data.projectedMonthly)}\n`;
+  output += '\n';
+  output += `Days elapsed:      ${data.daysElapsed}\n`;
+  output += `Days remaining:    ${data.daysRemaining}\n`;
+
+  // Add some context
+  const projected = Number(data.projectedMonthly) || 0;
+  if (projected > 0) {
+    output += '\n';
+    output += 'Projections at current pace:\n';
+    output += '-'.repeat(40) + '\n';
+    output += `  This week:   ~${formatCost((data.dailyAverage || 0) * 7)}\n`;
+    output += `  This month:  ~${formatCost(projected)}\n`;
+    output += `  This year:   ~${formatCost(projected * 12)}\n`;
+  }
+
+  return output;
+}
+
+async function handleGetOptimizations(args) {
+  const days = Math.min(Math.max(parseInt(args.days) || 30, 1), 365);
+
+  const data = await callApi(`/api/analytics/optimizations?days=${days}`);
+
+  let output = `Cost Optimization Recommendations (${days} days)\n`;
+  output += '='.repeat(50) + '\n';
+
+  // The optimization engine returns various recommendations
+  // Format them in a readable way
+  if (data.score != null) {
+    output += `\nEfficiency Score: ${data.score}/100\n`;
+  }
+
+  if (data.totalCost != null) {
+    output += `Total Cost Analyzed: ${formatCost(data.totalCost)}\n`;
+  }
+
+  if (data.potentialSavings != null) {
+    output += `Potential Savings:   ${formatCost(data.potentialSavings)}\n`;
+  }
+
+  const recommendations = data.recommendations || data.tips || [];
+  if (recommendations.length > 0) {
+    output += '\nRecommendations:\n';
+    output += '-'.repeat(50) + '\n';
+    for (let i = 0; i < recommendations.length; i++) {
+      const rec = recommendations[i];
+      if (typeof rec === 'string') {
+        output += `  ${i + 1}. ${rec}\n`;
+      } else {
+        const title = rec.title || rec.name || `Recommendation ${i + 1}`;
+        const desc = rec.description || rec.detail || rec.message || '';
+        const savings = rec.savings || rec.estimatedSavings;
+        output += `\n  ${i + 1}. ${title}\n`;
+        if (desc) output += `     ${desc}\n`;
+        if (savings != null) output += `     Estimated savings: ${formatCost(savings)}/month\n`;
+        if (rec.priority) output += `     Priority: ${rec.priority}\n`;
+      }
+    }
+  }
+
+  // Model breakdown if available
+  const models = data.modelBreakdown || data.byModel || [];
+  if (models.length > 0) {
+    output += '\nCost by Model:\n';
+    output += '-'.repeat(50) + '\n';
+    for (const m of models) {
+      const name = padRight(m.model || m.name || 'unknown', 24);
+      output += `  ${name} ${padLeft(formatCost(m.cost || m.totalCost), 10)}\n`;
+    }
+  }
+
+  if (recommendations.length === 0 && !data.score) {
+    // Raw data fallback - format whatever we got
+    output += '\n' + JSON.stringify(data, null, 2) + '\n';
+  }
+
+  return output;
+}
+
+// ─── MCP Protocol Handler ────────────────────────────────────────────────────
+
+async function handleMessage(message) {
+  const { id, method, params } = message;
+
+  // Notifications (no id) - acknowledge silently
+  if (id === undefined || id === null) {
+    if (method === 'notifications/initialized') {
+      // Client acknowledged initialization - nothing to respond
+      return null;
+    }
+    if (method === 'notifications/cancelled') {
+      return null;
+    }
+    // Unknown notification - ignore
+    return null;
+  }
+
+  switch (method) {
+    case 'initialize':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: {
+            tools: {},
+          },
+          serverInfo: SERVER_INFO,
+        },
+      };
+
+    case 'ping':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {},
+      };
+
+    case 'tools/list':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          tools: TOOLS,
+        },
+      };
+
+    case 'tools/call': {
+      const toolName = params && params.name;
+      const toolArgs = (params && params.arguments) || {};
+
+      try {
+        let resultText;
+
+        switch (toolName) {
+          case 'get_usage_summary':
+            resultText = await handleGetUsageSummary();
+            break;
+          case 'get_daily_costs':
+            resultText = await handleGetDailyCosts(toolArgs);
+            break;
+          case 'get_session_blocks':
+            resultText = await handleGetSessionBlocks(toolArgs);
+            break;
+          case 'get_cost_forecast':
+            resultText = await handleGetCostForecast();
+            break;
+          case 'get_optimizations':
+            resultText = await handleGetOptimizations(toolArgs);
+            break;
+          default:
+            return {
+              jsonrpc: '2.0',
+              id,
+              result: {
+                content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],
+                isError: true,
+              },
+            };
+        }
+
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [{ type: 'text', text: resultText }],
+          },
+        };
+      } catch (err) {
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [{ type: 'text', text: `Error: ${err.message}` }],
+            isError: true,
+          },
+        };
+      }
+    }
+
+    default:
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: {
+          code: -32601,
+          message: `Method not found: ${method}`,
+        },
+      };
+  }
+}
+
+// ─── STDIO Transport ─────────────────────────────────────────────────────────
+
+function startMcpServer() {
+  // Suppress any accidental console.log from dependencies
+  // MCP protocol uses stdout exclusively for JSON-RPC messages
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+
+  function sendResponse(response) {
+    if (!response) return;
+    const json = JSON.stringify(response);
+    originalStdoutWrite(json + '\n');
+  }
+
+  // Read from stdin line by line
+  let buffer = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+
+    // Process complete lines
+    let newlineIndex;
+    while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+
+      if (!line) continue;
+
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (err) {
+        // Try reading as Content-Length framed message
+        // Some MCP clients use HTTP-style framing: "Content-Length: N\r\n\r\n{...}"
+        // We'll handle this in the content-length path below
+        continue;
+      }
+
+      handleMessage(message)
+        .then((response) => sendResponse(response))
+        .catch((err) => {
+          // Internal error
+          if (message && message.id != null) {
+            sendResponse({
+              jsonrpc: '2.0',
+              id: message.id,
+              error: {
+                code: -32603,
+                message: `Internal error: ${err.message}`,
+              },
+            });
+          }
+        });
+    }
+
+    // Handle Content-Length framed messages (some clients use this format)
+    handleContentLengthFrames();
+  });
+
+  // Content-Length based frame parsing
+  let contentLengthBuffer = '';
+  let expectedLength = -1;
+
+  function handleContentLengthFrames() {
+    // Check if buffer contains Content-Length headers
+    if (expectedLength === -1) {
+      const headerEnd = buffer.indexOf('\r\n\r\n');
+      if (headerEnd === -1) return;
+
+      const header = buffer.slice(0, headerEnd);
+      const match = header.match(/Content-Length:\s*(\d+)/i);
+      if (!match) return;
+
+      expectedLength = parseInt(match[1], 10);
+      buffer = buffer.slice(headerEnd + 4);
+    }
+
+    if (expectedLength > 0 && buffer.length >= expectedLength) {
+      const body = buffer.slice(0, expectedLength);
+      buffer = buffer.slice(expectedLength);
+      expectedLength = -1;
+
+      let message;
+      try {
+        message = JSON.parse(body);
+      } catch {
+        return;
+      }
+
+      handleMessage(message)
+        .then((response) => sendResponse(response))
+        .catch((err) => {
+          if (message && message.id != null) {
+            sendResponse({
+              jsonrpc: '2.0',
+              id: message.id,
+              error: {
+                code: -32603,
+                message: `Internal error: ${err.message}`,
+              },
+            });
+          }
+        });
+
+      // Recurse to handle any remaining frames
+      handleContentLengthFrames();
+    }
+  }
+
+  process.stdin.on('end', () => {
+    process.exit(0);
+  });
+
+  process.stdin.on('error', () => {
+    process.exit(1);
+  });
+
+  // Handle process signals gracefully
+  process.on('SIGINT', () => process.exit(0));
+  process.on('SIGTERM', () => process.exit(0));
+
+  // Suppress unhandled rejections from crashing the server
+  process.on('unhandledRejection', () => {});
+  process.on('uncaughtException', () => {});
+
+  // Log to stderr (not stdout — stdout is reserved for MCP protocol)
+  process.stderr.write('[aimeter-mcp] Server started on stdio\n');
+}
+
+// ─── Entry Point ─────────────────────────────────────────────────────────────
+
+// If run directly (not required as module), start the server
+if (require.main === module) {
+  startMcpServer();
+}
+
+module.exports = { startMcpServer };

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "getaimeter",
-  "version": "0.8.1",
-  "description": "Track AI coding costs across Claude, Cursor, Codex, and Gemini. Optimization recommendations that cut costs by 30%.",
+  "version": "0.10.0",
+  "description": "Track AI coding costs across Claude, Cursor, Codex, Copilot, and Gemini. MCP server, billing blocks, optimization recommendations.",
   "bin": {
-    "aimeter": "cli.js"
+    "aimeter": "cli.js",
+    "aimeter-mcp": "mcp.js"
   },
   "main": "watcher.js",
+  "scripts": {
+    "test": "node --test test/parser.test.js",
+    "test:e2e": "node --test test/e2e.test.js",
+    "test:all": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18"
   },
@@ -25,10 +31,13 @@
     "optimization",
     "claude-code",
     "vscode",
+    "copilot",
+    "mcp",
     "multi-tool"
   ],
   "files": [
     "cli.js",
+    "mcp.js",
     "watcher.js",
     "reporter.js",
     "config.js",
@@ -40,6 +49,7 @@
     "tray-launcher.vbs",
     "icon.ico",
     "update-check.js",
+    "config-schema.json",
     "README.md"
   ],
   "repository": {

package/watcher.js

@@ -35,6 +35,9 @@ function logError(...args) {
 // Cache detected sources per file to avoid re-reading headers
 const _sourceCache = new Map();
 
+// Cache conversation metadata per file: { conversationId, projectPath }
+const _convMetaCache = new Map();
+
 // Track cumulative token counts per file for Codex CLI (which reports cumulative, not delta)
 const _codexCumulative = {};
 
@@ -140,6 +143,76 @@ function detectSource(filePath) {
   return source;
 }
 
+// ---------------------------------------------------------------------------
+// Conversation metadata extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract conversation ID and project path from a file.
+ * - conversationId: file basename without extension (unique per session)
+ * - projectPath: cwd from the JSONL header (Claude Code stores this in init/system messages)
+ *
+ * For subagent files, the conversation ID is inherited from the parent session.
+ */
+function getConversationMeta(filePath) {
+  if (_convMetaCache.has(filePath)) return _convMetaCache.get(filePath);
+
+  const normalized = filePath.replace(/\\/g, '/');
+
+  // Conversation ID = file basename without extension
+  let conversationId = path.basename(filePath, '.jsonl');
+
+  // For subagent files, use the parent session UUID as conversation ID
+  const subagentMatch = normalized.match(/\/([^/]+)\/subagents\//);
+  if (subagentMatch) {
+    conversationId = subagentMatch[1]; // parent session UUID
+  }
+
+  // Extract project path (cwd) from the first few lines of the file
+  let projectPath = null;
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(Math.min(8192, fs.fstatSync(fd).size));
+    fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    const header = buf.toString('utf8');
+
+    for (const line of header.split('\n').slice(0, 10)) {
+      if (!line.trim()) continue;
+      try {
+        const obj = JSON.parse(line.trim());
+        // Claude Code: type=system or init messages have cwd
+        if (obj.cwd) {
+          projectPath = obj.cwd;
+          break;
+        }
+        // Some formats nest it in message or data
+        if (obj.message?.cwd) {
+          projectPath = obj.message.cwd;
+          break;
+        }
+        // Codex: session_meta may have cwd
+        if (obj.type === 'session_meta' && obj.payload?.cwd) {
+          projectPath = obj.payload.cwd;
+          break;
+        }
+      } catch {}
+    }
+  } catch {}
+
+  // Shorten project path to just the last directory name for privacy/brevity
+  if (projectPath) {
+    projectPath = projectPath.replace(/\\/g, '/').replace(/\/$/, '');
+    // Keep last 2 path segments: "User/project" or just "project"
+    const parts = projectPath.split('/');
+    projectPath = parts.length > 1 ? parts.slice(-2).join('/') : parts[parts.length - 1];
+  }
+
+  const meta = { conversationId, projectPath };
+  _convMetaCache.set(filePath, meta);
+  return meta;
+}
+
 // ---------------------------------------------------------------------------
 // JSONL parsing — extract usage from new bytes in a transcript file
 // ---------------------------------------------------------------------------
@@ -166,6 +239,7 @@ function extractNewUsage(filePath) {
   if (lastOffset > 0 && lines.length > 0) lines.shift();
 
   const usageEvents = [];
+  const convMeta = getConversationMeta(filePath);
   let lineOffset = lastOffset;
   let pendingThinkingChars = 0; // Track thinking chars from streaming progress messages
 
@@ -252,6 +326,8 @@ function extractNewUsage(filePath) {
           thinkingTokens:   deltaReasoning,
           cacheReadTokens:  cachedTokens,
           cacheWriteTokens: 0,
+          conversationId:   convMeta.conversationId,
+          projectPath:      convMeta.projectPath,
         });
         continue;
       }
@@ -272,6 +348,8 @@ function extractNewUsage(filePath) {
           thinkingTokens:   obj.reasoning_tokens || 0,
           cacheReadTokens:  0,
           cacheWriteTokens: 0,
+          conversationId:   convMeta.conversationId,
+          projectPath:      convMeta.projectPath,
         });
         continue;
       }
@@ -303,6 +381,8 @@ function extractNewUsage(filePath) {
             thinkingTokens:   0,
             cacheReadTokens:  u.cacheReadTokens || 0,
             cacheWriteTokens: u.cacheWriteTokens || 0,
+            conversationId:   convMeta.conversationId,
+            projectPath:      convMeta.projectPath,
           });
         }
         continue;
@@ -326,6 +406,8 @@ function extractNewUsage(filePath) {
           thinkingTokens:   um.thoughtsTokenCount || 0,
           cacheReadTokens:  um.cachedContentTokenCount || 0,
           cacheWriteTokens: 0,
+          conversationId:   convMeta.conversationId,
+          projectPath:      convMeta.projectPath,
         });
         continue;
       }
@@ -384,6 +466,8 @@ function extractNewUsage(filePath) {
       thinkingTokens:   estimatedThinkingTokens,
       cacheReadTokens:  u.cache_read_input_tokens    || 0,
       cacheWriteTokens: u.cache_creation_input_tokens || 0,
+      conversationId:   convMeta.conversationId,
+      projectPath:      convMeta.projectPath,
     });
   }
 
@@ -575,6 +659,8 @@ function extractCursorUsage(dbPath) {
           thinkingTokens:   0,
           cacheReadTokens:  0,
           cacheWriteTokens: 0,
+          conversationId:   conv.composerId,
+          projectPath:      null,
         });
       } catch {}
     }