# netdiag-mcp

An MCP server that gives an AI agent read-only network diagnostics for a target host: DNS, TLS, HTTP and registry data.

Agents are good at reasoning about infrastructure problems and bad at gathering the facts. "Why is this domain not loading?" needs a resolver, a certificate, a redirect chain and a registry lookup — four different tools, none of which an LLM can do on its own. This server supplies them.

No API keys. Every backing service is keyless, so it runs the moment you clone it.

## Install and run

```bash
uv sync
uv run netdiag-mcp        # speaks MCP over stdio
```

Register it with any MCP client. For Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "netdiag": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/netdiag-mcp", "netdiag-mcp"]
    }
  }
}
```

## Tools

| Tool | Answers | Backed by |
|---|---|---|
| `dns_lookup(domain, record_type)` | What does this resolve to? A/AAAA/MX/TXT/NS/CNAME/SOA/CAA, with TTLs. | Cloudflare DNS-over-HTTPS |
| `tls_certificate(host, port)` | Who issued the cert, when does it expire, which SANs, which TLS version? | Python `ssl` |
| `http_probe(url)` | Where does this redirect to, how slow is each hop, which security headers are missing? | `httpx` |
| `ip_rdap(ip)` | Who owns this address, which allocation, which country? | RDAP registries |

Each is annotated `readOnlyHint` so a client can auto-approve it safely.

### Design notes

**NXDOMAIN is a result, not an error.** `dns_lookup` returns `{"nxdomain": true, "records": []}`. "This domain does not exist" is usually the answer the agent wanted, and burying it in an exception makes it harder to reason about.

**A failed certificate check is also a result.** `tls_certificate` returns `valid: false` with the verification message rather than raising — an expired or mismatched cert is frequently the thing being investigated.

**Errors come back as `{"error": ...}`.** A tool call that raises gives an agent nothing to work with. Every failure path returns a dict describing what went wrong.

## Security

These tools accept a hostname from a language model and then make a network request to it. That is a textbook SSRF surface: without a guard, an agent could be talked into using this server to reach `169.254.169.254` (cloud metadata), `127.0.0.1`, or anything on an internal RFC1918 network.

`resolve_public()` resolves the target and refuses it unless **every** returned address is publicly routable. Checking every answer matters — a hostile domain can return one public and one private record and win the race if only the first is inspected.

Three details that are easy to get wrong, and are covered by tests:

- **Redirects are re-checked at every hop.** A public URL is allowed to redirect to `127.0.0.1`. Following redirects with `follow_redirects=True` would validate only the first URL, so the chain is walked by hand.
- **Opaque schemes.** `data:` and `javascript:` contain no `://`, so a check for `://` misses them entirely.
- **`example.com:8080` is not a scheme.** URL scheme grammar permits dots, so a bare host:port matches the scheme pattern exactly and must not be rejected as one.

## Tests

```bash
uv run pytest -m "not integration"   # 62 offline tests
uv run pytest                        # adds 3 that need the network
```

Validation and the SSRF guard are tested offline on purpose: they are the parts that must not regress, and they should not need a working internet connection to verify.

## Requirements

Python 3.12+, `mcp>=2.0`. Note that MCP SDK 2.0 renamed `FastMCP` to `MCPServer`; this targets the 2.x API.

## Licence

MIT