qbo-mcp: Instructions file for Codex

QuickBooks MCP Server

Project Overview

This is a Model Context Protocol (MCP) server that gives compatible AI clients access to QuickBooks Online. It can query, create, and edit accounting data including journal entries, bills, expenses, and reports.

Git Workflow

This repository uses a branch-and-PR workflow. Never commit directly to master; all changes land through a pull request.

• "Commit and push" means: branch from the latest origin/master, commit, push, and open a PR to master. Stop after opening the PR; do not auto-merge.
• Start from an up-to-date baseline: git fetch origin && git switch -c <branch> origin/master.
• Name branches type/short-desc using feat/, fix/, docs/, chore/, or refactor/.
• Give the PR a descriptive title and a body explaining what changed and why.
• Use closes #N in commit messages when applicable.
• Use a short imperative commit subject and explain the reason in the body.

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
|- credentials/       # Credential providers and OAuth client
|- query/              # Query helpers and pagination
|- reports/            # Report extraction helpers
|- runtime/            # Company runtime and refresh coordination
|- tools/
|  |- definitions.ts   # Tool schema definitions
|  |- index.ts         # Registry, handlers, auth retry dispatcher
|  `- handlers/        # Tool implementations
|- types/              # TypeScript definitions
`- utils/              # Files, URLs, money, output, validation

Key Conventions

Money

Use integer cents for all monetary calculations:

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

const cents = validateAmount(amount, "Line description");
const totalCents = sumCents([amountACents, amountBCents]);
validateBalance(debitsCents, creditsCents);