scripts/SSE_BRIDGE_EXPERIMENTAL.md

# Guardian Forge SSE Bridge 🧪

This bridge includes support for Server-Sent Events (SSE) to enable bidirectional communication and future auto-update capabilities.

## 🆕 What's Different?

**Standard Bridge (`guardian-forge-mcp-bridge.js`):**
- ✅ Simple, stable, tested
- ✅ Works with all MCP clients
- ❌ No SSE support

**SSE Bridge (`guardian-forge-mcp-bridge-sse.js`):**
- ⚡ SSE support for notifications
- ✅ Auto-reconnect on connection loss
- ✅ Bidirectional communication (client ↔ server)
- ✅ Better long-term connection stability
- ⚠️ Slightly more complex

## 🎯 Current Behavior

**Tool Updates:**
1. You request a new tool in your MCP client
2. You approve it in the dashboard at `/admin`
3. Server sends `notifications/tools/list_changed` → Bridge forwards to client
4. **Currently: You still need to restart Claude Desktop/Code to see the new tool**

**Why restart is needed:** The MCP client (Claude Desktop/Code) doesn't yet auto-refresh when receiving `notifications/tools/list_changed`. The bridge correctly forwards the notification, but the client-side implementation isn't handling it yet.

**Future:** When MCP clients fully implement notification handling, new tools will appear automatically without restart.

## 📥 Setup

### Step 1: Configure MCP Client

Get your API key from the Guardian Forge dashboard Settings tab, then configure your MCP client:

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": ["/absolute/path/to/guardian-forge-mcp-bridge-sse.js"],
      "env": {
        "GUARDIAN_FORGE_API_KEY": "gf_your_key_here"
      }
    }
  }
}
```

**Claude Code** (`~/.claude.json` on macOS/Linux, `C:\Users\<username>\.claude.json` on Windows):
```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": ["/absolute/path/to/guardian-forge-mcp-bridge-sse.js"],
      "env": {
        "GUARDIAN_FORGE_API_KEY": "gf_your_key_here"
      }
    }
  }
}
```

**Windows Example (Claude Desktop):**
```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\Downloads\\guardian-forge-mcp-bridge-sse.js"],
      "env": {
        "GUARDIAN_FORGE_API_KEY": "gf_your_key_here"
      }
    }
  }
}
```

**Windows Example (Claude Code - `C:\Users\<username>\.claude.json`):**
```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": ["C:\\Users\\giova\\Downloads\\guardian-forge-mcp-bridge-sse.js"],
      "env": {
        "GUARDIAN_FORGE_API_KEY": "gf_your_key_here"
      }
    }
  }
}
```

### Step 2: Restart Your MCP Client

Watch the logs for:
```
[Guardian Forge Bridge SSE] Bridge started, connecting to Guardian Forge...
[Guardian Forge Bridge SSE] Client initialized - starting SSE connection for notifications
[Guardian Forge Bridge SSE] Connecting to SSE endpoint for notifications...
[Guardian Forge Bridge SSE] SSE connection established - listening for notifications
```

## 🔍 How It Works

### Architecture

```
┌──────────────┐
│ MCP Client   │
│ (Claude Code)│
└──────┬───────┘
       │ stdin/stdout (JSON-RPC)
       │
┌──────▼───────────────────────────┐
│  SSE Bridge (Node.js)            │
│  ┌─────────────┐ ┌─────────────┐ │
│  │ POST        │ │ GET (SSE)   │ │
│  │ Handler     │ │ Listener    │ │
│  └──────┬──────┘ └──────┬──────┘ │
│         │                │        │
└─────────┼────────────────┼────────┘
          │                │
          │ HTTP POST      │ SSE Stream
          │ (requests)     │ (notifications)
          ▼                ▼
    ┌─────────────────────────────┐
    │  Guardian Forge Server      │
    │  (HuggingFace Spaces)       │
    └─────────────────────────────┘
```

### Message Flow

**Client → Server (Requests):**
```
Client sends: tools/list
      ↓
Bridge POSTs JSON-RPC to /mcp
      ↓
Server responds with tool list
      ↓
Bridge forwards response to client
```

**Server → Client (Notifications):**
```
User approves tool in dashboard
      ↓
Server sends SSE: notifications/tools/list_changed
      ↓
Bridge receives via GET /mcp SSE stream
      ↓
Bridge forwards notification to client stdout
      ↓
Client auto-refreshes tool list
```

## 🐛 Known Issues

1. **SSE Connection Stability**
   - SSE connections may drop after long periods
   - Bridge auto-reconnects after 5 seconds
   - Look for "SSE connection closed" messages

2. **Initial Connection**
   - SSE connection starts AFTER client sends `notifications/initialized`
   - May take 1-2 seconds to establish

3. **Firewall/Proxy**
   - SSE requires long-lived HTTP connections
   - Some firewalls/proxies may close these connections
   - Corporate networks may block SSE

## 📊 Debugging

### Enable Verbose Logging

All logs go to stderr, so you can monitor:
```bash
# Run with stderr visible
node guardian-forge-mcp-bridge-sse.js 2>&1 | tee bridge.log
```

### Look for These Messages

✅ **Success:**
```
[Guardian Forge Bridge SSE] SSE connection established - listening for notifications
```

⚠️ **Warning:**
```
[Guardian Forge Bridge SSE] SSE connection failed with status 401
[Guardian Forge Bridge SSE] Scheduling SSE reconnect in 5000ms
```

❌ **Error:**
```
[Guardian Forge Bridge SSE] SSE request error: connect ETIMEDOUT
```

### Test Notifications Manually

1. Connect the bridge
2. Request a new tool via MCP client
3. Approve it in dashboard at `/admin`
4. Watch stderr for:
   ```
   [Guardian Forge Bridge SSE] Received server notification: notifications/tools/list_changed
   ```
5. Check if tool appears in client without reconnecting

## 🔄 Switching Between Bridges

To go back to the stable bridge:
```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": ["/path/to/guardian-forge-mcp-bridge.js"]  // Remove -sse
    }
  }
}
```

## 🤝 Feedback

This is experimental! Please report:
- Connection stability issues
- Missing notifications
- Performance problems
- Compatibility with different MCP clients

## 📚 Technical Details

**SSE Implementation:**
- Uses `https.get()` with `Accept: text/event-stream`
- Parses `data:` lines from SSE stream
- Forwards JSON-RPC notifications to stdout
- Auto-reconnects on connection loss

**Notification Format:**
```json
{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed",
  "params": {}
}
```

**Capabilities Advertisement:**
```json
{
  "capabilities": {
    "tools": {
      "listChanged": true  // Tells client we support this!
    }
  }
}
```

## ⚠️ Production Use

**Recommendation:** Use the standard bridge for production until SSE bridge is thoroughly tested.

**When to use SSE bridge:**
- You want auto-updates
- You're willing to help test
- You don't mind occasional reconnections
- You can monitor logs for issues

**When to use standard bridge:**
- You need maximum stability
- You're okay with manual reconnection
- You're in a corporate network with proxy/firewall
- You're demoing Guardian Forge

---

**Status:** 🧪 Experimental - Feedback Welcome!