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