@mcpspend/proxy 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @mcpspend/proxy
+
+Transparent observability proxy for MCP (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.
+
+Fire-and-forget: the proxy never blocks the MCP wire — if the MCPSpend API is unreachable, your agent keeps working.
+
+## Install
+
+```sh
+npm install -g @mcpspend/proxy
+```
+
+## Quick start
+
+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
+   ```
+
+## Usage with Claude Desktop / Claude Code
+
+Wherever you have an MCP server configured, prepend `mcpspend wrap --` to the command:
+
+**Before:**
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-filesystem", "/Users/me"]
+    }
+  }
+}
+```
+
+**After:**
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "mcpspend",
+      "args": ["wrap", "--key", "mcps_live_xxx", "--", "npx", "@modelcontextprotocol/server-filesystem", "/Users/me"]
+    }
+  }
+}
+```
+
+## Configuration
+
+CLI flags, environment variables, and `~/.mcpspend/config.json` are merged in that order (CLI wins).
+
+| Setting | Flag | Env var | Config key |
+|---|---|---|---|
+| API key | `--key` | `MCPSPEND_API_KEY` | `apiKey` |
+| API endpoint | `--endpoint` | `MCPSPEND_ENDPOINT` | `endpoint` |
+| Project ID | `--project` | `MCPSPEND_PROJECT_ID` | `projectId` |
+| Agent name | `--agent` | `MCPSPEND_AGENT_NAME` | `agentName` |
+| Disable tracking | `--disable` | `MCPSPEND_DISABLED=1` | `disabled: true` |
+
+## Privacy
+
+The proxy reports:
+- Tool name (e.g. `read_file`)
+- Server name (e.g. `filesystem`)
+- Latency, success, error codes
+- Approximate input/output sizes (tokens, derived from JSON length)
+
+It does **not** send the actual tool arguments or response bodies to MCPSpend.
+
+## Support
+
+[support@mcpspend.com](mailto:support@mcpspend.com) · [mcpspend.com](https://mcpspend.com)
+
+© NewRzs SRL · CUI RO48756557

package/dist/cli.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+"use strict";
+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 HELP = `mcpspend — observability proxy for MCP servers (v${VERSION})
+
+USAGE
+  mcpspend wrap [options] -- <command> [args...]
+  mcpspend config set <key> <value>
+  mcpspend config show
+  mcpspend --version
+  mcpspend --help
+
+WRAP OPTIONS
+  --key <value>            API key (overrides config + MCPSPEND_API_KEY)
+  --endpoint <url>         API endpoint (default: https://api.mcpspend.com)
+  --project <id>           Attribute calls to this project
+  --agent <name>           Agent name reported in dashboards
+  --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
+
+  # Configure once, then run many wrapped servers without flags
+  mcpspend config set apiKey mcps_live_xxx
+  mcpspend wrap -- npx @modelcontextprotocol/server-github
+
+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: [] };
+    if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+        result.command = 'help';
+        return result;
+    }
+    if (argv[0] === '-v' || argv[0] === '--version') {
+        result.command = 'version';
+        return result;
+    }
+    const cmd = argv[0];
+    if (cmd === 'wrap') {
+        result.command = 'wrap';
+        let i = 1;
+        while (i < argv.length) {
+            const a = argv[i];
+            if (a === '--') {
+                i++;
+                break;
+            }
+            const next = argv[i + 1];
+            switch (a) {
+                case '--key':
+                    result.wrapOpts.apiKey = next;
+                    i += 2;
+                    break;
+                case '--endpoint':
+                    result.wrapOpts.endpoint = next;
+                    i += 2;
+                    break;
+                case '--project':
+                    result.wrapOpts.projectId = next;
+                    i += 2;
+                    break;
+                case '--agent':
+                    result.wrapOpts.agentName = next;
+                    i += 2;
+                    break;
+                case '--model':
+                    result.wrapOpts.model = next;
+                    i += 2;
+                    break;
+                case '--disable':
+                    result.wrapOpts.disabled = true;
+                    i += 1;
+                    break;
+                default:
+                    process.stderr.write(`mcpspend: unknown option ${a}\n`);
+                    process.exit(2);
+            }
+        }
+        if (i >= argv.length) {
+            process.stderr.write('mcpspend: missing command to wrap. Use: mcpspend wrap [options] -- <command> [args...]\n');
+            process.exit(2);
+        }
+        result.childCommand = argv[i];
+        result.childArgs = argv.slice(i + 1);
+        return result;
+    }
+    if (cmd === 'config') {
+        result.command = 'config';
+        const action = argv[1];
+        if (action === 'show') {
+            result.configAction = 'show';
+            return result;
+        }
+        if (action === 'set') {
+            result.configAction = 'set';
+            result.configKey = argv[2];
+            result.configValue = argv[3];
+            if (!result.configKey || result.configValue === undefined) {
+                process.stderr.write('mcpspend: usage: mcpspend config set <key> <value>\n');
+                process.exit(2);
+            }
+            return result;
+        }
+        process.stderr.write(`mcpspend: unknown config action ${action}\n`);
+        process.exit(2);
+    }
+    process.stderr.write(`mcpspend: unknown command ${cmd}\n`);
+    process.exit(2);
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.command === 'help') {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (parsed.command === 'version') {
+        process.stdout.write(`${VERSION}\n`);
+        return;
+    }
+    if (parsed.command === 'config') {
+        if (parsed.configAction === 'show') {
+            const cfg = (0, config_js_1.loadConfig)();
+            const masked = cfg.apiKey ? cfg.apiKey.slice(0, 12) + '…' : '(not set)';
+            process.stdout.write(JSON.stringify({ ...cfg, apiKey: masked }, null, 2) + '\n');
+            return;
+        }
+        if (parsed.configAction === 'set') {
+            const k = parsed.configKey;
+            const v = parsed.configValue;
+            const allowed = ['apiKey', 'endpoint', 'projectId', 'agentName', 'disabled'];
+            if (!allowed.includes(k)) {
+                process.stderr.write(`mcpspend: unknown config key ${k}. Allowed: ${allowed.join(', ')}\n`);
+                process.exit(2);
+            }
+            const updates = {};
+            updates[k] = k === 'disabled' ? (v === 'true' || v === '1') : v;
+            const path = (0, config_js_1.saveConfig)(updates);
+            process.stdout.write(`Saved ${k} → ${path}\n`);
+            return;
+        }
+    }
+    if (parsed.command === 'wrap') {
+        const cfg = (0, config_js_1.loadConfig)(parsed.wrapOpts);
+        const code = await (0, proxy_js_1.runProxy)({
+            command: parsed.childCommand,
+            args: parsed.childArgs,
+            config: cfg,
+            model: parsed.wrapOpts.model || process.env.MCPSPEND_MODEL || 'mcp-stdio',
+        });
+        process.exit(code);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`mcpspend: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/config.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const DEFAULT_ENDPOINT = 'https://api.mcpspend.com';
+function configPath() {
+    return process.env.MCPSPEND_CONFIG || (0, node_path_1.join)((0, node_os_1.homedir)(), '.mcpspend', 'config.json');
+}
+function fileConfig() {
+    const p = configPath();
+    if (!(0, node_fs_1.existsSync)(p))
+        return {};
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(p, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function loadConfig(cliOverrides = {}) {
+    const file = fileConfig();
+    const apiKey = cliOverrides.apiKey ||
+        process.env.MCPSPEND_API_KEY ||
+        file.apiKey;
+    return {
+        apiKey,
+        endpoint: cliOverrides.endpoint || process.env.MCPSPEND_ENDPOINT || file.endpoint || DEFAULT_ENDPOINT,
+        projectId: cliOverrides.projectId || process.env.MCPSPEND_PROJECT_ID || file.projectId,
+        agentName: cliOverrides.agentName || process.env.MCPSPEND_AGENT_NAME || file.agentName,
+        disabled: cliOverrides.disabled || process.env.MCPSPEND_DISABLED === '1' || file.disabled,
+    };
+}
+function saveConfig(updates) {
+    const p = configPath();
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    const current = fileConfig();
+    const next = { ...current, ...updates };
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify(next, null, 2), { mode: 0o600 });
+    return p;
+}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });

package/dist/ingest.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ingest = void 0;
+const MAX_BATCH = 50;
+const FLUSH_INTERVAL_MS = 1000;
+const MAX_QUEUE = 1000; // drop events if we exceed this (protects memory if API is down)
+class Ingest {
+    cfg;
+    queue = [];
+    timer = null;
+    inflight = false;
+    dropped = 0;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    enqueue(event) {
+        if (this.cfg.disabled || !this.cfg.apiKey)
+            return;
+        if (this.queue.length >= MAX_QUEUE) {
+            this.dropped++;
+            return;
+        }
+        this.queue.push({
+            ...event,
+            projectId: event.projectId || this.cfg.projectId,
+        });
+        this.scheduleFlush();
+    }
+    scheduleFlush() {
+        if (this.timer)
+            return;
+        if (this.queue.length >= MAX_BATCH) {
+            void this.flush();
+            return;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+    }
+    async flush() {
+        if (this.inflight || this.queue.length === 0)
+            return;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const batch = this.queue.splice(0, MAX_BATCH);
+        this.inflight = true;
+        try {
+            const res = await fetch(`${this.cfg.endpoint}/api/ingest`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.cfg.apiKey}`,
+                },
+                body: JSON.stringify(batch),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!res.ok) {
+                // 4xx: don't requeue (bad data / unauthorized) — log and drop
+                // 5xx: requeue once at the front for retry
+                if (res.status >= 500 && this.queue.length + batch.length <= MAX_QUEUE) {
+                    this.queue.unshift(...batch);
+                }
+                // Avoid logging high-volume errors to stdout (would pollute MCP protocol stream)
+                // Errors go to stderr; the parent process can choose to surface them.
+                process.stderr.write(`[mcpspend] ingest HTTP ${res.status}\n`);
+            }
+        }
+        catch (err) {
+            // Network error — requeue if there's room
+            if (this.queue.length + batch.length <= MAX_QUEUE) {
+                this.queue.unshift(...batch);
+            }
+            process.stderr.write(`[mcpspend] ingest failed: ${err instanceof Error ? err.message : 'unknown'}\n`);
+        }
+        finally {
+            this.inflight = false;
+            if (this.queue.length > 0)
+                this.scheduleFlush();
+        }
+    }
+    async shutdown() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        while (this.queue.length > 0 && !this.inflight) {
+            // try one final flush
+            await this.flush();
+        }
+        if (this.dropped > 0) {
+            process.stderr.write(`[mcpspend] dropped ${this.dropped} events (queue overflow)\n`);
+        }
+    }
+}
+exports.Ingest = Ingest;

package/dist/proxy.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runProxy = runProxy;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const ingest_js_1 = require("./ingest.js");
+// Token estimation: ~4 chars per token for English/JSON content.
+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 extractServerName(command, args) {
+    // Best-effort: pick the most descriptive token from the command line.
+    // Examples:
+    //   npx @modelcontextprotocol/server-filesystem /path  →  "filesystem"
+    //   node ./my-mcp-server.js                            →  "my-mcp-server"
+    //   /usr/bin/uvx mcp-server-fetch                       →  "mcp-server-fetch"
+    const tokens = [command, ...args];
+    for (const t of tokens) {
+        const m = t.match(/(?:server-|mcp-server-)([a-z0-9-]+)/i);
+        if (m)
+            return m[1];
+    }
+    for (const t of tokens) {
+        const m = t.match(/([a-z0-9-]+)-mcp-server/i);
+        if (m)
+            return m[1];
+    }
+    // Fallback: last non-flag arg's basename without extension
+    const lastArg = [...tokens].reverse().find((t) => !t.startsWith('-'));
+    if (lastArg) {
+        return lastArg.split(/[\\/]/).pop().replace(/\.[^.]+$/, '');
+    }
+    return 'mcp';
+}
+async function runProxy(opts) {
+    const { command, args, config, model } = opts;
+    const serverName = extractServerName(command, args);
+    const sessionId = (0, node_crypto_1.randomUUID)();
+    const ingest = new ingest_js_1.Ingest(config);
+    if (!config.apiKey) {
+        process.stderr.write('[mcpspend] no API key configured — running in passthrough mode (no tracking)\n');
+    }
+    const child = (0, node_child_process_1.spawn)(command, args, {
+        stdio: ['pipe', 'pipe', 'inherit'],
+        env: process.env,
+    });
+    const pending = new Map();
+    function handleClientMessage(line) {
+        if (!line.trim())
+            return;
+        try {
+            const msg = JSON.parse(line);
+            if (msg.method === 'tools/call' && msg.id != null && msg.params && typeof msg.params === 'object') {
+                const params = msg.params;
+                if (params.name) {
+                    pending.set(msg.id, {
+                        toolName: params.name,
+                        serverName,
+                        startedAt: Date.now(),
+                        inputTokens: estimateTokens(params.arguments),
+                    });
+                }
+            }
+        }
+        catch {
+            // not JSON or partial — ignore, just forward
+        }
+    }
+    function handleServerMessage(line) {
+        if (!line.trim())
+            return;
+        try {
+            const msg = JSON.parse(line);
+            if (msg.id != null && (msg.result !== undefined || msg.error)) {
+                const call = pending.get(msg.id);
+                if (call) {
+                    pending.delete(msg.id);
+                    const latencyMs = Date.now() - call.startedAt;
+                    const success = !msg.error;
+                    ingest.enqueue({
+                        serverName: call.serverName,
+                        toolName: call.toolName,
+                        model,
+                        inputTokens: call.inputTokens,
+                        outputTokens: estimateTokens(msg.result),
+                        latencyMs,
+                        success,
+                        errorCode: msg.error ? String(msg.error.code) : undefined,
+                        calledAt: new Date(call.startedAt).toISOString(),
+                        sessionId,
+                    });
+                }
+            }
+        }
+        catch {
+            // not JSON or partial — ignore
+        }
+    }
+    function pipeWithInspect(src, dst, onLine) {
+        let buf = '';
+        src.on('data', (chunk) => {
+            const text = chunk.toString('utf8');
+            // Pass through immediately — never block the MCP wire
+            dst.write(chunk);
+            buf += text;
+            let idx;
+            while ((idx = buf.indexOf('\n')) !== -1) {
+                const line = buf.slice(0, idx);
+                buf = buf.slice(idx + 1);
+                onLine(line);
+            }
+        });
+        src.on('end', () => {
+            if (buf)
+                onLine(buf);
+        });
+    }
+    pipeWithInspect(process.stdin, child.stdin, handleClientMessage);
+    pipeWithInspect(child.stdout, process.stdout, handleServerMessage);
+    return new Promise((resolve) => {
+        child.on('exit', async (code, signal) => {
+            // Final flush before exit
+            await ingest.shutdown();
+            resolve(code ?? (signal ? 128 : 0));
+        });
+        child.on('error', (err) => {
+            process.stderr.write(`[mcpspend] failed to spawn ${command}: ${err.message}\n`);
+            resolve(127);
+        });
+        // Propagate termination signals to the child so MCP servers shut down cleanly
+        const propagate = (sig) => {
+            if (!child.killed)
+                child.kill(sig);
+        };
+        process.on('SIGINT', () => propagate('SIGINT'));
+        process.on('SIGTERM', () => propagate('SIGTERM'));
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mcpspend/proxy",
+  "version": "0.1.0",
+  "description": "Transparent proxy CLI for MCP servers — tracks tool calls, latency, and cost via MCPSpend.",
+  "license": "MIT",
+  "homepage": "https://mcpspend.com",
+  "bugs": "mailto:support@mcpspend.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andreisirbu91-lab/MCPSpend.git",
+    "directory": "packages/proxy"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "observability",
+    "cost-tracking",
+    "ai",
+    "proxy"
+  ],
+  "bin": {
+    "mcpspend": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.10",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}