fred-mcp: Instructions file for Codex

AGENTS.md

Open-source MCP server for FRED economic data. FastMCP 4 wraps fred-py-api. One process, no database, no cache. Version is in pyproject.toml. Python >=3.10. CI runs on 3.13.

The server exposes 31 read-only tools in five domains, plus the fred_research_workflow prompt. tests/test_tools.py asserts the tool count. Change that assertion when you add or remove a tool.

Setup and checks

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
make check

make check runs ruff check src tests and then pytest. make lint and make test run one of those. CI calls make check on pull requests and pushes to main when src/, tests/, pyproject.toml, the Makefile, the Dockerfile, or the workflow file changes. A published GitHub Release publishes the package to PyPI and the Docker image to GHCR as latest, the release git tag, and the released commit SHA. Pushes to main do neither. The image runs fred-mcp with MCP_SERVER_TRANSPORT=streamable-http on 0.0.0.0:8000.

Run the server:

# stdio (default). FRED_API_KEY is required.
FRED_API_KEY=$FRED_API_KEY fred-mcp

# HTTP. Clients send their own key. Endpoint: http://localhost:8000/mcp
MCP_SERVER_TRANSPORT=streamable-http MCP_SERVER_HOST=0.0.0.0 MCP_SERVER_PORT=8000 fred-mcp

MCP_SERVER_TRANSPORT is stdio, streamable-http, or sse.

Where a change goes

main.py builds the server, mounts the five domain servers, and installs ToolCallLoggingMiddleware. Add a tool on the domain server in src/fred_mcp/<domain>/tools.py. Mount a new domain from main.py.

Each tool is a thin function:

• Decorate with @<domain>_mcp.tool. Set name (snake_case), a description that includes an example call, and annotations={**READ_ONLY_ANNOTATIONS, "title": "..."}.
• Accept FRED parameters explicitly. Use the Literal aliases in common/types.py for enums. Add a new alias there instead of inlining a new set of allowed strings.
• Return call_fred("<fred-py-api method>", ...). call_fred drops None values and sets file_type="json". Do not pass the API key in. Do not call FredAPI from a tool.
• Let FRED failures raise ToolError through raise_fred_tool_error. Do not return {"error": ...}.