tuskledger-mcp: Instructions file for Codex

AGENTS.md

Working memory for AI assistants (Claude Code, Cursor, Cowork, etc.) operating on this repository. Read this first.

What this project is

tuskledger-mcp is a Model Context Protocol server that runs locally on a user's machine and gives their AI assistant typed access to data in their Tusk Ledger install. It's a thin adapter — the actual finance data and logic live in the main tuskledger app; this package just translates MCP tool calls into HTTP requests against that app's local FastAPI backend (http://127.0.0.1:8000 by default).

Local-first, no exceptions. Nothing here calls out to the network. The only HTTP destination is 127.0.0.1. If you find yourself writing a request to a non-localhost URL, stop and ask the user.

Permission boundaries

Safe to do without asking

• Add a new tool that wraps an existing read-only backend endpoint
• Improve a tool description (LLM tool-selection accuracy depends on these)
• Tighten input schemas (additionalProperties: false, required fields, etc.)
• Add tests
• Update the README, CHANGELOG, or AGENTS.md

Ask the user first

• Add a tool that performs a write/mutation
• Bump the mcp SDK version
• Change the JSON shape of any tool's output (it's a contract for the LLM caller)
• Change the env-var names (users have these wired in their MCP client config)

Never do without explicit user instruction

• Add a tool that performs a destructive operation (delete a transaction, remove a connected account, rotate keys, etc.)
• Add a non-localhost HTTP destination
• Capture, log, or transmit Plaid tokens, balances, or transaction details outside the user's machine
• Change the package name (it's published as tuskledger-mcp)

Repo structure

tuskledger-mcp/
├── README.md            ← user-facing install + usage docs
├── AGENTS.md            ← you are here
├── CHANGELOG.md
├── LICENSE              ← MIT
├── pyproject.toml       ← package metadata, deps, console script
├── tuskledger_mcp/
│   ├── __init__.py      ← __version__
│   ├── __main__.py      ← `python -m tuskledger_mcp` entry
│   ├── client.py        ← TuskLedgerClient: sync httpx wrapper
│   └── server.py        ← TOOLS list + _dispatch + build_server + serve_stdio
└── tests/
    └── test_server.py   ← dispatch + schema invariants