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>.