QBO-Multicompany-MCP: Instructions file for Codex

Repository guide for coding agents

A self-hosted remote MCP server giving an AI assistant access to several QuickBooks Online company files through one connection. Single npm package, TypeScript, deployed as a container to Azure Container Apps.

Commands

npm install
npm run build         # tsc -b
npm run lint          # eslint
npm run format:check  # prettier --check
npm test              # vitest run

All four run in CI on every push and pull request. The test suite is fully offline — in-memory store, local encryption key, scripted Intuit — so there is no reason to skip it.

Layout

• src/config.ts — every environment variable, parsed and validated. Start here to understand what the service can be told to do.
• src/oauth/ — the connector's own OAuth 2.1 authorization server (for the assistant).
• src/qbo/ — Intuit OAuth client, token lifecycle, company registry, REST client.
• src/store/ — Table Storage and in-memory stores, envelope encryption.
• src/mcp/ — MCP server and tool definitions.
• src/routes/ — OAuth routes and the published app pages.
• infra/ — Azure Bicep and the deploy script.
• docs/architecture.md — read before any structural change.

Conventions

• TypeScript, strict mode. ESM with .js import specifiers (NodeNext resolution) — importing ./foo.ts will not compile.
• Comments explain why. Match the surrounding density rather than adding narration.
• Errors reaching the model come back as tool results with isError, not protocol failures, so the model can read and correct them.

Invariants worth knowing before you change things

• Never log tokens, authorization codes, or sealed values. Realm ids and hashed user ids are the safe correlation keys.
• Operator identity is configuration, not source. Every deployment is run by someone different. Nothing about a particular operator, practice, or contact address belongs in the code — it comes from OPERATOR_* env vars.
• Test fixtures use example.com and obviously fake secrets. Keep it that way; never commit real credentials, realm ids, or company names.
• The privacy page is a factual claim. If a stored record gains a field, disclose it in src/routes/appRoutes.ts. appRoutes.test.ts has assertions that exist as a reminder.
• Several subtle things are load-bearing and documented in docs/architecture.md: the hashed user id (how one person holds many companies), conditional company writes (how concurrent refreshes do not clobber each other), the shared in-flight refresh, and single-use records consumed with ETag-conditional deletes.
• New environment variables go in three places: src/config.ts, docs/configuration.md, and .env.example — plus infra/main.bicep and infra/deploy.sh if they need to reach a deployment.