Bookie

The problem

Financial software demands a dedicated UI — but the LLM already reads CSVs, sees receipt photos, and writes prose. Bookie owns what an LLM shouldn't improvise: a correct double-entry ledger, integer-cent math, deterministic categorization rules, and reproducible US Schedule C tax reports.

My role

Author

Highlights

• Multi-transport MCP server: stdio for local IDEs and HTTP with OAuth 2.0 + PKCE for remote mobile LLM access
• Self-healing CLI setup: handles cross-platform CRLF normalization, interactive Neon org resolution, and idempotent project creation with guided error recovery
• Automated 'Smoke Test' CI: verifies npm package integrity by installing into a disposable Neon environment and testing stdio responsiveness via the MCP Inspector
• Cost-aware serverless architecture: replaced 60s polling with opportunistic cleanup and event-driven sweeps, preventing idle compute from exhausting Neon's 'scale-to-zero' allowance
• Defensive integration testing: prevents data corruption via hostname normalization guards that block test suites from executing against production databases
• Graceful degradation UX: handles mobile LLM constraints (like Claude.ai's sandboxed runtime) by falling back to structured data extraction when binary uploads are blocked
• Observability-driven error handling: replaced opaque 'Unexpected Token' failures with shared diagnostic helpers that capture raw response text, exposing cross-test database concurrency issues
• Double-entry ledger with integer-cent math — no floating-point rounding errors across all accounting operations

Architecture

Bookie is a TypeScript-based Model Context Protocol server that manages a double-entry accounting ledger through a Neon Postgres database and Prisma ORM. The system enforces a strict separation of concerns where the host LLM handles natural language processing while the server executes deterministic money math using integer minor units to avoid floating-point errors. It supports dual transports via stdio for local use and a Hono-based HTTP layer for cloud deployment, featuring a full OAuth 2.0 flow with PKCE for secure integration with the Claude.ai connector. Engineering highlights include a centralized remote database strategy using Neon branches for environment parity, automated tool documentation generation, and a graceful degradation pattern for receipt storage using S3-compatible Railway Buckets.

Stack