| 1 | # Netdata MCP Bridge - Node.js Implementation |
| 2 | |
| 3 | This Node.js bridge converts MCP stdio communication to Netdata's MCP over WebSocket. |
| 4 | |
| 5 | ## Requirements |
| 6 | |
| 7 | - Node.js 14+ |
| 8 | - ws library |
| 9 | |
| 10 | ## Installation |
| 11 | |
| 12 | The easiest way to set up the Node.js 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 Node.js is installed |
| 24 | 2. Create a package.json file if it doesn't exist |
| 25 | 3. Install the required ws dependency |
| 26 | |
| 27 | Alternatively, you can set it up manually: |
| 28 | |
| 29 | ```bash |
| 30 | # Create a package.json file (optional) |
| 31 | npm init -y |
| 32 | |
| 33 | # Install the WebSocket library |
| 34 | npm install ws --save |
| 35 | ``` |
| 36 | |
| 37 | ## Usage |
| 38 | |
| 39 | The script can be run directly as an executable (the shebang line will use the system's Node.js): |
| 40 | |
| 41 | ```bash |
| 42 | ./nd-mcp.js ws://<ip>:19999/mcp |
| 43 | ``` |
| 44 | |
| 45 | Or explicitly with Node.js: |
| 46 | |
| 47 | ```bash |
| 48 | node nd-mcp.js ws://<ip>:19999/mcp |
| 49 | ``` |
| 50 | |
| 51 | Where `<ip>` is either `localhost` or the IP address where a Netdata instance is listening. |
| 52 | |
| 53 | ## Example with Claude Desktop |
| 54 | |
| 55 | To use this bridge with Claude Desktop: |
| 56 | |
| 57 | 1. In Claude Desktop settings, configure the Custom Command option: |
| 58 | |
| 59 | ```bash |
| 60 | node /path/to/stdio-nodejs/nd-mcp.js ws://localhost:19999/mcp |
| 61 | ``` |
| 62 | |
| 63 | 2. If your Netdata instance is running on a different machine, replace `localhost` with the appropriate IP address. |
| 64 | |
| 65 | ## How It Works |
| 66 | |
| 67 | The bridge: |
| 68 | 1. Establishes a WebSocket connection to the specified Netdata MCP endpoint |
| 69 | 2. Reads from standard input and sends to the WebSocket |
| 70 | 3. Receives messages from the WebSocket and writes to standard output |
| 71 | 4. Handles both directions simultaneously |
| 72 | 5. Automatically reconnects if the connection is lost, with exponential backoff |
| 73 | |
| 74 | ## Connection Reliability |
| 75 | |
| 76 | This bridge implements robust connection handling: |
| 77 | |
| 78 | - **Automatic Reconnection**: If the WebSocket connection is lost, the bridge will automatically attempt to reconnect |
| 79 | - **Exponential Backoff**: Reconnection attempts use exponential backoff with jitter to avoid overwhelming the server |
| 80 | - **Message Queuing**: Messages sent while disconnected are queued and delivered once reconnected |
| 81 | - **Connection Status Logging**: The bridge logs connection status to stderr for monitoring |
| 82 | - **SIGINT Handling**: Properly closes the WebSocket connection on CTRL+C |
| 83 | |
| 84 | 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. |
| 85 | |
| 86 | ## Protocol Compatibility |
| 87 | |
| 88 | - Netdata MCP implements the JSON-RPC 2.0 protocol |
| 89 | - Messages that don't conform to the JSON-RPC 2.0 format are silently ignored |
| 90 | - The bridge passes messages directly without any modification |