qbo-mcp: Instructions file for Claude Code

QuickBooks MCP Server

Project Overview

This is a Model Context Protocol (MCP) server that provides Claude with access to QuickBooks Online. It enables Claude to query, create, and edit accounting data including journal entries, bills, expenses, and reports.

Git Workflow

This repo uses a branch-and-PR workflow — never commit directly to master. All changes land via pull request.

• "commit and push" means: branch off the latest master, commit, push, and open a PR to master with gh pr create. Then stop — PRs wait for review; do not auto-merge.
• Start from an up-to-date master: git fetch origin && git switch -c <branch> origin/master.
• Branch naming: type/short-desc — feat/, fix/, docs/, chore/, refactor/. E.g. fix/scraper-popup, chore/bump-deps.
• Give the PR a descriptive title and a body summarizing what changed and why.

Architecture

src/
├── index.ts           # MCP server entry point (stdio)
├── lambda.ts          # Thin API Gateway adapter
├── http/              # Provider-neutral Request → Response application
├── client/            # QuickBooks API client and caching
├── types/             # TypeScript type definitions
├── utils/             # Utility functions (files, URLs, money, output)
├── query/             # Query helpers and pagination
├── reports/           # Report extraction helpers (P&L, Balance Sheet)
└── tools/
    ├── definitions.ts # All tool schema definitions (single file)
    ├── index.ts       # Tool registry, handler map, auth retry dispatcher
    └── handlers/      # One file per tool (or per entity group)

Key Conventions

Cents-Based Money Handling

All monetary calculations use integer cents to avoid floating-point precision errors:

import { validateAmount, toCents, toDollars, sumCents, validateBalance } from "./utils/index.js";

// Validate input (rejects >2 decimal places)
const cents = validateAmount(amount, "Line description");  // throws if 10.001

// Sum safely (integer addition)
const totalCents = sumCents([amountACents, amountBCents]);

// Journal entries must balance exactly
validateBalance(debitsCents, creditsCents);  // throws if not equal