| 1 | # Netdata MCP Bridge - Go Implementation |
| 2 | |
| 3 | This Go bridge converts MCP stdio communication to Netdata's MCP over WebSocket. |
| 4 | |
| 5 | ## Requirements |
| 6 | |
| 7 | - Go 1.16+ |
| 8 | - github.com/coder/websocket package |
| 9 | |
| 10 | ## Installation |
| 11 | |
| 12 | The easiest way to build the Go bridge is to use the included build script: |
| 13 | |
| 14 | ```bash |
| 15 | # Make the build script executable (if needed) |
| 16 | chmod +x build.sh |
| 17 | |
| 18 | # Run the build script |
| 19 | ./build.sh |
| 20 | ``` |
| 21 | |
| 22 | The script will: |
| 23 | 1. Check if Go is installed |
| 24 | 2. Initialize a Go module if needed |
| 25 | 3. Add required dependencies |
| 26 | 4. Build the binary as `nd-mcp` |
| 27 | |
| 28 | Alternatively, you can build it manually: |
| 29 | |
| 30 | ```bash |
| 31 | # Initialize a new module in this directory (only needed once) |
| 32 | go mod init netdata/nd-mcp-bridge |
| 33 | |
| 34 | # Add dependencies |
| 35 | go get github.com/coder/websocket |
| 36 | go mod tidy |
| 37 | |
| 38 | # Build the binary |
| 39 | go build -o nd-mcp nd-mcp.go |
| 40 | ``` |
| 41 | |
| 42 | ## Usage |
| 43 | |
| 44 | ```bash |
| 45 | ./nd-mcp ws://<ip>:19999/mcp |
| 46 | ``` |
| 47 | |
| 48 | Where `<ip>` is either `localhost` or the IP address where a Netdata instance is listening. |
| 49 | |
| 50 | ## Example with Claude Desktop |
| 51 | |
| 52 | To use this bridge with Claude Desktop: |
| 53 | |
| 54 | 1. In Claude Desktop settings, configure the Custom Command option: |
| 55 | |
| 56 | ```bash |
| 57 | /path/to/stdio-golang/nd-mcp ws://localhost:19999/mcp |
| 58 | ``` |
| 59 | |
| 60 | 2. If your Netdata instance is running on a different machine, replace `localhost` with the appropriate IP address. |
| 61 | |
| 62 | ## How It Works |
| 63 | |
| 64 | The bridge: |
| 65 | 1. Establishes a WebSocket connection to the specified Netdata MCP endpoint |
| 66 | 2. Reads from standard input and sends to the WebSocket |
| 67 | 3. Receives messages from the WebSocket and writes to standard output |
| 68 | 4. Handles both directions simultaneously |
| 69 | 5. Automatically reconnects if the connection is lost, with exponential backoff |
| 70 | |
| 71 | ## Connection Reliability |
| 72 | |
| 73 | This bridge implements robust connection handling: |
| 74 | |
| 75 | - **Automatic Reconnection**: If the WebSocket connection is lost, the bridge will automatically attempt to reconnect |
| 76 | - **Exponential Backoff**: Reconnection attempts use exponential backoff with jitter to avoid overwhelming the server |
| 77 | - **Message Queuing**: Messages sent while disconnected are queued and delivered once reconnected |
| 78 | - **Connection Status Logging**: The bridge logs connection status to stderr for monitoring |
| 79 | - **Thread-Safe Operation**: Uses goroutines and mutexes to ensure thread-safe operation |
| 80 | |
| 81 | The reconnection algorithm starts with a 1-second delay and doubles the wait time with each attempt, up to a maximum of 60 seconds. Random jitter is added to prevent connection storms from multiple clients reconnecting simultaneously. |
| 82 | |
| 83 | ## Protocol Compatibility |
| 84 | |
| 85 | - Netdata MCP implements the JSON-RPC 2.0 protocol |
| 86 | - Messages that don't conform to the JSON-RPC 2.0 format are silently ignored |
| 87 | - The bridge passes messages directly without any modification |
| 88 | |
| 89 | ## Implementation Notes |
| 90 | |
| 91 | This implementation: |
| 92 | - Uses the github.com/coder/websocket library for WebSocket communication |
| 93 | - Explicitly sets WebSocket headers including Sec-WebSocket-Key and Sec-WebSocket-Version |
| 94 | - Implements proper WebSocket handshake to ensure compatibility with Netdata's WebSocket server |
| 95 | - Sends and receives raw text messages directly (without JSON serialization/deserialization) |
| 96 | - Preserves the exact format of JSON-RPC 2.0 messages without adding extra quotes or escaping |
| 97 | - Uses Go's concurrency model with channels for efficient message processing |