monarch_mcp CLAUDE.md

Monarch MCP Server

Standalone MCP server for Monarch Money personal finance data.

Repository Structure

src/
  config.js        # Data dir + DB path resolution (MONARCH_DATA_DIR env var)
  db.js            # SQLite read-only query layer (node:sqlite DatabaseSync)
  token.js         # Auth token loader (env var or ~/.monarch-token file)
  fetch.js         # Monarch GraphQL API transaction fetcher
  import.js        # JSON → SQLite importer with upsert + pending prune
  refresh.js       # Async orchestrator: fetch → import
  api.js           # Monarch GraphQL write client (mutations + live reads)
  mirror.js        # Post-write read-back verification + local-mirror sync (shared row mapping)
  server.js        # MCP server factory: 4 resources + 12 tools
  bin/
    stdio.js       # stdio transport entry point
    cli.js         # CLI: init, refresh, serve
test/
  *.test.js        # node:test suite (149 tests)
  fixtures/
    monarch.db     # Committed 5-row fixture DB
    create-fixture-db.js  # Regenerates the fixture

Tech Stack

• Node.js ESM — "type": "module", requires Node >= 22.0.0 for node:sqlite
• MCP SDK — @modelcontextprotocol/sdk with zod for tool schemas
• SQLite — node:sqlite DatabaseSync (no native dependencies)
• Tests — node:test runner, all tests use fixture DB or mocked fetch

Running Tests

npm test                          # All 149 tests
node --test test/db.test.js       # Single file

Key Design Decisions

• Configurable data dir: MONARCH_DATA_DIR env var or ~/.monarch default. Every DB function accepts optional dbPath override for testability.
• Token at ~/.monarch-token: JSON file with { "token": "..." } field. MONARCH_TOKEN env var takes priority.
• fetchTransactions returns data, not files. The caller (refresh.js) decides where to persist.
• refreshDb is async — no execSync, direct function calls.
• Fixture DB committed. 5 deterministic rows spanning 3 accounts, 3 category types, tags, and splits. Tests never touch real financial data.