# ⚡ SuperGateway Pro

> **Centralized MCP Gateway Daemon, Vercel-Style Live Activity Dashboard & macOS Menu Bar Suite for AI Coding Agents**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-v18%2B-green.svg)](https://nodejs.org)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-black.svg)]()

---

## 🌟 Overview

**SuperGateway Pro** is an open-source, high-performance **Model Context Protocol (MCP)** gateway, connection pooler, and real-time observability console.

Instead of every AI developer client (**Codex / ChatGPT, Claude Desktop, Antigravity, OpenCode / Codeg**) spinning up its own isolated Node.js/Python runtimes for the exact same tools (wasting **500MB – 1.5GB of RAM** and hundreds of threads), SuperGateway Pro maintains a **single, pre-warmed shared server pool** and multiplexes requests in sub-millisecond time.

```
┌───────────────────────────────────────────────────────────────┐
│     AI Clients: Codex | Claude Desktop | Antigravity | Codeg  │
└───────────────────────────────┬───────────────────────────────┘
                                │ (Lightweight stdio / SSE)
                                ▼
┌───────────────────────────────────────────────────────────────┐
│       ⚡ SuperGateway Pro Daemon (Port 8080 / <25MB RAM)       │
│  ├─ 📊 Vercel-Style Live Console (SSE Tool Stream)           │
│  ├─ ⚡ macOS Menu Bar Status Item (RAM Footprint Tracker)     │
│  └─ 📦 Universal 1-Click Config Backup & Diff Engine          │
└───────────────────────────────┬───────────────────────────────┘
                                ▼
┌───────────────────────────────────────────────────────────────┐
│   Shared Server Pool: SSH | K8s | Tabularis | Grafana | AWS   │
└───────────────────────────────────────────────────────────────┘
```

---

## ✨ Features

- 🏎️ **~83% Memory Footprint Reduction**: Consolidates 15+ duplicate MCP runtime child processes into a single shared pool (~85 MB total vs ~520 MB duplicate).
- ⚡ **Sub-5ms Execution Latency**: Persistent, pre-warmed JSON-RPC connection pooling delivers median P50 response times under **2 ms**.
- 🖤 **Vercel-Inspired Live Console**:
  - Pure black dark theme & crisp light theme with instant switcher.
  - Custom UI & monospace code font customizer (Geist, Inter, Fira Code, JetBrains Mono).
  - Real-time Server-Sent Events (SSE) tool activity feed.
  - Interactive Tool Execution Sandbox for instant JSON-RPC testing.
- 🍏 **Native macOS Menu Bar App**:
  - `⚡ MCP 🟢` status item in the macOS status bar.
  - Live RAM savings counter.
  - 1-click dashboard launcher and background process management.
- 🛡️ **Universal 1-Click Backup & Restore**:
  - Automatically snapshots configurations across Codex (`~/.codex/config.toml`), Claude Desktop (`claude_desktop_config.json`), Antigravity, and OpenCode with SHA-256 integrity manifests and interactive visual diffs.
- 🤖 **Multi-Agent Compatibility**: Works with Codex (ChatGPT), Claude Code / Claude Desktop, Google Antigravity, and OpenCode / Codeg out of the box.

---

## 📊 Benchmark Telemetry

Real benchmark metrics collected across 20 serial and 20 parallel (5 concurrent threads) read-only tool calls (`ssh-manager`, `kubernetes-readonly`, `tabularis`):

| Metric | Serial Execution (20 calls) | Parallel Execution (5 Threads) |
| :--- | :--- | :--- |
| **Total Duration** | **0.369 s** | **0.240 s** |
| **Throughput** | **54.24 calls/sec** | **83.21 calls/sec** |
| **Success Rate** | **100.0%** (20/20) | **100.0%** (20/20) |
| **P50 (Median) Latency** | **1.36 ms** | **3.10 ms** |
| **P95 Latency** | 181.28 ms | 164.89 ms |
| **Net Memory Saved** | **~435 MB** *(from ~520 MB down to ~85 MB, **83.6% reduction**)* |

---

## 🚀 Quickstart

### 1. Installation

```bash
# Clone repository
git clone https://github.com/dhomane/supergateway-pro.git
cd supergateway-pro

# Install Node and Python dependencies
npm install
pip install -r requirements.txt
```

### 2. Start the Gateway Daemon

```bash
# Start SuperGateway server on http://127.0.0.1:8080
node gateway_server.js
```

Open **[`http://localhost:8080/`](http://localhost:8080/)** in your browser to access the Vercel-style live activity dashboard.

### 3. Launch macOS Menu Bar App (Optional)

```bash
python3 menubar_cocoa.py
```

---

## 🔌 AI Agent Integration

### A. Codex (ChatGPT)
Add the proxy to `~/.codex/config.toml`:

```toml
[mcp_servers.supergateway]
command = "node"
args = ["/path/to/supergateway-pro/unified_mcp_server.js"]
enabled = true
```

### B. Claude Desktop
Add the proxy to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "supergateway": {
      "command": "node",
      "args": ["/path/to/supergateway-pro/unified_mcp_server.js"]
    }
  }
}
```

---

## 📦 Universal Backup & Restore Suite

```bash
# Create a timestamped safety backup snapshot
python3 mcp_backup_manager.py backup --tag "my_checkpoint"

# View diff between current active configs and latest backup
python3 mcp_backup_manager.py diff

# List all available backup snapshots
python3 mcp_backup_manager.py list

# Restore from latest (or specific) snapshot
python3 mcp_backup_manager.py restore
```

---

## 🧪 Running Benchmarks

```bash
python3 benchmark_mcp.py
```

---

## 📋 Checklist & Roadmap

- [x] Centralized JSON-RPC & SSE proxy router
- [x] Vercel-style real-time web console with SSE streaming
- [x] Light / Dark theme switcher with persistence
- [x] Custom UI and code font customizer
- [x] Native macOS status bar tray app (AppKit / PyObjC)
- [x] Universal 1-click config backup & diff engine
- [x] Codex & Claude Desktop stdio client proxies
- [x] Automated latency & throughput benchmark suite
- [x] Agent Skill (`SKILL.md`) integration

---

## 📄 License

MIT © SuperGateway Contributors