@leeroy/mcp-superassistant-proxy/README.md

A bulletproof proxy server for MCP (Model Context Protocol) that aggregates multiple MCP servers with comprehensive memory leak prevention and reliable HTTP/SSE transport

# MCP SuperAssistant Proxy

A **bulletproof proxy server** for MCP (Model Context Protocol) that aggregates multiple MCP servers with comprehensive memory leak prevention and reliable HTTP/SSE transport. Perfect for Chrome extensions and web applications.

**🚀 Features:**
- **🛡️ Memory-Safe** - Comprehensive memory leak prevention and automatic cleanup
- **⚡ Bulletproof** - Robust error handling and resource management
- **🌐 Multi-Transport** - HTTP and SSE support for maximum compatibility
- **🔧 Cross-Platform** - Works on macOS, Linux, and Windows
- **📊 Data Flow Optimization** - Data passes through without being cached in memory
- **🎯 Chrome Extension Ready** - Optimized for browser extension communication

## Installation & Usage

### Quick Start

```bash
# Install globally for easy access
npm install -g @leeroy/mcp-superassistant-proxy

# Or run directly with npx
npx -y @leeroy/mcp-superassistant-proxy@latest --config config.json --port 3006
```

### Recommended Setup

```bash
# Create config directory
mkdir -p ~/.mcp-superassistant

# Create your config file
echo '{"mcpServers": {}}' > ~/.mcp-superassistant/config.json

# Run the proxy
mcp-superassistant-proxy --config ~/.mcp-superassistant/config.json --port 3006
```

### CLI Options

- `--config, -c <path>`: **(required)** Path to a JSON configuration file (see below)
- `--port <number>`: Port to run the HTTP server on (default: `3006`)
- `--logLevel <info|none>`: Set logging level (default: `info`)
- `--timeout <ms>`: Connection timeout in milliseconds (default: `30000`)

### Available Endpoints

When running, the proxy exposes:
- **Modern HTTP**: `http://localhost:<port>/mcp` - Streamable HTTP transport (recommended)
- **Legacy SSE**: `http://localhost:<port>/sse` - Server-Sent Events transport
- **Health Check**: `http://localhost:<port>/health` - Returns server status

## Configuration File

The configuration file is a JSON file specifying which MCP servers to connect to. Each server can be either a stdio-based server (run as a subprocess) or a remote HTTP/SSE server.

### Example `config.json`

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "<your_notion_token_here>"
      }
    },
    "remote-server": {
      "url": "https://your-remote-mcp-server.com/mcp"
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    }
  }
}
```

### Configuration Options

- **For stdio servers**: Use `command`, `args`, and optionally `env`
- **For remote servers**: Use `url` pointing to the MCP endpoint
- Each key under `mcpServers` is a unique name for the server

## Memory Safety & Reliability

This proxy is designed to be **bulletproof** with comprehensive memory leak prevention:

### 🛡️ Memory Management
- **Automatic session cleanup** - Stale sessions cleaned every 2 minutes
- **Data flow optimization** - Data passes through without being cached in memory
- **Resource tracking** - All intervals, timeouts, and connections tracked
- **Graceful shutdown** - Complete cleanup on exit
- **Reference clearing** - Explicit garbage collection hints

### ⚡ Reliability Features
- **Connection stability** - Robust error handling and recovery
- **Timeout protection** - All operations have timeouts to prevent hanging
- **Transport fallback** - Automatic fallback from modern to legacy transports
- **Process monitoring** - Automatic cleanup of disconnected child processes
- **Error boundaries** - Isolated error handling prevents cascading failures

### 📊 Data Flow Optimization
- **Zero data caching** - Large data objects pass through without being stored
- **Immediate cleanup** - References cleared immediately after data transfer
- **Memory monitoring** - Proactive memory leak prevention
- **Performance tracking** - Built-in performance monitoring

## Transport Compatibility

The proxy provides **automatic backwards compatibility** between different MCP transport versions:

### Client-Side Compatibility
- **Modern clients** → Connect to `/mcp` for Streamable HTTP transport
- **Legacy clients** → Connect to `/sse` for Server-Sent Events transport
- **Automatic fallback** → Clients can try modern first, fall back to legacy

### Server-Side Compatibility
- **Remote HTTP servers** → Tries Streamable HTTP first, falls back to SSE
- **Stdio servers** → Native subprocess communication
- **Mixed environments** → Seamlessly handles different server types

## Quick Example

1. **Create a config file**:
   ```bash
   mkdir -p ~/.mcp-superassistant
   cat > ~/.mcp-superassistant/config.json << 'EOF'
   {
     "mcpServers": {
       "filesystem": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
       }
     }
   }
   EOF
   ```

2. **Run the proxy**:
   ```bash
   npx -y @leeroy/mcp-superassistant-proxy@latest --config ~/.mcp-superassistant/config.json --port 3006
   ```

3. **Connect your client** to `http://localhost:3006/mcp`

## Why MCP?

[Model Context Protocol](https://spec.modelcontextprotocol.io/) standardizes how AI tools exchange data. This proxy allows you to:

- **Aggregate multiple MCP servers** behind a single endpoint
- **Bridge different transports** (stdio ↔ HTTP/SSE)
- **Ensure reliability** with bulletproof memory management
- **Scale safely** with built-in monitoring and limits

## Advanced Features

### Automatic Protocol Detection
- **JSON-RPC version** automatically derived from requests
- **Transport negotiation** between client and server
- **Backwards compatibility** maintained across MCP versions

### Production Ready
- **Memory leak prevention** - Comprehensive resource management
- **Error isolation** - Failures don't cascade between servers
- **Performance monitoring** - Built-in metrics and logging
- **Graceful degradation** - Continues working when individual servers fail

### Chrome Extension Optimized
- **Content script proxy pattern** - Reliable browser networking
- **Zero data retention** - Large data flows through without caching
- **Timeout handling** - No hanging requests
- **Reference cleanup** - Explicit garbage collection

---

## Version History

### v0.1.0 - Memory Safety Release
- ✅ **Comprehensive memory leak fixes**
- ✅ **WebSocket removal** (HTTP/SSE only)
- ✅ **Data flow optimization** - No data caching/retention
- ✅ **Bulletproof resource management**
- ✅ **Chrome extension reliability improvements**

---

For more details, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).