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):

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

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

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

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

# 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:

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

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed",
  "params": {}
}

Capabilities Advertisement:

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