satgate-proxy 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# satgate-proxy
+
+**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).
+
+## Quick Start
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "google-search": {
+      "command": "npx",
+      "args": [
+        "satgate-proxy",
+        "--cap", "5.00",
+        "--server", "@modelcontextprotocol/server-google-search"
+      ],
+      "env": {
+        "SATGATE_API_KEY": "your_macaroon_here"
+      }
+    }
+  }
+}
+```
+
+Get your API key at [cloud.satgate.io](https://cloud.satgate.io).
+
+## How It Works
+
+```
+┌──────────────┐     stdio      ┌────────────────┐     SSE/HTTP     ┌──────────────┐
+│ Claude       │ ──── JSON-RPC ──▶ satgate-proxy  │ ──── JSON-RPC ──▶ SatGate      │
+│ Desktop      │ ◀── JSON-RPC ── │ (this package) │ ◀── JSON-RPC ── │ MCP Proxy    │
+│ / Cursor     │                 └────────────────┘                  │ + Budget     │
+└──────────────┘                                                     │ Enforcement  │
+                                                                     └──────┬───────┘
+                                                                            │
+                                                                     ┌──────▼───────┐
+                                                                     │ MCP Server   │
+                                                                     │ (hosted)     │
+                                                                     └──────────────┘
+```
+
+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
+
+## CLI Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--server <package>` | MCP server package to proxy (required) | — |
+| `--cap <amount>` | Budget cap in USD | — |
+| `--endpoint <url>` | SatGate proxy endpoint | `https://satgate-mcp-saas.fly.dev` |
+| `--key <macaroon>` | API key (or use `SATGATE_API_KEY` env var) | — |
+| `--verbose` | Debug logging to stderr | off |
+| `-h, --help` | Show help | — |
+
+## Why?
+
+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
+- 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.
+
+## Links
+
+- 🌐 [satgate.io](https://satgate.io) — Homepage
+- ☁️ [cloud.satgate.io](https://cloud.satgate.io) — Dashboard & API keys
+- 📦 [GitHub](https://github.com/SatGate-io/satgate-proxy) — Source code
+- 📋 [MCP Specification](https://modelcontextprotocol.io) — Model Context Protocol
+
+## License
+
+MIT

package/bin/satgate-proxy.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+'use strict';
+
+const { parseArgs, printUsage } = require('../src/index.js');
+const { Bridge } = require('../src/bridge.js');
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) {
+  printUsage();
+  process.exit(0);
+}
+
+if (!args.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);
+}
+
+const bridge = new Bridge({
+  server: args.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

@@ -0,0 +1,20 @@
+{
+  "name": "satgate-proxy",
+  "version": "0.1.0",
+  "description": "Budget-enforced MCP proxy — hard-cap your AI agent tool spend",
+  "bin": {
+    "satgate-proxy": "./bin/satgate-proxy.js"
+  },
+  "keywords": ["mcp", "ai", "agent", "budget", "l402", "satgate", "proxy", "claude", "cursor"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SatGate-io/satgate-proxy"
+  },
+  "homepage": "https://satgate.io",
+  "author": "SatGate Inc.",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": ["bin/", "src/", "README.md"]
+}

package/src/bridge.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+class Bridge {
+  constructor({ server, endpoint, apiKey, cap, verbose }) {
+    this.server = server;
+    this.endpoint = endpoint;
+    this.apiKey = apiKey;
+    this.cap = cap;
+    this.verbose = verbose;
+    this._buffer = '';
+    this._pendingRequests = new Map();
+    this._sseBuffer = '';
+  }
+
+  log(msg) {
+    if (this.verbose) process.stderr.write(`[satgate-proxy] ${msg}\n`);
+  }
+
+  async start() {
+    this.log(`Bridging stdio ↔ ${this.endpoint}`);
+    this.log(`Server: ${this.server}`);
+    if (this.cap) this.log(`Budget cap: $${this.cap}`);
+
+    // Connect SSE session to SatGate
+    this._connectSSE();
+
+    // Read JSON-RPC from stdin and forward via HTTP POST
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => this._onStdinData(chunk));
+    process.stdin.on('end', () => {
+      this.log('stdin closed, shutting down');
+      this._cleanup();
+    });
+
+    // Handle stdout errors (EPIPE when reader disconnects)
+    process.stdout.on('error', (err) => {
+      if (err.code === 'EPIPE') {
+        this.log('stdout pipe closed, shutting down');
+        this._cleanup();
+      }
+    });
+
+    // Graceful shutdown
+    process.on('SIGINT', () => this._cleanup());
+    process.on('SIGTERM', () => this._cleanup());
+    process.on('unhandledRejection', (err) => {
+      this.log(`Unhandled rejection: ${err.message}`);
+    });
+  }
+
+  _buildUrl(path) {
+    const base = this.endpoint.replace(/\/$/, '');
+    return `${base}${path}`;
+  }
+
+  _buildHeaders() {
+    const headers = {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.apiKey}`,
+    };
+    if (this.cap) {
+      headers['X-SatGate-Cap'] = this.cap;
+    }
+    headers['X-SatGate-Server'] = this.server;
+    return headers;
+  }
+
+  _connectSSE() {
+    const url = this._buildUrl('/sse');
+    this.log(`Connecting SSE: ${url}`);
+
+    const parsedUrl = new URL(url);
+    const mod = parsedUrl.protocol === 'https:' ? https : http;
+    const headers = this._buildHeaders();
+    headers['Accept'] = 'text/event-stream';
+
+    const req = mod.get(url, { headers }, (res) => {
+      if (res.statusCode !== 200) {
+        process.stderr.write(`SSE connection failed: HTTP ${res.statusCode}\n`);
+        let body = '';
+        res.on('data', (d) => body += d);
+        res.on('end', () => {
+          if (body) process.stderr.write(`Response: ${body}\n`);
+          process.exit(1);
+        });
+        return;
+      }
+
+      this.log('SSE connected');
+      this._sseRes = res;
+      res.setEncoding('utf8');
+
+      res.on('data', (chunk) => this._onSSEData(chunk));
+      res.on('end', () => {
+        this.log('SSE connection closed');
+        process.exit(0);
+      });
+      res.on('error', (err) => {
+        process.stderr.write(`SSE error: ${err.message}\n`);
+        process.exit(1);
+      });
+    });
+
+    req.on('error', (err) => {
+      process.stderr.write(`SSE connection error: ${err.message}\n`);
+      process.exit(1);
+    });
+
+    this._sseReq = req;
+  }
+
+  _onSSEData(chunk) {
+    this._sseBuffer += chunk;
+    const lines = this._sseBuffer.split('\n');
+    // Keep incomplete last line in buffer
+    this._sseBuffer = lines.pop() || '';
+
+    let eventType = 'message';
+    let dataLines = [];
+
+    for (const line of lines) {
+      if (line.startsWith('event:')) {
+        eventType = line.slice(6).trim();
+      } else if (line.startsWith('data:')) {
+        dataLines.push(line.slice(5).trim());
+      } else if (line === '') {
+        // End of event
+        if (dataLines.length > 0) {
+          const data = dataLines.join('\n');
+          this._handleSSEEvent(eventType, data);
+        }
+        eventType = 'message';
+        dataLines = [];
+      }
+    }
+  }
+
+  _handleSSEEvent(eventType, data) {
+    this.log(`SSE event: ${eventType}`);
+
+    if (eventType === 'endpoint') {
+      // SatGate sends the POST endpoint URL via SSE
+      this._postEndpoint = data.startsWith('http') ? data : this._buildUrl(data);
+      this.log(`POST endpoint: ${this._postEndpoint}`);
+      // Flush any queued messages
+      this._flushQueue();
+      return;
+    }
+
+    if (eventType === 'message') {
+      this.log(`← ${data.substring(0, 200)}`);
+      // Write JSON-RPC response to stdout
+      process.stdout.write(data + '\n');
+    }
+  }
+
+  _onStdinData(chunk) {
+    this._buffer += chunk;
+    // Split on newlines — MCP uses line-delimited JSON
+    const lines = this._buffer.split('\n');
+    this._buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      this._sendMessage(trimmed);
+    }
+  }
+
+  _sendMessage(jsonStr) {
+    this.log(`→ ${jsonStr.substring(0, 200)}`);
+
+    if (!this._postEndpoint) {
+      this.log('POST endpoint not yet known, queuing');
+      if (!this._queue) this._queue = [];
+      this._queue.push(jsonStr);
+      return;
+    }
+
+    this._postToEndpoint(jsonStr);
+  }
+
+  _flushQueue() {
+    if (!this._queue || this._queue.length === 0) return;
+    this.log(`Flushing ${this._queue.length} queued messages`);
+    for (const msg of this._queue) {
+      this._postToEndpoint(msg);
+    }
+    this._queue = [];
+  }
+
+  _postToEndpoint(jsonStr) {
+    const url = new URL(this._postEndpoint);
+    const mod = url.protocol === 'https:' ? https : http;
+
+    const body = Buffer.from(jsonStr, 'utf8');
+    const headers = this._buildHeaders();
+    headers['Content-Length'] = body.length;
+
+    const opts = {
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers,
+    };
+
+    const req = mod.request(opts, (res) => {
+      let respBody = '';
+      res.setEncoding('utf8');
+      res.on('data', (d) => respBody += d);
+      res.on('end', () => {
+        if (res.statusCode === 402) {
+          // Budget exceeded — synthesize JSON-RPC error
+          this.log('Budget exceeded (402)');
+          try {
+            const parsed = JSON.parse(jsonStr);
+            if (parsed.id != null) {
+              const errResp = JSON.stringify({
+                jsonrpc: '2.0',
+                id: parsed.id,
+                error: {
+                  code: -32000,
+                  message: 'Budget exceeded. Your SatGate spending cap has been reached.',
+                },
+              });
+              process.stdout.write(errResp + '\n');
+            }
+          } catch (_) {}
+        } else if (res.statusCode >= 400) {
+          this.log(`POST error ${res.statusCode}: ${respBody}`);
+        } else {
+          this.log(`POST OK ${res.statusCode}`);
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      process.stderr.write(`POST error: ${err.message}\n`);
+    });
+
+    req.write(body);
+    req.end();
+  }
+
+  _cleanup() {
+    this.log('Shutting down');
+    if (this._sseReq) this._sseReq.destroy();
+    process.exit(0);
+  }
+}
+
+module.exports = { Bridge };

package/src/index.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const DEFAULT_ENDPOINT = 'https://satgate-mcp-saas.fly.dev';
+
+function parseArgs(argv) {
+  const args = {
+    server: null,
+    cap: null,
+    endpoint: DEFAULT_ENDPOINT,
+    key: null,
+    verbose: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--server':
+        args.server = argv[++i];
+        break;
+      case '--cap':
+        args.cap = argv[++i];
+        break;
+      case '--endpoint':
+        args.endpoint = argv[++i];
+        break;
+      case '--key':
+        args.key = argv[++i];
+        break;
+      case '--verbose':
+        args.verbose = true;
+        break;
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+      default:
+        process.stderr.write(`Unknown flag: ${argv[i]}\n`);
+        args.help = true;
+    }
+  }
+
+  return args;
+}
+
+function printUsage() {
+  process.stderr.write(`satgate-proxy v0.1.0 — Budget-enforced MCP proxy
+
+USAGE:
+  npx satgate-proxy --server <package> [options]
+
+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)
+  --endpoint <url>     SatGate proxy endpoint
+                       (default: ${DEFAULT_ENDPOINT})
+  --key <macaroon>     API key / macaroon token
+                       (also reads SATGATE_API_KEY env var)
+  --verbose            Enable debug logging to stderr
+  -h, --help           Show this help
+
+EXAMPLE (Claude Desktop config):
+  {
+    "mcpServers": {
+      "google-search": {
+        "command": "npx",
+        "args": ["satgate-proxy", "--cap", "5.00",
+                 "--server", "@modelcontextprotocol/server-google-search"],
+        "env": { "SATGATE_API_KEY": "your_macaroon_here" }
+      }
+    }
+  }
+
+More info: https://satgate.io
+`);
+}
+
+module.exports = { parseArgs, printUsage, DEFAULT_ENDPOINT };