waveapps-mcp: Instructions file for Claude Code

CLAUDE.md

Notes for agents working on waveapps-mcp. README.md is the user guide; this file covers how the code fits together and what has caught us out before.

What this is

A TypeScript MCP server for Wave (waveapps.com) bookkeeping: 58 tools across businesses, invoices, customers, estimates, products, bills, receipts and sales taxes. Wave gives regular users no API key, so the server uses the session a browser gets on sign-in: the waveapps cookie, sent as a Bearer token to Wave's own REST and internal GraphQL APIs.

The package is not on npm. People run it from a clone, with their MCP client pointed at the absolute path of dist/server.js.

Build, test, run

npm install                        # also installs the pre-commit secret scan
npm run build                      # tsc, src/ to dist/
npm test                           # vitest, no network
npm run typecheck
npm run test:coverage
npm run test:live                  # live contract checks, no session needed
npm run test:live:signed-in        # plus read-only checks with the stored session
npm run test:live:writes           # plus real writes on a test customer (WAVE_LIVE_TEST_CUSTOMER_ID)
npx playwright install chromium    # once, before login or refresh
cd gateway && uv sync --locked && uv run pytest   # the FastMCP gateway (Python 3.12+, uv)

• Node 20.18 or later. CI (.github/workflows/test.yml) runs npm ci --ignore-scripts, typecheck and tests on Node 20 and 22. build.yml compiles and uploads dist after Test passes on main.
• npm run dev runs tsx watch src/server.ts.
• The live suites (src/live/, vitest.live.config.ts) never run in npm test or CI. test:live drives every tool with a fake token, so nothing can be read or changed; it still catches drift because REST answers 401 for routes that exist (404 otherwise) and GraphQL validates documents, input fields and enum values before auth. test:live:signed-in builds its client without a refresher, so it can't trigger a sign-in. Run test:live after touching any query, mutation, request body or enum. test:live:writes (src/live/writes.live.test.ts) runs the write tools for real on the customer WAVE_LIVE_TEST_CUSTOMER_ID names, refuses one whose name lacks "test", only emails that customer's address, and deletes what it creates in afterEach; register each record's cleanup as soon as it exists. Run it only when the user has agreed to writes on their account.
• dist/ is gitignored, so a client pointed at dist/server.js runs whatever was built last. After pulling or switching branches, rebuild, then restart the MCP client.
• One entry point serves both roles. node dist/server.js <subcommand> runs the CLI: login, refresh [--headed], paste, save-password, whoami, logout, help. With no subcommand it starts the MCP server: stdio by default, or Streamable HTTP with WAVE_MCP_TRANSPORT=http on WAVE_MCP_BIND:WAVE_MCP_PORT (default 127.0.0.1:8765). WAVE_MCP_HTTP_TOKEN is required when WAVE_MCP_BIND is not a loopback address, and once it is set every request must carry it as a bearer token. Loopback listeners also reject Host headers whose hostname is not a loopback address (hostnameOf() strips the port, so tunnels on other ports work; this is the DNS-rebinding guard), and every listener rejects bodies over 1 MiB with a 413 after draining up to 8 MiB.
• npx waveapps-mcp ... only resolves inside the repo. User-facing hints come from cliCommand() in src/util/cli-command.ts, which gives node <path>/dist/server.js <subcommand> when the server was started that way. Use it for any new hint; don't hardcode a command.
• To check the server starts without touching Wave, send initialize and tools/list over stdin. Neither calls Wave, and the process exits when stdin closes: