pagespeed-insights-mcp: Instructions file for Codex

Agent notes

For a coding agent working in this repo: the part an agent needs and a person already knows. People start with CONTRIBUTING.md; read it before writing, because this file does not repeat it.

Build

• Keep the three ground rules in CONTRIBUTING.md: standard library only, no number without its uncertainty, lab and field kept separate. They are constraints, not preferences: a change that breaks one is rejected however good the rest is.
• Keep Python 3.9 working. CI runs 3.9 and 3.12 on Linux, macOS and Windows. A 3.10-only construct (match, a runtime-evaluated X | Y annotation, zip(strict=), itertools.pairwise, tomllib, dataclass(slots=)) passes on a newer interpreter and fails only in the 3.9 leg.
• Change the version in pagespeed_insights/__init__.py and the tool list in the package, then run ./build-mcpb.py --sync. manifest.json is generated from them, so edit it only through --sync. Tool titles and hints are in CONTRIBUTING.md, under "Building the bundle".
• Extract shared logic only when two callers need it. One caller makes a layer for nothing.

Test

python3 -m compileall -q pagespeed_insights setup.py mcp_server.py tests
python3 -m unittest discover -s tests -v
./build-mcpb.py --check

A PR needs all three green. Read the test count, not the word "passed": a collection error reports zero failures. No test needs an API key or a network connection; to try the real API, follow "Testing against the real APIs" in CONTRIBUTING.md.

Capture the before while you are still reproducing the problem, which is when it is cheapest, and the after once the change works. Here that is usually a pair of command outputs.

Not checkable locally: the Windows and Linux CI legs, the 3.9 leg unless 3.9 is installed, how a client renders the tool list, and whether the MCP Registry accepts a listing (mcp-publisher validate is the only thing that answers that before a release is cut).