@mcpspend/proxy 0.2.1 → 0.3.0

package/dist/cli.js

@@ -4,7 +4,7 @@ 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.2.1';
+const VERSION = '0.3.0';
 const HELP = `mcpspend — observability proxy for MCP servers (v${VERSION})
 
 USAGE

package/dist/clients.d.ts

@@ -12,12 +12,14 @@ export interface ClientDefinition {
     id: 'claude-desktop' | 'cursor' | 'windsurf' | 'vscode' | 'vscode-workspace' | 'claude-code';
     name: string;
     configPaths: () => string[];
+    installMarkers?: () => string[];
     serversKey?: string;
 }
 export declare const CLIENTS: ClientDefinition[];
 export interface DiscoveredClient {
     client: ClientDefinition;
     path: string;
+    bootstrapped?: boolean;
 }
 export declare function discoverClients(): DiscoveredClient[];
 export declare function readClientConfig(path: string): ClientConfig;
@@ -27,6 +29,7 @@ export interface WrapResult {
     status: 'wrapped' | 'already-wrapped' | 'skipped';
     reason?: string;
 }
+export declare function isAlreadyWrapped(entry: McpServerEntry): boolean;
 export interface WrapOptions {
     apiKey?: string;
     projectId?: string;

package/dist/clients.js

@@ -4,6 +4,7 @@ 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;
@@ -39,6 +40,22 @@ exports.CLIENTS = [
             (0, node_path_1.join)(home, '.codeium', 'windsurf', 'mcp_config.json'),
             (0, node_path_1.join)(home, '.codeium', 'windsurf-next', 'mcp_config.json'),
         ],
+        // Windsurf only creates mcp_config.json after the user adds a server via
+        // the UI. The .codeium/windsurf dir exists from the moment Windsurf runs
+        // once, and the AppData install dir exists from the install itself.
+        installMarkers: () => {
+            const markers = [
+                (0, node_path_1.join)(home, '.codeium', 'windsurf'),
+                (0, node_path_1.join)(home, '.codeium', 'windsurf-next'),
+            ];
+            if (isWin) {
+                markers.push((0, node_path_1.join)(process.env.LOCALAPPDATA || (0, node_path_1.join)(home, 'AppData', 'Local'), 'Windsurf'));
+            }
+            else if (isMac) {
+                markers.push('/Applications/Windsurf.app');
+            }
+            return markers;
+        },
     },
     {
         id: 'vscode',
@@ -67,12 +84,29 @@ exports.CLIENTS = [
 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)) {
                 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.
+        if (c.installMarkers) {
+            const installed = c.installMarkers().some(p => (0, node_fs_1.existsSync)(p));
+            if (installed) {
+                const paths = c.configPaths();
+                if (paths.length > 0) {
+                    found.push({ client: c, path: paths[0], bootstrapped: true });
+                }
+            }
+        }
     }
     return found;
 }
@@ -111,6 +145,15 @@ function writeClientConfig(path, config, backupSuffix = '.mcpspend.bak') {
 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;
@@ -118,10 +161,10 @@ function isAlreadyWrapped(entry) {
     // Shape A: `mcpspend wrap ...`
     if (MCPSPEND_BIN_NAMES.has(base) && args[0] === 'wrap')
         return true;
-    // Shape B: `npx [-y] @mcpspend/proxy wrap ...`
+    // 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 (args[skipFlag] === PROXY_PKG && args[skipFlag + 1] === 'wrap')
+        if (isProxyPackageArg(args[skipFlag]) && args[skipFlag + 1] === 'wrap')
             return true;
     }
     return false;

package/dist/clients.test.d.ts

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

package/dist/clients.test.js

@@ -0,0 +1,133 @@
+"use strict";
+// Unit tests for the wrap/unwrap logic in clients.ts.
+//
+// History: we shipped 0.2.0 with isAlreadyWrapped() failing to recognise
+// `npx -y @mcpspend/proxy@latest wrap …`, which caused init to double-wrap
+// configs that users had previously set up manually. These tests pin down
+// every wrap shape we ever generate or accept.
+//
+// Run with: node --test --import tsx src/clients.test.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const clients_js_1 = require("./clients.js");
+(0, node_test_1.describe)('isAlreadyWrapped', () => {
+    (0, node_test_1.test)('recognises npx -y @mcpspend/proxy wrap', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'npx',
+            args: ['-y', '@mcpspend/proxy', 'wrap', '--', 'node', 'server.js'],
+        }), true);
+    });
+    (0, node_test_1.test)('recognises npx -y @mcpspend/proxy@latest wrap', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'npx',
+            args: ['-y', '@mcpspend/proxy@latest', 'wrap', '--', 'node', 'server.js'],
+        }), true);
+    });
+    (0, node_test_1.test)('recognises npx -y @mcpspend/proxy@0.2.2 wrap', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'npx',
+            args: ['-y', '@mcpspend/proxy@0.2.2', 'wrap', '--', 'node', 'server.js'],
+        }), true);
+    });
+    (0, node_test_1.test)('recognises npx without -y flag', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'npx',
+            args: ['@mcpspend/proxy', 'wrap', '--', 'node', 'server.js'],
+        }), true);
+    });
+    (0, node_test_1.test)('recognises bin-direct mcpspend wrap', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'mcpspend',
+            args: ['wrap', '--', 'node', 'server.js'],
+        }), true);
+    });
+    (0, node_test_1.test)('recognises absolute Windows path to mcpspend.cmd', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'C:\\Users\\me\\AppData\\Roaming\\npm\\mcpspend.cmd',
+            args: ['wrap', '--', 'node', 'server.js'],
+        }), true);
+    });
+    (0, node_test_1.test)('rejects unrelated npx invocations', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'npx',
+            args: ['-y', '@modelcontextprotocol/server-filesystem', '/data'],
+        }), false);
+    });
+    (0, node_test_1.test)('rejects raw mcpspend without wrap subcommand', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'mcpspend',
+            args: ['init', '--key', 'mcps_live_xxx'],
+        }), false);
+    });
+    (0, node_test_1.test)('rejects empty args', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({ command: 'npx', args: [] }), false);
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({ command: 'mcpspend', args: [] }), false);
+    });
+    (0, node_test_1.test)('rejects an npx invoking some other package called proxy', () => {
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)({
+            command: 'npx',
+            args: ['-y', '@otherorg/proxy', 'wrap', '--', 'node', 'server.js'],
+        }), false);
+    });
+});
+(0, node_test_1.describe)('wrap → unwrap roundtrip', () => {
+    (0, node_test_1.test)('npx-style preserves command + args + env', () => {
+        const original = {
+            command: 'npx',
+            args: ['-y', '@modelcontextprotocol/server-filesystem', '/data'],
+            env: { FOO: 'bar' },
+        };
+        const wrapped = (0, clients_js_1.wrapEntry)(original);
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)(wrapped), true, 'wrapped should be recognised');
+        const restored = (0, clients_js_1.unwrapEntry)(wrapped);
+        strict_1.default.deepEqual(restored, original);
+    });
+    (0, node_test_1.test)('bin-style preserves command + args + env', () => {
+        const original = {
+            command: 'node',
+            args: ['./my-server.js'],
+            env: { GITHUB_TOKEN: 'xxx' },
+        };
+        const wrapped = (0, clients_js_1.wrapEntry)(original, { style: 'bin' });
+        strict_1.default.equal(wrapped.command, 'mcpspend');
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)(wrapped), true);
+        const restored = (0, clients_js_1.unwrapEntry)(wrapped);
+        strict_1.default.deepEqual(restored, original);
+    });
+    (0, node_test_1.test)('does NOT bake the API key into wrapped args (prevents git leak)', () => {
+        const wrapped = (0, clients_js_1.wrapEntry)({ command: 'node', args: ['server.js'] }, { apiKey: 'mcps_live_SECRET' });
+        const flat = JSON.stringify(wrapped);
+        strict_1.default.equal(flat.includes('mcps_live_SECRET'), false);
+        strict_1.default.equal(flat.includes('--key'), false);
+    });
+    (0, node_test_1.test)('projectId and agentName are baked in (they are not secrets)', () => {
+        const wrapped = (0, clients_js_1.wrapEntry)({ command: 'node', args: ['server.js'] }, { projectId: 'prj_xyz', agentName: 'demo-agent' });
+        strict_1.default.ok(wrapped.args.includes('--project'));
+        strict_1.default.ok(wrapped.args.includes('prj_xyz'));
+        strict_1.default.ok(wrapped.args.includes('--agent'));
+        strict_1.default.ok(wrapped.args.includes('demo-agent'));
+    });
+});
+(0, node_test_1.describe)('unwrapEntry edge cases', () => {
+    (0, node_test_1.test)('returns null for non-wrapped entries (no-op safety)', () => {
+        strict_1.default.equal((0, clients_js_1.unwrapEntry)({ command: 'npx', args: ['some', 'thing'] }), null);
+    });
+    (0, node_test_1.test)('handles wrapped entry with no -- separator gracefully', () => {
+        strict_1.default.equal((0, clients_js_1.unwrapEntry)({ command: 'mcpspend', args: ['wrap'] }), null);
+    });
+});
+(0, node_test_1.describe)('idempotency', () => {
+    (0, node_test_1.test)('wrapping a wrapped entry should not double-wrap (guarded at wrapAllServers level)', () => {
+        // wrapEntry itself does not check — it's wrapAllServers that gates on
+        // isAlreadyWrapped. Confirm that the gate works as documented.
+        const original = { command: 'npx', args: ['@modelcontextprotocol/server-filesystem', '/data'] };
+        const once = (0, clients_js_1.wrapEntry)(original);
+        strict_1.default.equal((0, clients_js_1.isAlreadyWrapped)(once), true);
+        // If wrapAllServers correctly skips, the entry passed to wrapEntry would
+        // already be wrapped — but defensive callers should rely on isAlreadyWrapped.
+    });
+});

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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, } from './clients.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,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatDoctor = exports.formatReport = exports.runDoctor = exports.runInit = exports.unwrapEntry = exports.wrapEntry = exports.unwrapAllServers = exports.wrapAllServers = exports.writeClientConfig = exports.readClientConfig = exports.discoverClients = exports.CLIENTS = 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; } });
@@ -16,6 +16,7 @@ Object.defineProperty(exports, "wrapAllServers", { enumerable: true, get: functi
 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; } });

package/dist/init.d.ts

@@ -16,6 +16,7 @@ export interface ClientReport {
     backupPath?: string;
     servers: WrapResult[];
     error?: string;
+    bootstrapped?: boolean;
 }
 export interface InitReport {
     apiKeyConfigured: boolean;

package/dist/init.js

@@ -27,10 +27,24 @@ function runInit(opts = {}) {
         discovered = discovered.filter((d) => set.has(d.client.id));
     }
     const clientReports = [];
-    for (const { client, path } of discovered) {
+    for (const { client, path, bootstrapped } of discovered) {
         const serversKey = client.serversKey || 'mcpServers';
         try {
             const current = (0, clients_js_1.readClientConfig)(path);
+            // Bootstrap-mode: client is installed but has no MCP config yet. We still
+            // want to create the file with an empty mcpServers object so the user
+            // can add their first server via the UI and have it auto-wrapped on the
+            // next `init` run. Unwrap is a no-op here.
+            if (bootstrapped && opts.unwrap) {
+                clientReports.push({
+                    client: client.id,
+                    name: client.name,
+                    path,
+                    status: 'no-changes',
+                    servers: [],
+                });
+                continue;
+            }
             const { config: next, results } = opts.unwrap
                 ? (0, clients_js_1.unwrapAllServers)(current, serversKey)
                 : (0, clients_js_1.wrapAllServers)(current, serversKey, {
@@ -38,7 +52,12 @@ function runInit(opts = {}) {
                     endpoint: opts.endpoint,
                     agentName: opts.agentName,
                 });
-            const changed = JSON.stringify(current) !== JSON.stringify(next);
+            const changed = bootstrapped || JSON.stringify(current) !== JSON.stringify(next);
+            if (bootstrapped && !(next[serversKey] && Object.keys(next[serversKey]).length > 0)) {
+                // Ensure the key exists in the new file even when empty.
+                ;
+                next[serversKey] = {};
+            }
             if (opts.dryRun) {
                 clientReports.push({
                     client: client.id,
@@ -67,6 +86,7 @@ function runInit(opts = {}) {
                 status: 'patched',
                 backupPath: backupPath || undefined,
                 servers: results,
+                bootstrapped,
             });
         }
         catch (err) {
@@ -102,7 +122,7 @@ function formatReport(report, unwrap = false) {
     }
     lines.push(`Found ${report.clientsFound} MCP client(s):`);
     for (const r of report.clients) {
-        const tag = r.status === 'patched' ? '✓ patched'
+        const tag = r.status === 'patched' ? (r.bootstrapped ? '✓ bootstrapped (empty config created)' : '✓ patched')
             : r.status === 'no-changes' ? '· no changes'
                 : r.status === 'dry-run' ? '∼ dry-run'
                     : `✗ error: ${r.error}`;
@@ -111,6 +131,9 @@ function formatReport(report, unwrap = false) {
         if (r.backupPath) {
             lines.push(`    backup: ${r.backupPath}`);
         }
+        if (r.bootstrapped && r.servers.length === 0) {
+            lines.push(`    (add MCP servers in the client UI — they'll be auto-wrapped next time you run init)`);
+        }
         for (const s of r.servers) {
             const sym = s.status === 'wrapped' ? '+'
                 : s.status === 'already-wrapped' ? '='
@@ -156,11 +179,8 @@ async function runDoctor(cliVersion) {
             const servers = cfg[serversKey] || {};
             serversCount = Object.keys(servers).length;
             for (const s of Object.values(servers)) {
-                const cmdBase = (s.command || '').toLowerCase().split(/[\\/]/).pop() || '';
-                if (cmdBase === 'mcpspend' || cmdBase === 'mcpspend.cmd' || cmdBase === 'mcpspend.exe') {
-                    if ((s.args || [])[0] === 'wrap')
-                        wrappedCount++;
-                }
+                if (s && typeof s.command === 'string' && (0, clients_js_1.isAlreadyWrapped)(s))
+                    wrappedCount++;
             }
         }
         catch { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpspend/proxy",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Transparent proxy CLI for MCP servers — tracks tool calls, latency, and cost via MCPSpend.",
   "license": "MIT",
   "homepage": "https://mcpspend.com",
@@ -36,6 +36,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli.ts",
+    "test": "node --test --import tsx src/clients.test.ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },