yahoo-finance-mcp: Instructions file for Claude Code

Working guidelines for Claude

How to work in this repository. Read this before making changes. See SPECS.md for what the project is and does.

Golden rules

1. Virtual environment only. Never use the global Python/pip. Work inside a virtual environment — a uv-created .venv counts as one, so uv run ... satisfies this rule. Without uv, invoke the project venv interpreter:
   • .\.venv\Scripts\python.exe ... (PowerShell)
   • .venv/Scripts/python.exe ... (Bash on Windows) Install deps into the venv (uv sync --extra dev, or -e . / -e ".[dev]").
2. English in the repo. All code, comments, docstrings, and docs are in English. (Conversation with the user may be in German.)
3. stdio is sacred. stdout carries the MCP JSON-RPC stream. Never print() to stdout from server/library code; log to stderr only.
4. Read-only domain. This server only reads market data. Do not add write or trade operations, and do not authenticate to Yahoo or any paid feed (see non-goals in SPECS.md). Guarding this server's own HTTP port is a different thing and is allowed — see transport.py.

Environment

• Windows, PowerShell or Bash. Python 3.11-3.14 (developed on 3.14).
• Set up (recommended): uv sync --extra dev (creates .venv, installs the versions pinned in uv.lock). Without uv: py -m venv .venv then .\.venv\Scripts\python.exe -m pip install -e ".[dev]".
• Run the server (stdio): uv run benethos-yahoo-finance-mcp, or .\.venv\Scripts\python.exe -m benethos_yahoo_finance_mcp. For HTTP transports and Docker/Compose hosting, see the README (--transport, Dockerfile, compose.yaml).

Project layout

src/benethos_yahoo_finance_mcp/
  server.py       # MCPServer instance + @mcp.tool() definitions + CLI main()
  __main__.py     # enables `python -m benethos_yahoo_finance_mcp`
  client.py       # all yfinance access, in-memory ticker cache, error mapping
  cache.py        # opt-in persistent result cache (SQLite) with per-tool TTLs
  formatting.py   # pandas/yfinance -> compact JSON-safe values
  errors.py       # ToolError / SymbolNotFoundError / RateLimitError
  transport.py    # HTTP app + optional bearer guard (stdio never uses it)
  py.typed        # PEP 561 marker, without it the annotations reach nobody
tests/            # mocked, offline unit tests (+ live smoke.py, not collected)