openfda-mcp-server: Instructions file for Codex

AGENTS.md

Operational notes for coding agents working in this repo.

Running the server

pixi run serve
# or, once installed:
openfda-mcp-server

Communicates over stdio — it's meant to be launched by an MCP client, not run standalone for interactive use.

Requires FDA_API_KEY in the environment or a .env file at the repo root (loaded automatically via python-dotenv). The server works without a key at a lower rate limit (1k req/hr vs 120k req/hr), so its absence won't break anything, just throttle it.

Launch gotcha: if the host that spawns this server doesn't set the working directory (e.g. Claude Desktop, which launches as a GUI process with no shell PATH/cwd), pixi run serve alone will fail to find pixi.toml. Use an absolute path to pixi plus --manifest-path instead of relying on cwd:

/opt/homebrew/bin/pixi run --manifest-path /abs/path/to/openfda-mcp-server/pixi.toml serve

Dev commands

pixi run test       # pytest, offline (respx-mocked), integration tests excluded by default
pixi run lint        # ruff check
pixi run fmt          # ruff format
pixi run typecheck  # pyright

Run all four after any code change; CI (.github/workflows/ci.yml) runs lint/typecheck/test on push and PR.

Layout

src/openfda_mcp_server/
├── client.py   # FDAClient — async httpx wrapper around the openFDA REST API, retry/backoff, endpoint registry
├── server.py   # FastMCP entry point, lifespan-managed FDAClient
└── tools.py    # MCP tool definitions/handlers — this is where new search tools get added

Tool definitions and their docstrings (which the LLM sees as tool descriptions) live in tools.py. New openFDA endpoints need an entry in ENDPOINTS in client.py plus a corresponding @mcp_server.tool() function in tools.py.