# defi-node-health

DeFi RPC node health, block synchronization, uptime and comparison monitoring with a CLI and Model Context Protocol (MCP) server.

**No API key required for your own RPC endpoints.** Works with Claude Desktop, Cursor, Windsurf and any MCP client.

## Features

- Health checks with latency and current block height
- `eth_syncing` progress and reference-node block lag detection
- Client version, chain ID, network ID and peer count
- Bounded watch sessions with availability and status-change reporting
- Side-by-side comparison of up to 20 RPC endpoints
- Zero runtime dependencies, TypeScript declarations and offline tests

## Frequently asked questions

### How do I check an Ethereum RPC node in Claude Desktop?

Add this MCP server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "defi-node-health": {
      "command": "npx",
      "args": ["-y", "defi-node-health"]
    }
  }
}
```

Then ask: "Check the health of https://ethereum-rpc.publicnode.com".

### How do I check whether my node is synchronized?

```bash
ALLOW_PRIVATE_RPC=1 defi-node-health sync --rpc http://127.0.0.1:8545
```

For a real block-lag measurement, provide a trusted reference:

```bash
ALLOW_PRIVATE_RPC=1 defi-node-health sync \
  --rpc http://127.0.0.1:8545 \
  --reference-rpc https://ethereum-rpc.publicnode.com
```

Without a reference, `in_sync` only reflects the node's own `eth_syncing` response; it does not independently prove the node has reached the network tip.

### Does defi-node-health need an API key?

No. It uses the RPC endpoint you provide. Public endpoints may enforce their own rate limits. If your provider requires a URL key, keep that URL in your secret manager and never paste it into shared logs or tickets; tool output redacts userinfo, query strings, fragments and token-like path segments.

### Can I compare several RPC providers?

```bash
ALLOW_PRIVATE_RPC=1 defi-node-health compare \
  --nodes primary=https://ethereum-rpc.publicnode.com,fallback=http://127.0.0.1:8545
```

The summary includes healthy, degraded and unhealthy counts plus the fastest reachable endpoint.

### Can I monitor node uptime?

```bash
ALLOW_PRIVATE_RPC=1 defi-node-health uptime --rpc http://127.0.0.1:8545 --checks 10 --interval 5000
```

Watch sessions are bounded (`maxChecks` up to 100) so CLI and MCP calls cannot run forever.

### Which chains are supported?

Any EVM-compatible JSON-RPC endpoint. Optional public presets are included for Ethereum, BNB Smart Chain, Polygon, Arbitrum, Optimism, Base and Avalanche.

## Install and verify

```bash
npm install -g defi-node-health
defi-node-health --version
```

Or run without a global install:

```bash
npx defi-node-health --version
```

## CLI quick start

```bash
defi-node-health health --rpc https://ethereum-rpc.publicnode.com
defi-node-health info --rpc https://ethereum-rpc.publicnode.com
defi-node-health watch --rpc https://ethereum-rpc.publicnode.com --checks 3 --interval 10000 --stream
```

Output is JSON. Watch `--stream` emits one JSON object per check.

## MCP tools

| Tool | Purpose |
|---|---|
| `check_node_health` | Availability, latency and current block |
| `check_block_sync` | Sync progress and reference block lag |
| `get_node_info` | Client, chain, network and peer information |
| `watch_node` | Bounded status monitoring and change counts |
| `compare_nodes` | Health and latency comparison |
| `get_node_uptime` | Availability estimate over bounded checks |

Common options include `timeoutMs` (default 10000) and `retries` (default 3). Transient HTTP 429/5xx, network failures and malformed transient responses use exponential backoff. `Retry-After` is honored up to 60 seconds.


## Endpoint security

- Loopback, private, link-local and metadata endpoints are blocked by default, including hostnames that resolve to those addresses.
- For a trusted local or private RPC, opt in explicitly with `ALLOW_PRIVATE_RPC=1` or `allowPrivateRpc: true` in code.
- Redirects are disabled by default. If enabled with `allowRedirects: true`, every redirect target is revalidated and limited to 3 hops.
- Responses are capped at 1 MiB and JSON nesting is capped at 64 levels; oversized responses fail closed.
- Result and error URLs are redacted. Keep provider credentials in your secret manager rather than sharing credential-bearing URLs.

## Status semantics

- `healthy`: RPC responds within `maxResponseMs`.
- `degraded`: RPC responds but exceeds the latency threshold.
- `unhealthy`: RPC request fails or returns an invalid response.
- `behind`: local block is more than `maxBlockLag` behind reference.
- `ahead`: local block is more than `maxBlockLag` ahead of reference.

## Development

```bash
npm test
```

Tests use local mock RPC servers and make no external network requests.

## License

MIT