HAR MCP — The Hard Way

Build an MCP server that lets an AI agent debug web performance from a browser's HAR export. Start from the raw JSON and end with an agent that can say "this request is slow because the server took 900 ms to answer, and here is the chain of requests that decided your load time", without ever being shown a password.

At the end you will have built a minimal version of har-mcp yourself, and you will understand the three things most MCP tutorials skip: reading data too big for memory, timing numbers that look simple and are not, and handing a model a file full of secrets safely.

Why this exists

Most MCP tutorials stop at a weather API. The hard part of a useful server is elsewhere:

• a HAR file is 10–200 MB of nested JSON; json.load would need gigabytes

• the numbers inside have traps (-1 means "n/a", ssl is inside connect)

• the file contains every cookie and bearer token your browser sent

• the model needs the three lines that matter, not 200 MB

Related MCP server: py-har-mcp

Who it is for

Developers who built a "hello world" MCP server and want a real one. You need Python 3.10+ and no knowledge of HAR.

The modules

Every module is prose (the why), runnable code, and a main.py that checks its own result with assert. Later modules import the code written in earlier ones, so you build one server step by step.

Run it

pip install -r requirements.txt     # mcp, anyio
python verify.py                    # all seven modules, ~6 seconds
python verify.py 02 04              # just those
python verify.py --big              # module 07 with a 100 MB file
python 03-timing-math/main.py       # or any single module

Each module also has a break-it.md: changes to make to the code to see exactly which assertion catches them. Do those; the failures teach more than the passes.

What is deliberately missing

The finished har-mcp has seven tools (this builds four), filters, a redirect-chain view, body previews, cache statistics, a --dir sandbox with multiple roots, and a larger test suite. Everything it has that this does not is an elaboration of something in these seven modules.

License

MIT