elorus-mcp: Instructions file for Claude Code

AGENTS.md

Guidance for AI coding agents working in this repository.

What this is

elorus-mcp is an MCP (Model Context Protocol) server that exposes the Elorus invoicing/accounting REST API (v1.2, https://api.elorus.com/v1.2/) as MCP tools and resources, so an AI assistant can create invoices, manage contacts, record payments, etc. Node 20+, TypeScript, stdio transport, published as elorus-mcp on npm.

Commands

npm run build          # tsc -p tsconfig.build.json (production build, excludes src/__tests__)
npm run dev             # tsc --watch
npm test                # vitest run (all tests)
npm run test:watch      # vitest (watch mode)
npm run test:coverage   # vitest run --coverage
npm start               # node --env-file=.env dist/index.js (local dev; requires npm run build first)

Run a single test file: npx vitest run src/__tests__/integration/invoices.test.ts (or any path). Run tests matching a name: npx vitest run -t "void".

Local dev needs ELORUS_API_KEY and ELORUS_ORG_ID (copy .env.example to .env). Only npm start reads .env (via node --env-file); when launched through an MCP client config (Claude Desktop/Code), that config's own env block is what's used instead — the two are not merged. ELORUS_DEMO=1 targets Elorus's demo/sandbox org. ELORUS_ATTACHMENT_ROOT must be set to allow file_path-based attachment uploads (add_bill_attachment/add_expense_attachment); unset, only content_base64 works.

Architecture

Entry point src/index.ts: builds ElorusClient from getConfig() (src/auth.ts), constructs one McpServer, then calls a register<X>Tools(server, client) function per resource module from src/tools/, and finally registerResources(server, client). Adding a new resource module means writing the file and adding one import + one call here — nothing else is wired centrally.

src/client.ts — ElorusClient: the only place that talks to the Elorus API. Injects Authorization: Token <key>, X-Elorus-Organization, and X-Elorus-Demo headers. Methods: get/post/put/patch/delete<T>(), postMultipart<T>() (for attachment uploads — strips the default JSON Content-Type so fetch sets its own multipart boundary), getBinary() (for PDF export — requires Accept: application/pdf, rejects non-PDF responses, caps body at MAX_BINARY_RESPONSE_BYTES, bypasses the JSON parsing path entirely), and mergePut<T>(). Every request goes through fetchWithTimeout (30s AbortSignal.timeout); only get() retries (up to MAX_GET_RETRIES, on 429/5xx, honoring Retry-After) — writes are never auto-retried. Errors are normalized by formatHttpError/formatDrfError into a single readable Error.