mcp-server-kalshi: Instructions file for Codex

AGENTS.md

Guidance for AI agents (Claude Code, Cursor, etc.) working in this repo. Human-oriented usage/config lives in README.md; this file is the map + the conventions + the gotchas.

What this is

An MCP server that exposes the Kalshi prediction-market Trade API v2 as MCP tools, built for deep end-to-end trading (discover → research → read settlement rules → trade). Python 3.10+, uv, mcp low-level Server, httpx, pydantic.

Build / test / verify

uv sync --extra dev          # install (Python 3.10+)
uv run start                 # run the server over stdio
uv run pytest                # run the test suite  <- the feedback loop
uv run pytest --cov          # tests with a coverage report
uv run ruff check src tests  # lint (import order, pyflakes, pyupgrade, bugbear)
uv run black src tests       # format
uv run mypy                  # type check
uv run pre-commit install    # (once) run ruff+black on every commit

Run uv run pytest before declaring any change done. Tests are pure/offline — they exercise the order translation, the confirm-gate, the HTTP client (via an injected httpx.MockTransport), the tool registry, config, and PDF extraction, all by monkeypatching or mocking. Make no network calls. Keep it that way: never hit the live Kalshi API from a test. CI (.github/workflows/ci.yml) runs ruff + black + mypy + pytest across Python 3.10–3.13 on every push/PR, and releases are gated on that same suite.

Architecture (the 60-second map)

Data flows request → schema → client → server → MCP:

config.py                     Settings (env/.env). Safety default: KALSHI_ENV=demo.
kalshi_client/
  base.py                     BaseAPIClient (async httpx) + KalshiAuth (RSA-PSS signing)
                              + KalshiAPIError. Auth is OPTIONAL (public tools work keyless).
  client.py                   KalshiAPIClient: one async method per REST endpoint, PLUS the
                              build_*_order_payload() translators (see "cents model" below).
  schemas.py                  Pydantic request models. All extend MCPSchemaBaseModel, whose
                              to_mcp_input_schema() emits clean MCP inputSchemas.
  pdf.py                      fetch_pdf_text() — download + extract a contract-terms PDF.
server.py                     ToolRegistry (@register_tool decorator) defines every tool;
                              handlers validate the dict against a schema and call the client.
                              KALSHI_BACKGROUND_INFO is the server's MCP `instructions`.