splitwise-mcp: Instructions file for Codex

AGENTS.md

Guidance for coding agents working in this repository.

What this is

splitwise-mcp is a Model Context Protocol server that exposes the Splitwise API as MCP tools. Python, stdio transport, personal-API-key auth.

Setup

Requires Python ≥ 3.10. Uses uv.

uv sync --extra dev      # create venv + install runtime and dev deps

Test

uv run pytest            # full suite (no network — uses httpx.MockTransport + a fake client)
uv run pytest -q tests/test_server.py   # a single file

Tests must never hit the live Splitwise API. Mock at the httpx transport layer (tests/test_client.py) or inject a fake client (tests/test_server.py).

Run

SPLITWISE_API_KEY=your_key python -m splitwise_mcp      # serve over stdio
# or the console script:
SPLITWISE_API_KEY=your_key uv run splitwise-mcp

Get a key at https://secure.splitwise.com/apps. The key is read only from the SPLITWISE_API_KEY environment variable — never hard-code or log it.

Layout

src/splitwise_mcp/
  client.py   # SplitwiseClient: auth, HTTP, error translation. One method per endpoint.
  format.py   # pure functions trimming verbose API JSON to compact dicts (saves tokens)
  server.py   # FastMCP instance, tool definitions, split math, main()
tests/        # test_client.py, test_format.py, test_server.py
docs/specs/   # design docs (source of truth for intent)

Design rules (follow these)

• Thin wrapper. Tools expose clean Splitwise operations; the calling agent does the reasoning. Name→ID resolution (e.g. "Alex" → friend id) is done by the agent calling list_friends/list_groups, not by server-side fuzzy matching. Don't add hidden matching logic.
• Trim responses. Every tool returns through a format.py function. When adding an endpoint, add a formatter — don't return raw Splitwise JSON.
• Errors are readable. client.py raises SplitwiseError with a clear message (it also catches the errors-in-a-200 quirk). Let it propagate from tools; FastMCP surfaces it to the agent.
• Money is cent-accurate. Equal splits go through server.equal_shares, which distributes leftover cents so owed shares sum exactly to cost. Reuse it; don't reinvent rounding.
• Match the surrounding style. Small, focused modules; one clear purpose each. Keep files small enough to hold in context.