# netcheck MCP Server - The Hard Way

Build an MCP server that answers "is my site healthy and configured right?" from raw bytes up:
TLS certificates, DNS packets, HTTP redirects, security headers, with an SSRF guard in front of every
connection. No dnspython, no requests, no certificate library in the server code.

At the end you will have built a small version of [netcheck-mcp](https://github.com/0xmortuex/netcheck-mcp)
yourself, and you will understand the things most "network tool" MCP tutorials skip: **what the
bytes actually say**, **why an agent-facing tool must refuse to talk to your own network**, and
**how to test code that talks to the internet without the internet**.

## Why this exists

A weather-API tutorial teaches the SDK and nothing else. A network checker has real depth:

- a certificate that "fails" can fail six different ways, and each needs a different fix
- DNS is a binary protocol with compression pointers, truncation and two flavours of "not found"
- redirects hide latency, loops and downgrades unless you follow them yourself
- a tool that fetches URLs for an AI is an SSRF cannon unless you aim it carefully

## Modules

| # | Module | You build | Key idea |
|---|---|---|---|
| 1 | [TLS handshake and certs](01-tls-handshake-and-certs) | a DER certificate reader and a failure classifier | Python only decodes certs it verified; read the bytes yourself, ask OpenSSL *why* it failed |
| 2 | [DNS wire format](02-dns-wire-format) | a resolver: query bytes, compression, UDP+TCP | NXDOMAIN and NODATA are different answers |
| 3 | [Redirects and timings](03-redirects-and-timings) | a hop-by-hop HTTP tracer | connect vs TTFB vs total; loops and caps |
| 4 | [Security headers](04-security-headers) | a grader that names the exact fix | a finding without a fix is a complaint |
| 5 | [SSRF defense](05-ssrf-defense) | a guard: vet addresses, pin the IP, re-check every hop | decide by address, never by name |
| 6 | [The MCP wrapper](06-mcp-wrapper) | a stdio server over modules 1, 2 and 5 | `ToolError` is the only error text the agent sees |
| 7 | [Hermetic testing](07-hermetic-testing) | test fixtures: minted certs, a DNS server, synthetic SPF | the network is the last thing to test against |

## How to use it

```bash
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python verify.py          # runs every module against local servers; nothing leaves your machine
python 02-dns-wire-format/main.py
```

Each module has a README (the why), a `main.py` (runnable code that checks itself with `assert`),
and a "break it" exercise at the end of the README. `labs.py` at the top is the shared lab: a
throwaway certificate authority, a TLS/HTTP server and a DNS server, all on 127.0.0.1. Module 7
explains how it works; the earlier modules just use it.

Requirements: Python 3.10+. The server code in modules 1-6 uses only the standard library plus
`mcp`; `cryptography` is used only by `labs.py` to *mint test certificates*.

## Responsible use

The finished tool opens network connections on an AI's behalf. Point it only at hosts you own or are
authorised to test, and keep the SSRF guard from module 5 switched on.

## License

MIT