mcp-superassistant-proxy

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

# 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

# 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

{
  "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:

   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:

   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 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.