satgate-proxy 0.2.0 → 0.3.0

package/README.md

@@ -2,11 +2,58 @@
 
 **Budget-enforced MCP proxy — hard-cap your AI agent tool spend.**
 
-MCP servers are an open tap. Every `tools/call` costs money and there's no built-in spending limit. `satgate-proxy` sits between your MCP client (Claude Desktop, Cursor) and the server, enforcing a hard budget cap via [SatGate](https://satgate.io).
+MCP servers are an open tap. Every `tools/call` costs money and there's no built-in spending limit. `satgate-proxy` sits between your MCP client (Claude Desktop, Cursor) and the server, enforcing a hard budget cap.
 
-## Quick Start
+**Zero dependencies. Node.js built-ins only. `npx` and go.**
 
-Add to your Claude Desktop config (`claude_desktop_config.json`):
+## Quick Start — Local Mode (New in v0.3.0)
+
+No server, no API key, no account. Budget enforced in-process:
+
+```bash
+npx satgate-proxy --local --budget 5.00 \
+  --server @modelcontextprotocol/server-google-search
+```
+
+Or with a config file:
+
+```yaml
+# satgate.yaml
+server: @modelcontextprotocol/server-google-search
+budget: 5.00
+
+mcp_pricing:
+  web_search: 5
+  dalle_generate: 50
+  '*': 1
+```
+
+```bash
+npx satgate-proxy --local --config satgate.yaml
+```
+
+### Claude Desktop config (local mode):
+
+```json
+{
+  "mcpServers": {
+    "google-search": {
+      "command": "npx",
+      "args": [
+        "satgate-proxy",
+        "--local", "--budget", "5.00",
+        "--server", "@modelcontextprotocol/server-google-search"
+      ]
+    }
+  }
+}
+```
+
+No env vars needed. No accounts. Just a budget cap.
+
+## SaaS Mode (Teams & Enterprise)
+
+For server-side enforcement with L402 macaroons:
 
 ```json
 {
@@ -30,6 +77,20 @@ Get your API key at [cloud.satgate.io](https://cloud.satgate.io).
 
 ## How It Works
 
+### Local Mode
+```
+┌──────────────┐     stdio      ┌────────────────┐     stdio      ┌──────────────┐
+│ Claude       │ ──── JSON-RPC ──▶ satgate-proxy  │ ──── JSON-RPC ──▶ MCP Server  │
+│ Desktop      │ ◀── JSON-RPC ── │ (budget gate)  │ ◀── JSON-RPC ── │ (child proc) │
+│ / Cursor     │                 └────────────────┘                 └──────────────┘
+└──────────────┘                  ↑ intercepts tools/call
+                                  ↑ deducts from budget
+                                  ↑ blocks when exhausted
+```
+
+The proxy spawns your MCP server as a child process, intercepts every `tools/call`, deducts from your budget based on per-tool pricing, and blocks calls when the budget is exhausted.
+
+### SaaS Mode
 ```
 ┌──────────────┐     stdio      ┌────────────────┐     SSE/HTTP     ┌──────────────┐
 │ Claude       │ ──── JSON-RPC ──▶ satgate-proxy  │ ──── JSON-RPC ──▶ SatGate      │
@@ -44,21 +105,34 @@ Get your API key at [cloud.satgate.io](https://cloud.satgate.io).
                                                                      └──────────────┘
 ```
 
-1. Claude/Cursor launches `satgate-proxy` as a stdio MCP server
-2. The proxy connects to SatGate's SSE endpoint
-3. JSON-RPC messages from stdin are forwarded to SatGate via HTTP POST
-4. SatGate enforces your budget cap and proxies to the real MCP server
-5. Responses stream back via SSE and are written to stdout
-6. If budget is exceeded → 402 → clean error back to the client
+## Config File (`satgate.yaml`)
+
+Instead of CLI flags, you can use a config file:
+
+```yaml
+# satgate.yaml
+server: @modelcontextprotocol/server-google-search
+budget: 5.00
+
+mcp_pricing:
+  web_search: 5        # 5 cents per search
+  dalle_generate: 50   # 50 cents per image
+  '*': 1               # 1 cent default for unlisted tools
+```
+
+Pricing is in **cents**. The `'*'` wildcard sets the default cost for any tool not explicitly listed.
 
 ## CLI Flags
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--server <package>` | MCP server package to proxy (required) | — |
-| `--cap <amount>` | Budget cap in USD | — |
+| `--local` | Run in local mode (no SatGate server needed) | off |
+| `--budget <amount>` | Budget cap in USD (local mode) | unlimited |
+| `--config <path>` | Path to `satgate.yaml` config file | — |
+| `--cap <amount>` | Budget cap in USD (SaaS mode) | — |
 | `--endpoint <url>` | SatGate proxy endpoint | `https://satgate-mcp-saas.fly.dev` |
-| `--key <macaroon>` | API key (or use `SATGATE_API_KEY` env var) | — |
+| `--key <macaroon>` | API key (or `SATGATE_API_KEY` env var) | — |
 | `--verbose` | Debug logging to stderr | off |
 | `-h, --help` | Show help | — |
 
@@ -67,14 +141,13 @@ Get your API key at [cloud.satgate.io](https://cloud.satgate.io).
 MCP gives AI agents direct access to paid APIs — search, code execution, databases, you name it. There's no built-in spending limit. A runaway agent can burn through hundreds of dollars in minutes.
 
 **satgate-proxy** adds a hard cap:
-- Set `--cap 5.00` → agent can spend at most $5
-- Enforced server-side by SatGate (can't be bypassed by the client)
-- Uses L402 macaroons for cryptographic budget enforcement
+- **Local mode**: Set `--budget 5.00` → agent can spend at most $5, enforced in-process
+- **SaaS mode**: Set `--cap 5.00` → enforced server-side with L402 macaroons
 - Zero dependencies — `npx` runs it instantly
 
 ## Zero Dependencies
 
-This package uses only Node.js built-ins. No `node_modules`, no install step. `npx satgate-proxy` just works.
+This package uses only Node.js built-ins (`child_process`, `http`, `https`, `fs`). No `node_modules`, no install step. `npx satgate-proxy` just works.
 
 ## Links
 

package/bin/satgate-proxy.js

@@ -3,6 +3,7 @@
 
 const { parseArgs, printUsage } = require('../src/index.js');
 const { Bridge } = require('../src/bridge.js');
+const { LocalBridge } = require('../src/local-bridge.js');
 
 const args = parseArgs(process.argv.slice(2));
 
@@ -11,27 +12,61 @@ if (args.help) {
   process.exit(0);
 }
 
-if (!args.server) {
+// Load config file if specified
+let config = {};
+if (args.config) {
+  const { parseConfig } = require('../src/config.js');
+  try {
+    config = parseConfig(args.config);
+  } catch (err) {
+    process.stderr.write(`Error reading config file: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+// Merge config values (CLI flags take precedence)
+const server = args.server || config.server;
+if (!server) {
   process.stderr.write('Error: --server <package> is required\n\n');
   printUsage();
   process.exit(1);
 }
 
-const apiKey = args.key || process.env.SATGATE_API_KEY;
-if (!apiKey) {
-  process.stderr.write('Error: API key required via --key or SATGATE_API_KEY env var\n');
-  process.exit(1);
-}
+if (args.local) {
+  // Local mode — budget enforced in-process
+  const budgetDollars = args.budget || config.budget;
+  const budgetCents = budgetDollars ? Number(budgetDollars) * 100 : Infinity;
+  const pricing = config.mcp_pricing || {};
 
-const bridge = new Bridge({
-  server: args.server,
-  endpoint: args.endpoint,
-  apiKey,
-  cap: args.cap,
-  verbose: args.verbose,
-});
+  const bridge = new LocalBridge({
+    server,
+    budget: budgetCents,
+    pricing,
+    verbose: args.verbose,
+  });
 
-bridge.start().catch((err) => {
-  process.stderr.write(`Fatal: ${err.message}\n`);
-  process.exit(1);
-});
+  bridge.start().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+  });
+} else {
+  // SaaS mode
+  const apiKey = args.key || process.env.SATGATE_API_KEY;
+  if (!apiKey) {
+    process.stderr.write('Error: API key required via --key or SATGATE_API_KEY env var (use --local for local mode)\n');
+    process.exit(1);
+  }
+
+  const bridge = new Bridge({
+    server,
+    endpoint: args.endpoint,
+    apiKey,
+    cap: args.cap,
+    verbose: args.verbose,
+  });
+
+  bridge.start().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "satgate-proxy",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Budget-enforced MCP proxy — hard-cap your AI agent tool spend",
   "bin": {
     "satgate-proxy": "./bin/satgate-proxy.js"

package/src/config.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Parse a simple YAML-like config file.
+ * Supports top-level key: value and one level of nested maps (indented with spaces).
+ */
+function parseConfig(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  const config = {};
+  let currentMap = null;
+  let currentMapKey = null;
+
+  for (const rawLine of lines) {
+    // Strip comments
+    const line = rawLine.replace(/#.*$/, '');
+    if (line.trim() === '') continue;
+
+    const indented = line.startsWith('  ') || line.startsWith('\t');
+
+    if (indented && currentMapKey) {
+      // Nested key: value
+      const match = line.trim().match(/^['"]?([^'":\s]+)['"]?\s*:\s*(.+)$/);
+      if (match) {
+        let val = match[2].trim().replace(/^['"]|['"]$/g, '');
+        currentMap[match[1]] = isNaN(Number(val)) ? val : Number(val);
+      }
+    } else {
+      // Top-level key: value  OR  top-level key: (start of map)
+      const match = line.match(/^([a-z_]+)\s*:\s*(.*)$/i);
+      if (!match) continue;
+
+      const key = match[1].trim();
+      const val = match[2].trim();
+
+      if (val === '' || val === '{}') {
+        // Start of nested map
+        currentMap = {};
+        currentMapKey = key;
+        config[key] = currentMap;
+      } else {
+        currentMap = null;
+        currentMapKey = null;
+        // Parse value
+        let parsed = val.replace(/^['"]|['"]$/g, '');
+        config[key] = isNaN(Number(parsed)) ? parsed : Number(parsed);
+      }
+    }
+  }
+
+  return config;
+}
+
+module.exports = { parseConfig };

package/src/index.js

@@ -10,6 +10,9 @@ function parseArgs(argv) {
     key: null,
     verbose: false,
     help: false,
+    local: false,
+    budget: null,
+    config: null,
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -29,6 +32,15 @@ function parseArgs(argv) {
       case '--verbose':
         args.verbose = true;
         break;
+      case '--local':
+        args.local = true;
+        break;
+      case '--budget':
+        args.budget = argv[++i];
+        break;
+      case '--config':
+        args.config = argv[++i];
+        break;
       case '--help':
       case '-h':
         args.help = true;
@@ -43,15 +55,24 @@ function parseArgs(argv) {
 }
 
 function printUsage() {
-  process.stderr.write(`satgate-proxy v0.2.0 — Budget-enforced MCP proxy
+  process.stderr.write(`satgate-proxy v0.3.0 — Budget-enforced MCP proxy
 
 USAGE:
-  npx satgate-proxy --server <package> [options]
+
+  Local mode (zero-config, solo devs):
+    npx satgate-proxy --local --budget 5.00 --server <package>
+    npx satgate-proxy --local --config satgate.yaml
+
+  SaaS mode (teams, enterprise):
+    npx satgate-proxy --server <package> --key <macaroon> [--cap 5.00]
 
 OPTIONS:
   --server <package>   MCP server package to proxy (required)
                        e.g. @modelcontextprotocol/server-google-search
-  --cap <amount>       Budget cap in dollars (e.g. 5.00)
+  --local              Run in local mode (no SatGate server needed)
+  --budget <amount>    Budget cap in dollars for local mode (e.g. 5.00)
+  --config <path>      Path to satgate.yaml config file
+  --cap <amount>       Budget cap in dollars for SaaS mode (e.g. 5.00)
   --endpoint <url>     SatGate proxy endpoint
                        (default: ${DEFAULT_ENDPOINT})
   --key <macaroon>     API key / macaroon token
@@ -59,7 +80,16 @@ OPTIONS:
   --verbose            Enable debug logging to stderr
   -h, --help           Show this help
 
-EXAMPLE (Claude Desktop config):
+EXAMPLES:
+
+  # Local mode — budget enforced in-process, zero dependencies
+  npx satgate-proxy --local --budget 5.00 \\
+    --server @modelcontextprotocol/server-google-search
+
+  # Local mode with config file
+  npx satgate-proxy --local --config satgate.yaml
+
+  # SaaS mode (Claude Desktop config)
   {
     "mcpServers": {
       "google-search": {

package/src/local-bridge.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+class LocalBridge {
+  constructor({ server, budget, pricing, verbose }) {
+    this.server = server;
+    this.budget = budget != null ? Number(budget) : Infinity;
+    this.spent = 0;
+    this.pricing = pricing || {};  // { tool_name: cost_in_cents, '*': default }
+    this.verbose = verbose;
+    this._buffer = '';
+    this._childBuffer = '';
+    this._destroyed = false;
+  }
+
+  log(msg) {
+    if (this.verbose) process.stderr.write(`[satgate-proxy:local] ${msg}\n`);
+  }
+
+  _getToolCost(toolName) {
+    if (this.pricing[toolName] != null) return Number(this.pricing[toolName]);
+    if (this.pricing['*'] != null) return Number(this.pricing['*']);
+    return 1; // default 1 cent
+  }
+
+  async start() {
+    this.log(`Local mode — spawning: npx -y ${this.server}`);
+    this.log(`Budget: $${this.budget}`);
+
+    const child = spawn('npx', ['-y', this.server], {
+      stdio: ['pipe', 'pipe', 'inherit'],
+    });
+
+    this._child = child;
+
+    child.on('error', (err) => {
+      process.stderr.write(`[satgate-proxy:local] Failed to spawn server: ${err.message}\n`);
+      process.exit(1);
+    });
+
+    child.on('exit', (code) => {
+      this.log(`Server exited with code ${code}`);
+      if (!this._destroyed) process.exit(code || 0);
+    });
+
+    // Read from child stdout → write to our stdout
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      this._childBuffer += chunk;
+      const lines = this._childBuffer.split('\n');
+      this._childBuffer = lines.pop() || '';
+      for (const line of lines) {
+        if (line.trim()) {
+          this.log(`← ${line.substring(0, 200)}`);
+          process.stdout.write(line + '\n');
+        }
+      }
+    });
+
+    // Read from our stdin → intercept tool calls → forward to child
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      this._buffer += chunk;
+      const lines = this._buffer.split('\n');
+      this._buffer = lines.pop() || '';
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        this._handleMessage(trimmed);
+      }
+    });
+
+    process.stdin.on('end', () => {
+      this.log('stdin closed, shutting down');
+      this._cleanup();
+    });
+
+    process.stdout.on('error', (err) => {
+      if (err.code === 'EPIPE') this._cleanup();
+    });
+
+    process.on('SIGINT', () => this._cleanup());
+    process.on('SIGTERM', () => this._cleanup());
+  }
+
+  _handleMessage(jsonStr) {
+    this.log(`→ ${jsonStr.substring(0, 200)}`);
+
+    let msg;
+    try {
+      msg = JSON.parse(jsonStr);
+    } catch {
+      // Not valid JSON, forward anyway
+      this._child.stdin.write(jsonStr + '\n');
+      return;
+    }
+
+    // Intercept tools/call
+    if (msg.method === 'tools/call' && msg.params && msg.params.name) {
+      const toolName = msg.params.name;
+      const cost = this._getToolCost(toolName);
+      const remaining = this.budget - this.spent;
+
+      this.log(`Tool call: ${toolName}, cost: ${cost}¢, remaining: ${remaining.toFixed(2)}¢`);
+
+      if (cost > remaining) {
+        // Budget exhausted
+        this.log(`Budget exhausted! Need ${cost}¢ but only ${remaining.toFixed(2)}¢ left`);
+        if (msg.id != null) {
+          const errResp = JSON.stringify({
+            jsonrpc: '2.0',
+            id: msg.id,
+            error: {
+              code: -32000,
+              message: `Budget exceeded. Spent $${(this.spent / 100).toFixed(2)} of $${(this.budget / 100).toFixed(2)} cap. Tool '${toolName}' costs ${cost}¢.`,
+            },
+          });
+          process.stdout.write(errResp + '\n');
+        }
+        return;
+      }
+
+      this.spent += cost;
+      this.log(`Deducted ${cost}¢, total spent: ${this.spent}¢ / ${this.budget}¢`);
+    }
+
+    // Forward to child
+    this._child.stdin.write(jsonStr + '\n');
+  }
+
+  destroy() {
+    this._destroyed = true;
+    if (this._child) {
+      this._child.kill();
+      this._child = null;
+    }
+  }
+
+  _cleanup() {
+    this.log('Shutting down');
+    this.destroy();
+    process.exit(0);
+  }
+}
+
+module.exports = { LocalBridge };