MCP Beancount Tool

MCP Beancount Tool — Project Documentation **Description** - Build an MCP server that integrates with Beancount 3.2.0 to expose safe, structured tools for: viewing accounts, balances, income sheet (income statement), and transactions; inserting new transactions; removing transactions; and answering natural‑language questions via BeanQuery. - Provide deterministic, validated, and auditable interactions with a local Beancount ledger, suitable for MCP‑compatible clients (e.g., IDE agents or chat assistants) operating offline. - Emphasize correctness (balanced postings, type‑checked inputs), safety (file locking, atomic writes, backups), and usability (clear schemas and messages). Each created transaction receives a stable unique identifier to support safe updates/deletions. **Requirements** - Functional - List accounts: return name, type, open/close metadata, currencies, and optional tags/commodities. - Balances: compute account and roll‑up balances at a date or over a period; optionally convert using available price data. - Income sheet: produce an income statement (Income/Expenses and net result) for a specified period. - List transactions: filter by date range, account(s), payee, narration, tags, and metadata; include postings and totals. - Insert transaction: accept structured input (date, flag, payee, narration, postings, metadata), enforce balance; assign `txn_id` (UUID) if missing; validate with Beancount before persisting. - Remove transaction: delete by `txn_id` (required for deletion); refuse ambiguous deletes; validate resulting ledger. - Query (BeanQuery): execute read‑only BeanQuery strings and return typed rows/columns. - Natural‑language Q&A: map NL questions to safe BeanQuery templates (read‑only); return results and the generated query for transparency. - Dry‑run mode for mutations to preview effects without writing. - Non‑functional - Local‑first and offline; no network dependencies during normal operation. - Performance targets appropriate for 100k+ postings; avoid re‑parsing on trivial reads when possible. - Deterministic output formats and stable ordering for repeatability. - Clear, actionable errors (parse issues, validation failures, unbalanced postings, ambiguous matches). - Strong auditability: atomic writes, automatic timestamped backups, and file locking to prevent concurrent corruption. - Technical - Beancount 3.2.0 for parsing, validation, and query (`beancount.loader`, `beancount.core.*`, `beancount.query`). - Language/runtime: Python 3.11+. - MCP server SDK (Python) using the latest `modelcontextprotocol/python-sdk`; expose tools with JSON‑schema input/output; define stable tool names and schemas. - Transport: HTTP transport from the MCP Python SDK (server runs over HTTP). - Testing: `pytest`; sample fixture ledgers; golden files for tool responses where applicable. - Cross‑platform file locking and atomic replace on write; UTF‑8 encoding. - Configuration via file and environment: main ledger path, default currency, price/commodities options, locale/timezone. - Security & Privacy - Operate only on configured ledger roots; reject path traversal/out‑of‑scope files. - Sanitize and bound NL→BeanQuery generation to read‑only, parameterized templates; never perform writes from NL intents. - Never transmit ledger data over network; logs must redact sensitive fields when necessary. **Tasks** - Project scaffolding - Initialize Python project with `uv`, dependency pins (Beancount 3.2.0), and basic packaging. - Add configuration loader (env + config file) for ledger path and options. - Set up `pytest` with sample fixture ledgers for repeatable tests. - Provide a minimal example ledger at `tests/fixtures/example.beancount` for testing. - MCP server foundation - Integrate the latest `modelcontextprotocol/python-sdk`. - Use HTTP transport for the server; document default port and configuration. - Scaffold server entrypoint and lifecycle (no business logic yet). - Define tool manifests with JSON schemas for inputs/outputs and consistent error models. - Ledger loading & validation - Implement loader using `beancount.loader` with include handling, cache, and diagnostics capture. - Provide a validation layer to surface Beancount errors/warnings in a structured form. - Read‑only tools - `list_accounts`: enumerate accounts with metadata and inferred types. - `balance`: compute balances at date/period; include options for cost/value and conversions when price data exists. - `income_sheet`: generate period income statement (Income, Expenses, Net) with grouping and totals. - `list_transactions`: filters (date/account/payee/tag/metadata) and pagination; include postings. - `query`: execute BeanQuery safely; return columns + typed rows. - Mutation tools - `insert_transaction`: define input schema; normalize/validate postings; auto‑assign `txn_id`; pretty‑format; atomic write with backup; re‑load to verify. - `remove_transaction`: require `txn_id`; locate uniquely; remove; atomic write; re‑load to verify. - Introduce optional `dry_run` flag for both mutations; return proposed diff. - Natural‑language layer - Implement a rule/template‑based NL→BeanQuery mapper for common intents (balances, spending by category, income by month, etc.). - Validate generated queries as read‑only; expose the final query in responses for transparency. - Reliability & UX - Add file locking, atomic replace, and timestamped backups; configurable backup retention. - Normalize amounts/commodities and present deterministic output ordering. - Structured, user‑facing error messages with remediation hints. - Testing & examples - Unit tests for each tool, including edge cases (unbalanced inserts, ambiguous deletes, parse errors). - End‑to‑end tests against fixture ledgers and golden responses. - Example configuration and sample queries in docs. - Packaging & release - Package as a Python distribution; pin dependencies; provide entrypoint for MCP server. - Versioning and changelog; minimal quickstart documentation for MCP clients. **MCP SDK & Transport** - SDK: Use the latest `modelcontextprotocol/python-sdk` (installed as `modelcontextprotocol`). - Transport: HTTP transport. The server will expose an HTTP endpoint for MCP clients; default host/port and CORS/security considerations will be documented alongside configuration. No stdio transport is planned for the default setup. **Development (uv)** - Create and sync the environment: - `uv sync` (installs project and dev dependencies) - Run tests: - `uv run -m pytest` - Lint (if desired): - `uv run ruff check .` **Example configuration** - `tests/fixtures/mcp-beancount.toml` demonstrates a minimal config pointing at the bundled example ledger. Copy and adjust paths before running `uv run mcp-beancount --config <file>`.