@mcpspend/proxy 0.3.1 → 0.5.0

package/dist/cli.js

@@ -4,13 +4,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const config_js_1 = require("./config.js");
 const proxy_js_1 = require("./proxy.js");
 const init_js_1 = require("./init.js");
-const VERSION = '0.3.1';
+const snippet_js_1 = require("./snippet.js");
+const http_bridge_js_1 = require("./http-bridge.js");
+const VERSION = '0.5.0';
 const HELP = `mcpspend — observability proxy for MCP servers (v${VERSION})
 
 USAGE
   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 wrap-http [options]          Wrap a REMOTE HTTP MCP server (Figma, etc.)
+                                        Speaks stdio to the client, HTTP to the server.
+  mcpspend snippet [options] -- <cmd>...
+                                        Print a paste-ready JSON snippet for a
+                                        specific client (Windsurf protobuf, custom).
   mcpspend config set <key> <value>
   mcpspend config show
   mcpspend --version | --help
@@ -33,6 +40,24 @@ WRAP OPTIONS
   --model <name>           Model name for cost attribution (default: mcp-stdio)
   --disable                Run in passthrough mode (no tracking)
 
+WRAP-HTTP OPTIONS
+  --url <url>              Required. Remote MCP endpoint (POSTs JSON-RPC there).
+  --key <value>            API key (overrides config + MCPSPEND_API_KEY)
+  --endpoint <url>         MCPSpend API endpoint (NOT the remote MCP URL)
+  --project <id>           Attribute calls to this project
+  --agent <name>           Agent name reported in dashboards
+  --model <name>           Model name for cost attribution (default: mcp-http)
+  --auth <header>          Pass-through Authorization header to the remote MCP
+
+SNIPPET OPTIONS
+  --client <id>            One of: claude-desktop, cursor, windsurf, vscode,
+                           vscode-workspace, claude-code, generic. Default: generic.
+  --name <name>            Server name in the resulting JSON. Default: inferred from --
+  --project <id>           Attribute calls to this project (baked into wrap args)
+  --endpoint <url>         API endpoint
+  --agent <name>           Agent name
+  --style <npx|bin>        Wrap style. Default: npx (no global install required).
+
 EXAMPLES
   # First-time setup: paste your API key, patch every installed MCP client
   mcpspend init --key mcps_live_xxx
@@ -49,7 +74,14 @@ EXAMPLES
   # 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
+  # Get a copy-paste snippet for Windsurf (which stores config as protobuf)
+  mcpspend snippet --client windsurf --name playwright -- npx -y @playwright/mcp@latest
+
+  # Wrap a REMOTE HTTP MCP server (figma-remote etc.)
+  mcpspend wrap-http --url https://mcp.figma.com --key mcps_live_xxx \
+    --auth "Bearer FIGMA_TOKEN"
+
+Environment variables: MCPSPEND_API_KEY, MCPSPEND_ENDPOINT, MCPSPEND_PROJECT_ID, MCPSPEND_AGENT_NAME, MCPSPEND_DISABLED=1, MCPSPEND_NO_TELEMETRY=1
 Config file: ~/.mcpspend/config.json
 `;
 function parseArgs(argv) {
@@ -57,6 +89,8 @@ function parseArgs(argv) {
         command: 'help',
         wrapOpts: {},
         initOpts: { clients: [], dryRun: false, unwrap: false },
+        snippetOpts: { client: 'generic', style: 'npx' },
+        httpOpts: {},
         childArgs: [],
     };
     if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
@@ -114,6 +148,105 @@ function parseArgs(argv) {
         result.command = 'doctor';
         return result;
     }
+    if (cmd === 'wrap-http') {
+        result.command = 'wrap-http';
+        let i = 1;
+        while (i < argv.length) {
+            const a = argv[i];
+            const next = argv[i + 1];
+            switch (a) {
+                case '--url':
+                    result.httpOpts.url = next;
+                    i += 2;
+                    break;
+                case '--key':
+                    result.httpOpts.apiKey = next;
+                    i += 2;
+                    break;
+                case '--endpoint':
+                    result.httpOpts.endpoint = next;
+                    i += 2;
+                    break;
+                case '--project':
+                    result.httpOpts.projectId = next;
+                    i += 2;
+                    break;
+                case '--agent':
+                    result.httpOpts.agentName = next;
+                    i += 2;
+                    break;
+                case '--model':
+                    result.httpOpts.model = next;
+                    i += 2;
+                    break;
+                case '--auth':
+                    result.httpOpts.auth = next;
+                    i += 2;
+                    break;
+                default:
+                    process.stderr.write(`mcpspend: unknown option ${a}\n`);
+                    process.exit(2);
+            }
+        }
+        if (!result.httpOpts.url) {
+            process.stderr.write('mcpspend: wrap-http requires --url <https://...>\n');
+            process.exit(2);
+        }
+        return result;
+    }
+    if (cmd === 'snippet') {
+        result.command = 'snippet';
+        let i = 1;
+        while (i < argv.length) {
+            const a = argv[i];
+            if (a === '--') {
+                i++;
+                break;
+            }
+            const next = argv[i + 1];
+            switch (a) {
+                case '--client':
+                    result.snippetOpts.client = next;
+                    i += 2;
+                    break;
+                case '--name':
+                    result.snippetOpts.name = next;
+                    i += 2;
+                    break;
+                case '--project':
+                    result.snippetOpts.projectId = next;
+                    i += 2;
+                    break;
+                case '--endpoint':
+                    result.snippetOpts.endpoint = next;
+                    i += 2;
+                    break;
+                case '--agent':
+                    result.snippetOpts.agentName = next;
+                    i += 2;
+                    break;
+                case '--style':
+                    if (next === 'npx' || next === 'bin')
+                        result.snippetOpts.style = next;
+                    else {
+                        process.stderr.write('mcpspend: --style must be npx or bin\n');
+                        process.exit(2);
+                    }
+                    i += 2;
+                    break;
+                default:
+                    process.stderr.write(`mcpspend: unknown option ${a}\n`);
+                    process.exit(2);
+            }
+        }
+        if (i >= argv.length) {
+            process.stderr.write('mcpspend: missing command for snippet. Use: mcpspend snippet [options] -- <command> [args...]\n');
+            process.exit(2);
+        }
+        result.childCommand = argv[i];
+        result.childArgs = argv.slice(i + 1);
+        return result;
+    }
     if (cmd === 'wrap') {
         result.command = 'wrap';
         let i = 1;
@@ -206,6 +339,10 @@ async function main() {
             unwrap: parsed.initOpts.unwrap,
         });
         process.stdout.write((0, init_js_1.formatReport)(report, parsed.initOpts.unwrap) + '\n');
+        // Fire-and-forget anonymous compat report. Tells us when a client's schema
+        // changes so we can ship a fix BEFORE users notice. Opt out via
+        // MCPSPEND_NO_TELEMETRY=1. We swallow errors — telemetry is never blocking.
+        void (0, init_js_1.reportCompatFromInit)(VERSION, report);
         if (report.clients.some((c) => c.status === 'error'))
             process.exit(1);
         return;
@@ -217,6 +354,21 @@ async function main() {
             process.exit(1);
         return;
     }
+    if (parsed.command === 'snippet') {
+        const inferredName = guessServerName(parsed.childCommand, parsed.childArgs);
+        const out = (0, snippet_js_1.buildSnippet)({
+            client: parsed.snippetOpts.client,
+            serverName: parsed.snippetOpts.name || inferredName,
+            command: parsed.childCommand,
+            args: parsed.childArgs,
+            projectId: parsed.snippetOpts.projectId,
+            endpoint: parsed.snippetOpts.endpoint,
+            agentName: parsed.snippetOpts.agentName,
+            style: parsed.snippetOpts.style,
+        });
+        process.stdout.write((0, snippet_js_1.formatSnippet)(out) + '\n');
+        return;
+    }
     if (parsed.command === 'config') {
         if (parsed.configAction === 'show') {
             const cfg = (0, config_js_1.loadConfig)();
@@ -249,6 +401,54 @@ async function main() {
         });
         process.exit(code);
     }
+    if (parsed.command === 'wrap-http') {
+        const cfg = (0, config_js_1.loadConfig)({
+            apiKey: parsed.httpOpts.apiKey,
+            endpoint: parsed.httpOpts.endpoint,
+            projectId: parsed.httpOpts.projectId,
+            agentName: parsed.httpOpts.agentName,
+        });
+        const code = await (0, http_bridge_js_1.runHttpBridge)({
+            url: parsed.httpOpts.url,
+            config: cfg,
+            model: parsed.httpOpts.model || process.env.MCPSPEND_MODEL || 'mcp-http',
+            remoteAuthHeader: parsed.httpOpts.auth,
+        });
+        process.exit(code);
+    }
+}
+// Very small heuristic — keeps snippet code self-contained without exporting
+// extractServerName from proxy.ts. Same trade-off rules apply: drop versions,
+// drop scopes that reduce to "mcp", strip mcp-server- prefixes.
+function guessServerName(command, args) {
+    const skip = new Set(['npx', 'npx.cmd', 'uvx', 'pnpx', 'bunx', 'pipx', 'node', 'bun', 'deno', 'python', 'python3']);
+    const tokens = [command, ...args].filter((t) => t && !t.startsWith('-') && !skip.has(t.toLowerCase()));
+    for (const raw of tokens) {
+        let t = raw;
+        const lastAt = t.lastIndexOf('@');
+        if (lastAt > 0)
+            t = t.slice(0, lastAt);
+        let scope = null;
+        if (t.startsWith('@')) {
+            const slash = t.indexOf('/');
+            if (slash > 0) {
+                scope = t.slice(1, slash);
+                t = t.slice(slash + 1);
+            }
+        }
+        t = (t.split(/[\\/]/).pop() || t).replace(/\.(js|cjs|mjs|ts|tsx|py)$/i, '');
+        t = t.replace(/^mcp-server-/i, '').replace(/-mcp-server$/i, '');
+        t = t.replace(/^server-/i, '').replace(/-server$/i, '');
+        t = t.replace(/^mcp-/i, '').replace(/-mcp$/i, '');
+        t = t.toLowerCase().trim();
+        if (!t || t === 'mcp' || t === 'server') {
+            if (scope)
+                return scope.toLowerCase();
+            continue;
+        }
+        return t;
+    }
+    return 'mcp-server';
 }
 main().catch((err) => {
     process.stderr.write(`mcpspend: ${err instanceof Error ? err.message : String(err)}\n`);

package/dist/clients.js

@@ -31,7 +31,13 @@ exports.CLIENTS = [
     {
         id: 'cursor',
         name: 'Cursor',
-        configPaths: () => [(0, node_path_1.join)(home, '.cursor', 'mcp.json')],
+        configPaths: () => [
+            (0, node_path_1.join)(home, '.cursor', 'mcp.json'),
+            // Cursor also supports a workspace-scoped config at .cursor/mcp.json
+            // in the project. We discover it from process.cwd() so init knows about
+            // the project the user is currently in.
+            (0, node_path_1.join)(process.cwd(), '.cursor', 'mcp.json'),
+        ],
     },
     {
         id: 'windsurf',
@@ -75,29 +81,44 @@ exports.CLIENTS = [
         },
         serversKey: 'servers',
     },
+    {
+        id: 'vscode-workspace',
+        name: 'VS Code (workspace)',
+        // Workspace-scoped MCP config that lives inside the project. Cursor also
+        // reads this file because Cursor is a VS Code fork, so wrapping it here
+        // covers both. We resolve from process.cwd() — `init` should be run from
+        // the project root.
+        configPaths: () => [(0, node_path_1.join)(process.cwd(), '.vscode', 'mcp.json')],
+        serversKey: 'servers',
+    },
     {
         id: 'claude-code',
         name: 'Claude Code',
-        configPaths: () => [(0, node_path_1.join)(home, '.claude.json')],
+        // User-level config at ~/.claude.json AND project-level `.mcp.json` in
+        // the current working directory. The project-level file is the standard
+        // way to ship MCP server lists with a repository.
+        configPaths: () => [
+            (0, node_path_1.join)(home, '.claude.json'),
+            (0, node_path_1.join)(process.cwd(), '.mcp.json'),
+        ],
     },
 ];
 function discoverClients() {
     const found = [];
     for (const c of exports.CLIENTS) {
-        let matched = false;
-        // First try existing config files (the common case).
-        for (const p of c.configPaths()) {
-            if ((0, node_fs_1.existsSync)(p)) {
+        // Collect EVERY existing config file for this client, not just the first.
+        // Claude Code in particular has both a user-level (~/.claude.json) and
+        // project-level (./.mcp.json) location and they're independent.
+        const existing = c.configPaths().filter(p => (0, node_fs_1.existsSync)(p));
+        if (existing.length > 0) {
+            for (const p of existing) {
                 found.push({ client: c, path: p });
-                matched = true;
-                break;
             }
-        }
-        if (matched)
             continue;
+        }
         // Fall back to install markers. If the client is installed but has never
         // had a config written, take the first configPath as the destination and
-        // mark the discovery as bootstrapped.
+        // mark the discovery as bootstrapped so init creates the file.
         if (c.installMarkers) {
             const installed = c.installMarkers().some(p => (0, node_fs_1.existsSync)(p));
             if (installed) {

package/dist/http-bridge.d.ts

@@ -0,0 +1,8 @@
+import type { Config } from './config.js';
+export interface HttpWrapOptions {
+    url: string;
+    config: Config;
+    model: string;
+    remoteAuthHeader?: string;
+}
+export declare function runHttpBridge(opts: HttpWrapOptions): Promise<number>;

package/dist/http-bridge.js

@@ -0,0 +1,137 @@
+"use strict";
+// Stdio→HTTP bridge for remote MCP servers.
+//
+// `mcpspend wrap-http --url https://figma.com/mcp --key mcps_live_xxx` exposes
+// a local stdio MCP server that proxies every JSON-RPC message to the remote
+// HTTP endpoint and records each tools/call to MCPSpend — same metadata pipeline
+// as the stdio wrap (server name, latency, token estimate). The MCP client (any
+// of them) sees a normal stdio server; the user never has to know it's HTTP
+// behind the scenes.
+//
+// We deliberately do not implement SSE/Streamable response streaming yet — most
+// remote MCP servers in 2026 accept simple POST + JSON response. When we hit
+// a server that needs streaming we'll bolt it on here without changing the
+// stdio surface.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHttpBridge = runHttpBridge;
+const node_crypto_1 = require("node:crypto");
+const ingest_js_1 = require("./ingest.js");
+function estimateTokens(payload) {
+    if (payload === undefined || payload === null)
+        return 0;
+    const s = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    return Math.max(1, Math.ceil(s.length / 4));
+}
+function inferServerNameFromUrl(url) {
+    try {
+        const u = new URL(url);
+        // figma.com → figma · api.notion.com → notion · mcp.foo.dev → foo
+        const host = u.hostname.replace(/^(api|mcp)\./, '');
+        const parts = host.split('.');
+        return parts.length >= 2 ? parts[parts.length - 2] : host;
+    }
+    catch {
+        return 'remote-mcp';
+    }
+}
+async function runHttpBridge(opts) {
+    const serverName = inferServerNameFromUrl(opts.url);
+    const sessionId = (0, node_crypto_1.randomUUID)();
+    const ingest = new ingest_js_1.Ingest(opts.config);
+    const pending = new Map();
+    if (!opts.config.apiKey) {
+        process.stderr.write('[mcpspend wrap-http] no API key configured — running in passthrough mode (no tracking)\n');
+    }
+    async function forward(msg) {
+        const headers = { 'Content-Type': 'application/json' };
+        if (opts.remoteAuthHeader)
+            headers['Authorization'] = opts.remoteAuthHeader;
+        const r = await fetch(opts.url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(msg),
+        });
+        const text = await r.text();
+        if (!text.trim())
+            return null;
+        // The remote may return a single JSON-RPC envelope OR a batch (array).
+        // We pass through whatever we got — stdio readers handle batches fine.
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            process.stderr.write(`[mcpspend wrap-http] bad response from ${opts.url}: ${text.slice(0, 200)}\n`);
+            return null;
+        }
+    }
+    function onCallStart(msg) {
+        if (msg.method !== 'tools/call' || msg.id == null || !msg.params)
+            return;
+        const params = msg.params;
+        if (!params.name)
+            return;
+        pending.set(msg.id, {
+            toolName: params.name,
+            serverName,
+            startedAt: Date.now(),
+            inputTokens: estimateTokens(params.arguments),
+        });
+    }
+    function onCallEnd(msg) {
+        if (msg.id == null)
+            return;
+        const call = pending.get(msg.id);
+        if (!call)
+            return;
+        pending.delete(msg.id);
+        const latencyMs = Date.now() - call.startedAt;
+        const success = !msg.error;
+        const outputTokens = estimateTokens(success ? msg.result : msg.error);
+        void ingest.enqueue({
+            sessionId,
+            serverName: call.serverName,
+            toolName: call.toolName,
+            model: opts.model,
+            inputTokens: call.inputTokens,
+            outputTokens,
+            latencyMs,
+            success,
+            errorCode: msg.error?.code ? String(msg.error.code) : undefined,
+            calledAt: new Date(call.startedAt).toISOString(),
+        });
+    }
+    // Stdio loop: read line-delimited JSON from stdin, forward to HTTP, write
+    // response back to stdout.
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', async (chunk) => {
+        buf += chunk;
+        let nl;
+        while ((nl = buf.indexOf('\n')) !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                const msg = JSON.parse(line);
+                onCallStart(msg);
+                const resp = await forward(msg);
+                if (resp) {
+                    onCallEnd(resp);
+                    process.stdout.write(JSON.stringify(resp) + '\n');
+                }
+            }
+            catch (err) {
+                process.stderr.write(`[mcpspend wrap-http] error: ${err.message}\n`);
+            }
+        }
+    });
+    return new Promise((resolve) => {
+        process.stdin.on('end', async () => {
+            await ingest.flush();
+            resolve(0);
+        });
+        process.on('SIGTERM', () => { void ingest.flush().then(() => resolve(0)); });
+        process.on('SIGINT', () => { void ingest.flush().then(() => resolve(0)); });
+    });
+}

package/dist/init.d.ts

@@ -26,6 +26,12 @@ export interface InitReport {
     clients: ClientReport[];
 }
 export declare function runInit(opts?: InitOptions): InitReport;
+/**
+ * Fire a fire-and-forget anonymous compat report. Caller decides when to call —
+ * we don't run it inside runInit() to keep that function pure and testable.
+ * Opt out: MCPSPEND_NO_TELEMETRY=1.
+ */
+export declare function reportCompatFromInit(cliVersion: string, init: InitReport): Promise<void>;
 export declare function formatReport(report: InitReport, unwrap?: boolean): string;
 export interface DoctorReport {
     cliVersion: string;

package/dist/init.js

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runInit = runInit;
+exports.reportCompatFromInit = reportCompatFromInit;
 exports.formatReport = formatReport;
 exports.runDoctor = runDoctor;
 exports.formatDoctor = formatDoctor;
+const node_os_1 = require("node:os");
 const clients_js_1 = require("./clients.js");
 const config_js_1 = require("./config.js");
+const telemetry_js_1 = require("./telemetry.js");
 function runInit(opts = {}) {
     if (opts.apiKey) {
         (0, config_js_1.saveConfig)({ apiKey: opts.apiKey });
@@ -108,6 +111,38 @@ function runInit(opts = {}) {
         clients: clientReports,
     };
 }
+/**
+ * Fire a fire-and-forget anonymous compat report. Caller decides when to call —
+ * we don't run it inside runInit() to keep that function pure and testable.
+ * Opt out: MCPSPEND_NO_TELEMETRY=1.
+ */
+async function reportCompatFromInit(cliVersion, init) {
+    const reports = init.clients.map((r) => {
+        let fp;
+        let format;
+        try {
+            const parsed = (0, clients_js_1.readClientConfig)(r.path);
+            fp = (0, telemetry_js_1.fingerprintConfig)(parsed);
+            format = 'json';
+        }
+        catch {
+            format = 'missing';
+        }
+        return {
+            id: r.client,
+            status: r.bootstrapped ? 'bootstrapped' : r.status,
+            configFormat: format,
+            topLevelKeysFingerprint: fp,
+            serverCount: r.servers.length,
+            wrappedCount: r.servers.filter((s) => s.status === 'wrapped' || s.status === 'already-wrapped').length,
+        };
+    });
+    await (0, telemetry_js_1.sendCompatReport)({
+        cliVersion,
+        platform: (0, node_os_1.platform)(),
+        reports,
+    });
+}
 function formatReport(report, unwrap = false) {
     const lines = [];
     const action = unwrap ? 'Unwrap' : 'Wrap';

package/dist/snippet.d.ts

@@ -0,0 +1,20 @@
+import { WrapOptions } from './clients.js';
+export type SnippetClient = 'claude-desktop' | 'cursor' | 'windsurf' | 'vscode' | 'vscode-workspace' | 'claude-code' | 'generic';
+export interface SnippetOptions extends WrapOptions {
+    client: SnippetClient;
+    serverName: string;
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface SnippetOutput {
+    client: SnippetClient;
+    destination: string;
+    serversKey: string;
+    /** Stringified JSON ready to paste, plus the entry's name as the object key. */
+    json: string;
+    /** Plain instructions tailored to the client. */
+    instructions: string[];
+}
+export declare function buildSnippet(opts: SnippetOptions): SnippetOutput;
+export declare function formatSnippet(out: SnippetOutput): string;

package/dist/snippet.js

@@ -0,0 +1,119 @@
+"use strict";
+// Generates ready-to-paste snippets for clients we cannot auto-patch
+// (Windsurf in protobuf mode, custom JSON files, etc.).
+//
+// The user runs:
+//   mcpspend snippet --client windsurf -- npx -y @playwright/mcp@latest
+//
+// We print:
+//   1. The destination path / UI navigation for the chosen client
+//   2. The wrapped JSON they should paste
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSnippet = buildSnippet;
+exports.formatSnippet = formatSnippet;
+const clients_js_1 = require("./clients.js");
+const TEMPLATES = {
+    'claude-desktop': {
+        destination: '%APPDATA%\\Claude\\claude_desktop_config.json (Windows)  ·  ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)',
+        serversKey: 'mcpServers',
+        instructions: (s) => [
+            'Open the file above (create it if missing).',
+            `Add the snippet under "mcpServers" → "${s}".`,
+            'Quit Claude Desktop fully and reopen.',
+        ],
+    },
+    cursor: {
+        destination: '~/.cursor/mcp.json  (or .cursor/mcp.json in this project for workspace-scoped)',
+        serversKey: 'mcpServers',
+        instructions: (s) => [
+            'Open the file above (create it if missing).',
+            `Add the snippet under "mcpServers" → "${s}".`,
+            'Reload Cursor (Cmd/Ctrl + Shift + P → "Reload Window").',
+        ],
+    },
+    windsurf: {
+        destination: 'Settings → Cascade → MCP Servers → Add server (UI only — Windsurf no longer reads JSON)',
+        serversKey: 'mcpServers',
+        instructions: (s) => [
+            'Recent Windsurf versions store MCP config in a protobuf binary; you have to add the server through the UI.',
+            'Open Windsurf → Settings → Cascade → MCP Servers → "Add server".',
+            `Use this server name: ${s}`,
+            'Paste the command + args from the JSON snippet below into the corresponding fields.',
+            'Start a NEW Cascade conversation — the existing one won\'t see the new server until then.',
+        ],
+    },
+    vscode: {
+        destination: '%APPDATA%\\Code\\User\\mcp.json (Windows)  ·  ~/.config/Code/User/mcp.json (Linux)  ·  ~/Library/Application Support/Code/User/mcp.json (macOS)',
+        serversKey: 'servers',
+        instructions: (s) => [
+            'Open the file above (create it if missing).',
+            `Add the snippet under "servers" → "${s}".`,
+            'Reload VS Code.',
+        ],
+    },
+    'vscode-workspace': {
+        destination: '.vscode/mcp.json (in your project root)',
+        serversKey: 'servers',
+        instructions: (s) => [
+            'Create .vscode/mcp.json in your project root (if missing).',
+            `Add the snippet under "servers" → "${s}".`,
+            'Reload VS Code.',
+        ],
+    },
+    'claude-code': {
+        destination: '.mcp.json (project root)  or  ~/.claude.json (user-level)',
+        serversKey: 'mcpServers',
+        instructions: (s) => [
+            'For per-project: create .mcp.json in the project root.',
+            'For user-global: edit ~/.claude.json (add an "mcpServers" key if missing).',
+            `Place the snippet under "mcpServers" → "${s}".`,
+            'Restart the Claude Code panel / re-open the conversation.',
+        ],
+    },
+    generic: {
+        destination: 'Wherever your MCP client reads its config.',
+        serversKey: 'mcpServers',
+        instructions: (s) => [
+            `Add the snippet below as the value for "${s}" inside your client's mcpServers (or equivalent) object.`,
+            'Restart the client.',
+        ],
+    },
+};
+function buildSnippet(opts) {
+    const tmpl = TEMPLATES[opts.client];
+    const baseEntry = { command: opts.command, args: opts.args };
+    if (opts.env)
+        baseEntry.env = opts.env;
+    const wrapped = (0, clients_js_1.wrapEntry)(baseEntry, {
+        projectId: opts.projectId,
+        endpoint: opts.endpoint,
+        agentName: opts.agentName,
+        style: opts.style ?? 'npx',
+    });
+    const obj = { [opts.serverName]: wrapped };
+    const json = JSON.stringify(obj, null, 2);
+    return {
+        client: opts.client,
+        destination: tmpl.destination,
+        serversKey: tmpl.serversKey,
+        json,
+        instructions: tmpl.instructions(opts.serverName),
+    };
+}
+function formatSnippet(out) {
+    const lines = [];
+    lines.push('');
+    lines.push(`▾ ${out.client.toUpperCase()} — paste-ready snippet`);
+    lines.push('');
+    lines.push('Destination:');
+    lines.push(`  ${out.destination}`);
+    lines.push('');
+    lines.push('Steps:');
+    out.instructions.forEach((s, i) => lines.push(`  ${i + 1}. ${s}`));
+    lines.push('');
+    lines.push(`JSON (under "${out.serversKey}"):`);
+    lines.push('');
+    out.json.split('\n').forEach((l) => lines.push('  ' + l));
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,16 @@
+export interface CompatClientReport {
+    id: string;
+    status: 'patched' | 'no-changes' | 'error' | 'dry-run' | 'bootstrapped' | 'not-detected';
+    configFormat?: 'json' | 'protobuf' | 'binary-unknown' | 'missing';
+    topLevelKeysFingerprint?: string;
+    serverCount?: number;
+    wrappedCount?: number;
+}
+export interface CompatPayload {
+    cliVersion: string;
+    platform: string;
+    reports: CompatClientReport[];
+    errorSummary?: string;
+}
+export declare function fingerprintConfig(parsed: unknown): string;
+export declare function sendCompatReport(payload: CompatPayload, endpoint?: string): Promise<void>;

package/dist/telemetry.js

@@ -0,0 +1,51 @@
+"use strict";
+// Anonymous compatibility telemetry.
+//
+// Why: clients like Windsurf or Cursor occasionally change where or how they
+// store MCP config. The moment they do, our `init` silently stops auto-
+// patching for that client. We won't hear about it until a user files an
+// issue — by then the bad version has shipped to thousands.
+//
+// Solution: when init/doctor runs, POST a small payload to
+//   /api/internal/compat-report
+// describing what we found per client. The backend aggregates schema
+// fingerprints + version hashes. When a new fingerprint appears for an
+// existing client we get an alert and ship a fix.
+//
+// Payload is anonymous: no user identity, no config contents — only:
+//   - cli version (so we know which mcpspend rolled into the wall)
+//   - per-client: { id, configFormat, fingerprint, status }
+//     where fingerprint = sha256(sorted top-level keys) — leaks zero PII but
+//     lets us spot "this file used to have mcpServers, now has serverGroups".
+//
+// Opt out: MCPSPEND_NO_TELEMETRY=1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintConfig = fingerprintConfig;
+exports.sendCompatReport = sendCompatReport;
+const node_crypto_1 = require("node:crypto");
+const ENDPOINT_DEFAULT = 'https://api.mcpspend.com/api/internal/compat-report';
+function fingerprintConfig(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return 'NA';
+    const keys = Object.keys(parsed).sort();
+    return (0, node_crypto_1.createHash)('sha256').update(keys.join(',')).digest('hex').slice(0, 16);
+}
+async function sendCompatReport(payload, endpoint) {
+    if (process.env.MCPSPEND_NO_TELEMETRY === '1')
+        return;
+    const url = endpoint || process.env.MCPSPEND_COMPAT_ENDPOINT || ENDPOINT_DEFAULT;
+    try {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 4000);
+        await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: ac.signal,
+        }).catch(() => undefined);
+        clearTimeout(timer);
+    }
+    catch {
+        // Never propagate telemetry failures.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpspend/proxy",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Transparent proxy CLI for MCP servers — tracks tool calls, latency, and cost via MCPSpend.",
   "license": "MIT",
   "homepage": "https://mcpspend.com",