@mcpspend/proxy 0.1.5 → 0.2.2

package/README.md

@@ -1,52 +1,70 @@
 # @mcpspend/proxy
 
-Transparent observability proxy for MCP (Model Context Protocol) servers.
+One-command observability for [MCP](https://modelcontextprotocol.io) (Model Context Protocol) servers.
 
-Wraps any stdio MCP server, intercepts JSON-RPC `tools/call` traffic, and reports each call (tool, latency, success, approximate token sizes) to [MCPSpend](https://mcpspend.com) for cost attribution and analytics.
+Detects every MCP client installed on your machine — Claude Desktop, Cursor, Windsurf, VS Code, Claude Code — and transparently wraps each configured server so MCPSpend can attribute tool calls, latency and cost. The proxy never blocks the MCP wire: if our API is unreachable, your agent keeps working.
 
-Fire-and-forget: the proxy never blocks the MCP wire — if the MCPSpend API is unreachable, your agent keeps working.
+## Zero-friction setup — no install needed
 
-## Install
+```sh
+npx @mcpspend/proxy init --key mcps_live_xxx
+```
+
+That single command:
+
+1. Saves your API key to `~/.mcpspend/config.json` (mode `0600`).
+2. Discovers every supported MCP client config on your machine.
+3. Rewrites each `mcpServers` entry to be wrapped by `npx -y @mcpspend/proxy wrap --` (so the moment you restart your MCP client, it auto-fetches the proxy if missing).
+4. Leaves a `.mcpspend.bak` backup next to every file it touches.
+
+> Prefer a global binary? `npm install -g @mcpspend/proxy` then use `mcpspend init` — everything below works the same way.
+
+Restart your clients (Claude Desktop, Cursor, Windsurf, etc.) and head to [mcpspend.com](https://mcpspend.com) — calls start showing up within a minute.
+
+Get an API key at [mcpspend.com/dashboard/keys](https://mcpspend.com/dashboard/keys).
+
+## Verify
 
 ```sh
-npm install -g @mcpspend/proxy
+npx @mcpspend/proxy doctor
 ```
 
-## Quick start
+Reports API key status, endpoint reachability, and for every detected client: how many MCP servers are configured and how many are wrapped.
 
-1. Sign in at [mcpspend.com](https://mcpspend.com) and create an API key.
-2. Configure once:
-   ```sh
-   mcpspend config set apiKey mcps_live_xxx
-   ```
-3. Wrap any MCP server you already use:
-   ```sh
-   mcpspend wrap -- npx @modelcontextprotocol/server-filesystem /path
-   ```
+## Undo
 
-## Usage with Claude Desktop / Claude Code
+```sh
+npx @mcpspend/proxy init --unwrap
+```
 
-Wherever you have an MCP server configured, prepend `mcpspend wrap --` to the command:
+Restores every wrapped entry to its original `command` + `args`. The `.mcpspend.bak` files are left in place for paranoia.
 
-**Before:**
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["@modelcontextprotocol/server-filesystem", "/Users/me"]
-    }
-  }
-}
+## Supported clients
+
+| Client | Config path (detected automatically) |
+|---|---|
+| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` · `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (user) | `%APPDATA%\Code\User\mcp.json` · `~/.config/Code/User/mcp.json` |
+| Claude Code | `~/.claude.json` |
+
+## Manual single-server wrap
+
+If you want to wrap one specific invocation without touching client configs:
+
+```sh
+npx @mcpspend/proxy wrap --key mcps_live_xxx -- npx @modelcontextprotocol/server-filesystem /data
 ```
 
-**After:**
+Or paste this into a client config yourself:
+
 ```json
 {
   "mcpServers": {
     "filesystem": {
-      "command": "mcpspend",
-      "args": ["wrap", "--key", "mcps_live_xxx", "--", "npx", "@modelcontextprotocol/server-filesystem", "/Users/me"]
+      "command": "npx",
+      "args": ["-y", "@mcpspend/proxy", "wrap", "--", "npx", "@modelcontextprotocol/server-filesystem", "/Users/me"]
     }
   }
 }
@@ -64,9 +82,12 @@ CLI flags, environment variables, and `~/.mcpspend/config.json` are merged in th
 | Agent name | `--agent` | `MCPSPEND_AGENT_NAME` | `agentName` |
 | Disable tracking | `--disable` | `MCPSPEND_DISABLED=1` | `disabled: true` |
 
+The API key is **never** written into client config files (which often land in dotfile repos). It lives only in `~/.mcpspend/config.json` (mode `0600`) or `MCPSPEND_API_KEY`.
+
 ## Privacy
 
 The proxy reports:
+
 - Tool name (e.g. `read_file`)
 - Server name (e.g. `filesystem`)
 - Latency, success, error codes

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -3,37 +3,62 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const config_js_1 = require("./config.js");
 const proxy_js_1 = require("./proxy.js");
-const VERSION = '0.1.0';
+const init_js_1 = require("./init.js");
+const VERSION = '0.2.2';
 const HELP = `mcpspend — observability proxy for MCP servers (v${VERSION})
 
 USAGE
-  mcpspend wrap [options] -- <command> [args...]
+  mcpspend init [options]               Auto-detect MCP clients and wrap their servers
+  mcpspend doctor                       Diagnose setup (clients, API key, endpoint)
+  mcpspend wrap [options] -- <cmd>...   Manually wrap a single MCP server invocation
   mcpspend config set <key> <value>
   mcpspend config show
-  mcpspend --version
-  mcpspend --help
+  mcpspend --version | --help
+
+INIT OPTIONS
+  --key <value>            Save API key to ~/.mcpspend/config.json before patching
+  --project <id>           Attribute calls to this project (baked into wrapped args)
+  --endpoint <url>         Override API endpoint (default: https://api.mcpspend.com)
+  --agent <name>           Agent name reported in dashboards
+  --client <id>            Only patch a specific client (repeatable). IDs:
+                           claude-desktop, cursor, windsurf, vscode, claude-code
+  --dry-run                Show what would change without writing
+  --unwrap                 Restore original (non-wrapped) MCP server configs
 
 WRAP OPTIONS
   --key <value>            API key (overrides config + MCPSPEND_API_KEY)
-  --endpoint <url>         API endpoint (default: https://api.mcpspend.com)
+  --endpoint <url>         API endpoint
   --project <id>           Attribute calls to this project
-  --agent <name>           Agent name reported in dashboards
+  --agent <name>           Agent name
   --model <name>           Model name for cost attribution (default: mcp-stdio)
   --disable                Run in passthrough mode (no tracking)
 
 EXAMPLES
-  # Wrap a stdio MCP server, attribute to a specific project
-  mcpspend wrap --key mcps_live_xxx --project prj_abc -- npx @modelcontextprotocol/server-filesystem /data
+  # First-time setup: paste your API key, patch every installed MCP client
+  mcpspend init --key mcps_live_xxx
+
+  # See what init would change without writing
+  mcpspend init --dry-run
+
+  # Restore original configs (removes mcpspend wrapping)
+  mcpspend init --unwrap
+
+  # Only patch Cursor and Windsurf
+  mcpspend init --client cursor --client windsurf
 
-  # Configure once, then run many wrapped servers without flags
-  mcpspend config set apiKey mcps_live_xxx
-  mcpspend wrap -- npx @modelcontextprotocol/server-github
+  # Manual single-server wrap (no client config touched)
+  mcpspend wrap --key mcps_live_xxx -- npx @modelcontextprotocol/server-filesystem /data
 
 Environment variables: MCPSPEND_API_KEY, MCPSPEND_ENDPOINT, MCPSPEND_PROJECT_ID, MCPSPEND_AGENT_NAME, MCPSPEND_DISABLED=1
 Config file: ~/.mcpspend/config.json
 `;
 function parseArgs(argv) {
-    const result = { command: 'help', wrapOpts: {}, childArgs: [] };
+    const result = {
+        command: 'help',
+        wrapOpts: {},
+        initOpts: { clients: [], dryRun: false, unwrap: false },
+        childArgs: [],
+    };
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
         result.command = 'help';
         return result;
@@ -43,6 +68,52 @@ function parseArgs(argv) {
         return result;
     }
     const cmd = argv[0];
+    if (cmd === 'init') {
+        result.command = 'init';
+        let i = 1;
+        while (i < argv.length) {
+            const a = argv[i];
+            const next = argv[i + 1];
+            switch (a) {
+                case '--key':
+                    result.initOpts.apiKey = next;
+                    i += 2;
+                    break;
+                case '--project':
+                    result.initOpts.projectId = next;
+                    i += 2;
+                    break;
+                case '--endpoint':
+                    result.initOpts.endpoint = next;
+                    i += 2;
+                    break;
+                case '--agent':
+                    result.initOpts.agentName = next;
+                    i += 2;
+                    break;
+                case '--client':
+                    result.initOpts.clients.push(next);
+                    i += 2;
+                    break;
+                case '--dry-run':
+                    result.initOpts.dryRun = true;
+                    i += 1;
+                    break;
+                case '--unwrap':
+                    result.initOpts.unwrap = true;
+                    i += 1;
+                    break;
+                default:
+                    process.stderr.write(`mcpspend: unknown option ${a}\n`);
+                    process.exit(2);
+            }
+        }
+        return result;
+    }
+    if (cmd === 'doctor') {
+        result.command = 'doctor';
+        return result;
+    }
     if (cmd === 'wrap') {
         result.command = 'wrap';
         let i = 1;
@@ -124,6 +195,28 @@ async function main() {
         process.stdout.write(`${VERSION}\n`);
         return;
     }
+    if (parsed.command === 'init') {
+        const report = (0, init_js_1.runInit)({
+            apiKey: parsed.initOpts.apiKey,
+            projectId: parsed.initOpts.projectId,
+            endpoint: parsed.initOpts.endpoint,
+            agentName: parsed.initOpts.agentName,
+            clientFilter: parsed.initOpts.clients.length ? parsed.initOpts.clients : undefined,
+            dryRun: parsed.initOpts.dryRun,
+            unwrap: parsed.initOpts.unwrap,
+        });
+        process.stdout.write((0, init_js_1.formatReport)(report, parsed.initOpts.unwrap) + '\n');
+        if (report.clients.some((c) => c.status === 'error'))
+            process.exit(1);
+        return;
+    }
+    if (parsed.command === 'doctor') {
+        const report = await (0, init_js_1.runDoctor)(VERSION);
+        process.stdout.write((0, init_js_1.formatDoctor)(report) + '\n');
+        if (!report.apiKeyConfigured || !report.endpointReachable)
+            process.exit(1);
+        return;
+    }
     if (parsed.command === 'config') {
         if (parsed.configAction === 'show') {
             const cfg = (0, config_js_1.loadConfig)();

package/dist/clients.d.ts

@@ -0,0 +1,62 @@
+export interface McpServerEntry {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    [key: string]: unknown;
+}
+export interface ClientConfig {
+    mcpServers?: Record<string, McpServerEntry>;
+    [key: string]: unknown;
+}
+export interface ClientDefinition {
+    id: 'claude-desktop' | 'cursor' | 'windsurf' | 'vscode' | 'vscode-workspace' | 'claude-code';
+    name: string;
+    configPaths: () => string[];
+    serversKey?: string;
+}
+export declare const CLIENTS: ClientDefinition[];
+export interface DiscoveredClient {
+    client: ClientDefinition;
+    path: string;
+}
+export declare function discoverClients(): DiscoveredClient[];
+export declare function readClientConfig(path: string): ClientConfig;
+export declare function writeClientConfig(path: string, config: ClientConfig, backupSuffix?: string): string;
+export interface WrapResult {
+    serverName: string;
+    status: 'wrapped' | 'already-wrapped' | 'skipped';
+    reason?: string;
+}
+export declare function isAlreadyWrapped(entry: McpServerEntry): boolean;
+export interface WrapOptions {
+    apiKey?: string;
+    projectId?: string;
+    endpoint?: string;
+    agentName?: string;
+    /**
+     * Wrap style:
+     *  - 'npx' (default): emits `npx -y @mcpspend/proxy wrap -- <orig>`. Works without a global install.
+     *  - 'bin': emits `mcpspend wrap -- <orig>`. Requires `npm i -g @mcpspend/proxy`.
+     */
+    style?: 'npx' | 'bin';
+}
+/**
+ * Wrap a single MCP server entry. Returns a NEW entry; does not mutate the original.
+ *
+ * - Keeps `env` untouched.
+ * - API key is NOT baked into args (would leak into git-tracked dotfiles). The proxy
+ *   reads it from ~/.mcpspend/config.json (mode 0600) or MCPSPEND_API_KEY env.
+ */
+export declare function wrapEntry(entry: McpServerEntry, opts?: WrapOptions): McpServerEntry;
+export declare function unwrapEntry(entry: McpServerEntry): McpServerEntry | null;
+/**
+ * Apply wrapping to all MCP servers in a config. Returns the modified config + per-server results.
+ */
+export declare function wrapAllServers(config: ClientConfig, serversKey: string, opts?: WrapOptions): {
+    config: ClientConfig;
+    results: WrapResult[];
+};
+export declare function unwrapAllServers(config: ClientConfig, serversKey: string): {
+    config: ClientConfig;
+    results: WrapResult[];
+};

package/dist/clients.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENTS = void 0;
+exports.discoverClients = discoverClients;
+exports.readClientConfig = readClientConfig;
+exports.writeClientConfig = writeClientConfig;
+exports.isAlreadyWrapped = isAlreadyWrapped;
+exports.wrapEntry = wrapEntry;
+exports.unwrapEntry = unwrapEntry;
+exports.wrapAllServers = wrapAllServers;
+exports.unwrapAllServers = unwrapAllServers;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const home = (0, node_os_1.homedir)();
+const isWin = (0, node_os_1.platform)() === 'win32';
+const isMac = (0, node_os_1.platform)() === 'darwin';
+function appData() {
+    if (isWin)
+        return process.env.APPDATA || (0, node_path_1.join)(home, 'AppData', 'Roaming');
+    if (isMac)
+        return (0, node_path_1.join)(home, 'Library', 'Application Support');
+    return process.env.XDG_CONFIG_HOME || (0, node_path_1.join)(home, '.config');
+}
+exports.CLIENTS = [
+    {
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        configPaths: () => [(0, node_path_1.join)(appData(), 'Claude', 'claude_desktop_config.json')],
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        configPaths: () => [(0, node_path_1.join)(home, '.cursor', 'mcp.json')],
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        configPaths: () => [
+            (0, node_path_1.join)(home, '.codeium', 'windsurf', 'mcp_config.json'),
+            (0, node_path_1.join)(home, '.codeium', 'windsurf-next', 'mcp_config.json'),
+        ],
+    },
+    {
+        id: 'vscode',
+        name: 'VS Code (user)',
+        configPaths: () => {
+            const candidates = [];
+            if (isWin) {
+                candidates.push((0, node_path_1.join)(appData(), 'Code', 'User', 'mcp.json'));
+            }
+            else if (isMac) {
+                candidates.push((0, node_path_1.join)(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json'));
+            }
+            else {
+                candidates.push((0, node_path_1.join)(home, '.config', 'Code', 'User', 'mcp.json'));
+            }
+            return candidates;
+        },
+        serversKey: 'servers',
+    },
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        configPaths: () => [(0, node_path_1.join)(home, '.claude.json')],
+    },
+];
+function discoverClients() {
+    const found = [];
+    for (const c of exports.CLIENTS) {
+        for (const p of c.configPaths()) {
+            if ((0, node_fs_1.existsSync)(p)) {
+                found.push({ client: c, path: p });
+                break;
+            }
+        }
+    }
+    return found;
+}
+function readClientConfig(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return {};
+    try {
+        const raw = (0, node_fs_1.readFileSync)(path, 'utf-8');
+        if (!raw.trim())
+            return {};
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${path}: ${err.message}`);
+    }
+}
+function writeClientConfig(path, config, backupSuffix = '.mcpspend.bak') {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    let backupPath;
+    if ((0, node_fs_1.existsSync)(path)) {
+        backupPath = path + backupSuffix;
+        if (!(0, node_fs_1.existsSync)(backupPath)) {
+            (0, node_fs_1.copyFileSync)(path, backupPath);
+        }
+    }
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(config, null, 2) + '\n');
+    return backupPath ?? '';
+}
+// We support two wrap shapes:
+//  - npx-first  (default, recommended): command='npx', args=['-y','@mcpspend/proxy','wrap',...]
+//     No global install required — works the moment Node is on PATH.
+//  - bin-direct (legacy / for users who installed -g @mcpspend/proxy):
+//     command='mcpspend', args=['wrap',...]
+// `isAlreadyWrapped` accepts BOTH shapes so we don't re-wrap when migrating from
+// the old layout, and so users who manually pinned the global binary aren't disturbed.
+const MCPSPEND_BIN_NAMES = new Set(['mcpspend', 'mcpspend.cmd', 'mcpspend.exe']);
+const NPX_BIN_NAMES = new Set(['npx', 'npx.cmd', 'npx.exe']);
+const PROXY_PKG = '@mcpspend/proxy';
+// True if `pkgArg` is some form of @mcpspend/proxy: bare, @version, or @tag.
+//   '@mcpspend/proxy', '@mcpspend/proxy@0.2.1', '@mcpspend/proxy@latest' → true
+function isProxyPackageArg(pkgArg) {
+    if (!pkgArg)
+        return false;
+    if (pkgArg === PROXY_PKG)
+        return true;
+    return pkgArg.startsWith(PROXY_PKG + '@');
+}
+function isAlreadyWrapped(entry) {
+    const cmd = (entry.command || '').toLowerCase();
+    const base = cmd.split(/[\\/]/).pop() || cmd;
+    const args = entry.args || [];
+    // Shape A: `mcpspend wrap ...`
+    if (MCPSPEND_BIN_NAMES.has(base) && args[0] === 'wrap')
+        return true;
+    // Shape B: `npx [-y] @mcpspend/proxy[@version] wrap ...`
+    if (NPX_BIN_NAMES.has(base)) {
+        const skipFlag = args[0] === '-y' || args[0] === '--yes' ? 1 : 0;
+        if (isProxyPackageArg(args[skipFlag]) && args[skipFlag + 1] === 'wrap')
+            return true;
+    }
+    return false;
+}
+/**
+ * Find the position of the original command/args after the wrap prefix. Returns
+ * the index of the `--` separator, or -1 if the entry isn't wrapped.
+ */
+function findOriginalCommandStart(entry) {
+    if (!isAlreadyWrapped(entry))
+        return -1;
+    const args = entry.args || [];
+    const sepIdx = args.indexOf('--');
+    return sepIdx === -1 ? -1 : sepIdx;
+}
+/**
+ * Wrap a single MCP server entry. Returns a NEW entry; does not mutate the original.
+ *
+ * - Keeps `env` untouched.
+ * - API key is NOT baked into args (would leak into git-tracked dotfiles). The proxy
+ *   reads it from ~/.mcpspend/config.json (mode 0600) or MCPSPEND_API_KEY env.
+ */
+function wrapEntry(entry, opts = {}) {
+    const style = opts.style || 'npx';
+    const wrapArgs = ['wrap'];
+    if (opts.endpoint)
+        wrapArgs.push('--endpoint', opts.endpoint);
+    if (opts.projectId)
+        wrapArgs.push('--project', opts.projectId);
+    if (opts.agentName)
+        wrapArgs.push('--agent', opts.agentName);
+    wrapArgs.push('--', entry.command, ...(entry.args || []));
+    if (style === 'bin') {
+        return { ...entry, command: 'mcpspend', args: wrapArgs };
+    }
+    // npx style — prefix wrapArgs with `-y @mcpspend/proxy`.
+    return { ...entry, command: 'npx', args: ['-y', PROXY_PKG, ...wrapArgs] };
+}
+function unwrapEntry(entry) {
+    const sepIdx = findOriginalCommandStart(entry);
+    if (sepIdx === -1)
+        return null;
+    const args = entry.args || [];
+    if (sepIdx + 1 >= args.length)
+        return null;
+    const restored = {
+        ...entry,
+        command: args[sepIdx + 1],
+        args: args.slice(sepIdx + 2),
+    };
+    return restored;
+}
+/**
+ * Apply wrapping to all MCP servers in a config. Returns the modified config + per-server results.
+ */
+function wrapAllServers(config, serversKey, opts = {}) {
+    const results = [];
+    const servers = config[serversKey] || {};
+    const next = {};
+    for (const [name, entry] of Object.entries(servers)) {
+        if (!entry || typeof entry !== 'object' || !('command' in entry)) {
+            next[name] = entry;
+            results.push({ serverName: name, status: 'skipped', reason: 'no command field' });
+            continue;
+        }
+        if (isAlreadyWrapped(entry)) {
+            next[name] = entry;
+            results.push({ serverName: name, status: 'already-wrapped' });
+            continue;
+        }
+        next[name] = wrapEntry(entry, opts);
+        results.push({ serverName: name, status: 'wrapped' });
+    }
+    return { config: { ...config, [serversKey]: next }, results };
+}
+function unwrapAllServers(config, serversKey) {
+    const results = [];
+    const servers = config[serversKey] || {};
+    const next = {};
+    for (const [name, entry] of Object.entries(servers)) {
+        const restored = unwrapEntry(entry);
+        if (restored) {
+            next[name] = restored;
+            results.push({ serverName: name, status: 'wrapped', reason: 'restored to original' });
+        }
+        else {
+            next[name] = entry;
+            results.push({ serverName: name, status: 'skipped', reason: 'not wrapped by mcpspend' });
+        }
+    }
+    return { config: { ...config, [serversKey]: next }, results };
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface Config {
+    apiKey?: string;
+    endpoint: string;
+    projectId?: string;
+    agentName?: string;
+    disabled?: boolean;
+}
+export declare function loadConfig(cliOverrides?: Partial<Config>): Config;
+export declare function saveConfig(updates: Partial<Config>): string;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { loadConfig, saveConfig } from './config.js';
+export { runProxy } from './proxy.js';
+export type { Config } from './config.js';
+export type { ToolCallEvent } from './ingest.js';
+export { CLIENTS, discoverClients, readClientConfig, writeClientConfig, wrapAllServers, unwrapAllServers, wrapEntry, unwrapEntry, isAlreadyWrapped, } from './clients.js';
+export type { ClientDefinition, ClientConfig, DiscoveredClient, McpServerEntry, WrapResult, WrapOptions, } from './clients.js';
+export { runInit, runDoctor, formatReport, formatDoctor } from './init.js';
+export type { InitOptions, InitReport, ClientReport, DoctorReport } from './init.js';

package/dist/index.js

@@ -1,8 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runProxy = exports.saveConfig = exports.loadConfig = void 0;
+exports.formatDoctor = exports.formatReport = exports.runDoctor = exports.runInit = exports.isAlreadyWrapped = exports.unwrapEntry = exports.wrapEntry = exports.unwrapAllServers = exports.wrapAllServers = exports.writeClientConfig = exports.readClientConfig = exports.discoverClients = exports.CLIENTS = exports.runProxy = exports.saveConfig = exports.loadConfig = void 0;
 var config_js_1 = require("./config.js");
 Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_js_1.loadConfig; } });
 Object.defineProperty(exports, "saveConfig", { enumerable: true, get: function () { return config_js_1.saveConfig; } });
 var proxy_js_1 = require("./proxy.js");
 Object.defineProperty(exports, "runProxy", { enumerable: true, get: function () { return proxy_js_1.runProxy; } });
+// Programmatic API for embedders (VS Code extension, etc.)
+var clients_js_1 = require("./clients.js");
+Object.defineProperty(exports, "CLIENTS", { enumerable: true, get: function () { return clients_js_1.CLIENTS; } });
+Object.defineProperty(exports, "discoverClients", { enumerable: true, get: function () { return clients_js_1.discoverClients; } });
+Object.defineProperty(exports, "readClientConfig", { enumerable: true, get: function () { return clients_js_1.readClientConfig; } });
+Object.defineProperty(exports, "writeClientConfig", { enumerable: true, get: function () { return clients_js_1.writeClientConfig; } });
+Object.defineProperty(exports, "wrapAllServers", { enumerable: true, get: function () { return clients_js_1.wrapAllServers; } });
+Object.defineProperty(exports, "unwrapAllServers", { enumerable: true, get: function () { return clients_js_1.unwrapAllServers; } });
+Object.defineProperty(exports, "wrapEntry", { enumerable: true, get: function () { return clients_js_1.wrapEntry; } });
+Object.defineProperty(exports, "unwrapEntry", { enumerable: true, get: function () { return clients_js_1.unwrapEntry; } });
+Object.defineProperty(exports, "isAlreadyWrapped", { enumerable: true, get: function () { return clients_js_1.isAlreadyWrapped; } });
+var init_js_1 = require("./init.js");
+Object.defineProperty(exports, "runInit", { enumerable: true, get: function () { return init_js_1.runInit; } });
+Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function () { return init_js_1.runDoctor; } });
+Object.defineProperty(exports, "formatReport", { enumerable: true, get: function () { return init_js_1.formatReport; } });
+Object.defineProperty(exports, "formatDoctor", { enumerable: true, get: function () { return init_js_1.formatDoctor; } });

package/dist/ingest.d.ts

@@ -0,0 +1,26 @@
+import type { Config } from './config.js';
+export interface ToolCallEvent {
+    serverName: string;
+    toolName: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    success: boolean;
+    errorCode?: string;
+    calledAt: string;
+    projectId?: string;
+    sessionId?: string;
+}
+export declare class Ingest {
+    private cfg;
+    private queue;
+    private timer;
+    private inflight;
+    private dropped;
+    constructor(cfg: Config);
+    enqueue(event: ToolCallEvent): void;
+    private scheduleFlush;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/init.d.ts

@@ -0,0 +1,45 @@
+import { ClientDefinition, WrapResult } from './clients.js';
+export interface InitOptions {
+    apiKey?: string;
+    projectId?: string;
+    endpoint?: string;
+    agentName?: string;
+    clientFilter?: string[];
+    dryRun?: boolean;
+    unwrap?: boolean;
+}
+export interface ClientReport {
+    client: ClientDefinition['id'];
+    name: string;
+    path: string;
+    status: 'patched' | 'no-changes' | 'error' | 'dry-run';
+    backupPath?: string;
+    servers: WrapResult[];
+    error?: string;
+}
+export interface InitReport {
+    apiKeyConfigured: boolean;
+    apiKeySource: 'flag' | 'env' | 'config' | 'none';
+    clientsFound: number;
+    clientsPatched: number;
+    clients: ClientReport[];
+}
+export declare function runInit(opts?: InitOptions): InitReport;
+export declare function formatReport(report: InitReport, unwrap?: boolean): string;
+export interface DoctorReport {
+    cliVersion: string;
+    apiKeyConfigured: boolean;
+    apiKeySource: 'env' | 'config' | 'none';
+    endpointReachable?: boolean;
+    endpointError?: string;
+    clients: Array<{
+        client: ClientDefinition['id'];
+        name: string;
+        path?: string;
+        detected: boolean;
+        serversCount: number;
+        wrappedCount: number;
+    }>;
+}
+export declare function runDoctor(cliVersion: string): Promise<DoctorReport>;
+export declare function formatDoctor(report: DoctorReport): string;

package/dist/init.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInit = runInit;
+exports.formatReport = formatReport;
+exports.runDoctor = runDoctor;
+exports.formatDoctor = formatDoctor;
+const clients_js_1 = require("./clients.js");
+const config_js_1 = require("./config.js");
+function runInit(opts = {}) {
+    if (opts.apiKey) {
+        (0, config_js_1.saveConfig)({ apiKey: opts.apiKey });
+    }
+    if (opts.endpoint) {
+        (0, config_js_1.saveConfig)({ endpoint: opts.endpoint });
+    }
+    const cfg = (0, config_js_1.loadConfig)();
+    const apiKeySource = opts.apiKey
+        ? 'flag'
+        : process.env.MCPSPEND_API_KEY
+            ? 'env'
+            : cfg.apiKey
+                ? 'config'
+                : 'none';
+    let discovered = (0, clients_js_1.discoverClients)();
+    if (opts.clientFilter && opts.clientFilter.length) {
+        const set = new Set(opts.clientFilter);
+        discovered = discovered.filter((d) => set.has(d.client.id));
+    }
+    const clientReports = [];
+    for (const { client, path } of discovered) {
+        const serversKey = client.serversKey || 'mcpServers';
+        try {
+            const current = (0, clients_js_1.readClientConfig)(path);
+            const { config: next, results } = opts.unwrap
+                ? (0, clients_js_1.unwrapAllServers)(current, serversKey)
+                : (0, clients_js_1.wrapAllServers)(current, serversKey, {
+                    projectId: opts.projectId,
+                    endpoint: opts.endpoint,
+                    agentName: opts.agentName,
+                });
+            const changed = JSON.stringify(current) !== JSON.stringify(next);
+            if (opts.dryRun) {
+                clientReports.push({
+                    client: client.id,
+                    name: client.name,
+                    path,
+                    status: 'dry-run',
+                    servers: results,
+                });
+                continue;
+            }
+            if (!changed) {
+                clientReports.push({
+                    client: client.id,
+                    name: client.name,
+                    path,
+                    status: 'no-changes',
+                    servers: results,
+                });
+                continue;
+            }
+            const backupPath = (0, clients_js_1.writeClientConfig)(path, next);
+            clientReports.push({
+                client: client.id,
+                name: client.name,
+                path,
+                status: 'patched',
+                backupPath: backupPath || undefined,
+                servers: results,
+            });
+        }
+        catch (err) {
+            clientReports.push({
+                client: client.id,
+                name: client.name,
+                path,
+                status: 'error',
+                servers: [],
+                error: err.message,
+            });
+        }
+    }
+    return {
+        apiKeyConfigured: !!cfg.apiKey || apiKeySource === 'env',
+        apiKeySource,
+        clientsFound: discovered.length,
+        clientsPatched: clientReports.filter((r) => r.status === 'patched').length,
+        clients: clientReports,
+    };
+}
+function formatReport(report, unwrap = false) {
+    const lines = [];
+    const action = unwrap ? 'Unwrap' : 'Wrap';
+    if (report.clientsFound === 0) {
+        lines.push('No supported MCP clients found on this machine.');
+        lines.push('');
+        lines.push('Looked for:');
+        for (const c of clients_js_1.CLIENTS) {
+            lines.push(`  • ${c.name} — ${c.configPaths().join(', ')}`);
+        }
+        return lines.join('\n');
+    }
+    lines.push(`Found ${report.clientsFound} MCP client(s):`);
+    for (const r of report.clients) {
+        const tag = r.status === 'patched' ? '✓ patched'
+            : r.status === 'no-changes' ? '· no changes'
+                : r.status === 'dry-run' ? '∼ dry-run'
+                    : `✗ error: ${r.error}`;
+        lines.push(`  [${r.name}] ${tag}`);
+        lines.push(`    ${r.path}`);
+        if (r.backupPath) {
+            lines.push(`    backup: ${r.backupPath}`);
+        }
+        for (const s of r.servers) {
+            const sym = s.status === 'wrapped' ? '+'
+                : s.status === 'already-wrapped' ? '='
+                    : '·';
+            const reason = s.reason ? ` (${s.reason})` : '';
+            lines.push(`      ${sym} ${s.serverName}${reason}`);
+        }
+    }
+    lines.push('');
+    if (!report.apiKeyConfigured && !unwrap) {
+        lines.push('⚠ No API key configured. Tracking will be disabled until you set one:');
+        lines.push('    mcpspend config set apiKey mcps_live_xxx');
+        lines.push('  Get a key at https://mcpspend.com/dashboard/keys');
+    }
+    else if (!unwrap) {
+        lines.push(`API key source: ${report.apiKeySource}`);
+    }
+    if (action === 'Wrap' && report.clientsPatched > 0) {
+        lines.push('');
+        lines.push('Restart your MCP clients (Claude Desktop, Cursor, etc.) to pick up the new config.');
+    }
+    return lines.join('\n');
+}
+async function runDoctor(cliVersion) {
+    const cfg = (0, config_js_1.loadConfig)();
+    const apiKeySource = process.env.MCPSPEND_API_KEY
+        ? 'env'
+        : cfg.apiKey
+            ? 'config'
+            : 'none';
+    const discovered = (0, clients_js_1.discoverClients)();
+    const discoveredById = new Map(discovered.map((d) => [d.client.id, d]));
+    const clients = clients_js_1.CLIENTS.map((c) => {
+        const found = discoveredById.get(c.id);
+        if (!found) {
+            return { client: c.id, name: c.name, detected: false, serversCount: 0, wrappedCount: 0 };
+        }
+        let serversCount = 0;
+        let wrappedCount = 0;
+        try {
+            const cfg = (0, clients_js_1.readClientConfig)(found.path);
+            const serversKey = c.serversKey || 'mcpServers';
+            const servers = cfg[serversKey] || {};
+            serversCount = Object.keys(servers).length;
+            for (const s of Object.values(servers)) {
+                if (s && typeof s.command === 'string' && (0, clients_js_1.isAlreadyWrapped)(s))
+                    wrappedCount++;
+            }
+        }
+        catch { }
+        return { client: c.id, name: c.name, path: found.path, detected: true, serversCount, wrappedCount };
+    });
+    let endpointReachable;
+    let endpointError;
+    try {
+        const url = (cfg.endpoint || 'https://api.mcpspend.com') + '/health';
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 5000);
+        const resp = await fetch(url, { signal: ac.signal });
+        clearTimeout(timer);
+        endpointReachable = resp.ok;
+        if (!resp.ok)
+            endpointError = `HTTP ${resp.status}`;
+    }
+    catch (err) {
+        endpointReachable = false;
+        endpointError = err.message;
+    }
+    return {
+        cliVersion,
+        apiKeyConfigured: apiKeySource !== 'none',
+        apiKeySource,
+        endpointReachable,
+        endpointError,
+        clients,
+    };
+}
+function formatDoctor(report) {
+    const lines = [];
+    lines.push(`mcpspend v${report.cliVersion}`);
+    lines.push('');
+    lines.push(`API key:    ${report.apiKeyConfigured ? '✓' : '✗'} (${report.apiKeySource})`);
+    lines.push(`Endpoint:   ${report.endpointReachable ? '✓ reachable' : `✗ ${report.endpointError || 'unreachable'}`}`);
+    lines.push('');
+    lines.push('Clients:');
+    for (const c of report.clients) {
+        if (!c.detected) {
+            lines.push(`  · ${c.name} — not installed`);
+            continue;
+        }
+        const wrap = c.serversCount === 0 ? 'no servers configured' : `${c.wrappedCount}/${c.serversCount} wrapped`;
+        lines.push(`  ✓ ${c.name} — ${wrap}`);
+        if (c.path)
+            lines.push(`    ${c.path}`);
+    }
+    if (!report.apiKeyConfigured) {
+        lines.push('');
+        lines.push('Next: mcpspend config set apiKey mcps_live_xxx  (get one at https://mcpspend.com/dashboard/keys)');
+    }
+    return lines.join('\n');
+}

package/dist/proxy.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from './config.js';
+export declare function runProxy(opts: {
+    command: string;
+    args: string[];
+    config: Config;
+    model: string;
+}): Promise<number>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpspend/proxy",
-  "version": "0.1.5",
+  "version": "0.2.2",
   "description": "Transparent proxy CLI for MCP servers — tracks tool calls, latency, and cost via MCPSpend.",
   "license": "MIT",
   "homepage": "https://mcpspend.com",
@@ -22,6 +22,7 @@
     "mcpspend": "dist/cli.js"
   },
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "README.md"