freeagent-mcp: Instructions file for Claude Code

CLAUDE.md

Project guidance for Claude Code working in this repository.

What this is

freeagent-mcp-server — an MCP (Model Context Protocol) server that exposes the FreeAgent accounting API as tools for LLM clients. TypeScript, ESM, published to npm, driven over stdio.

Architecture

src/
├── index.ts      # Entry point: builds the McpServer, wires the client, registers every tool group
├── auth.ts       # OAuth2 flow, token storage (~/.freeagent-mcp/tokens.json) and refresh
├── client.ts     # FreeAgentClient — HTTP wrapper around fetch (get/postJson/putJson/deleteReq)
├── utils.ts      # Shared helpers: jsonResponse, errorResponse, logToolCall, buildParams, safeId, constants
└── tools/        # One file per FreeAgent resource, each exporting registerXxxTools(server, client)

Tests are co-located as *.test.ts and run with vitest.

Tool pattern

Every resource file exports a registerXxxTools(server, client) function and registers tools with server.tool(...) (or server.registerTool(...)). Each handler:

1. Calls logToolCall(name, args) first.
2. Uses the client to hit the API (paths are relative, e.g. `/contacts/${id}`).
3. Wraps the result in jsonResponse(data) and errors in errorResponse(err).
4. Uses buildParams(...) for query strings.

IDs are interpolated into request paths, so every ID parameter MUST use the safeId schema from utils.ts (z string matching /^[a-zA-Z0-9_-]+$/), not a plain z.string(). See any freeagent_get_* tool for the canonical shape.

To add a tool, use the /add-tool command — it scaffolds handler, registration, and test following this pattern.

Security conventions (this repo's threat model is indirect prompt injection)

• IDs → always safeId (blocks path traversal via ID fields).
• client.ts rejects absolute URLs / ../ and verifies the resolved URL's origin matches the API base — never weaken this; it prevents the bearer token being sent off-origin.
• Browser launch uses execFile (never exec/shell) and explorer.exe on Windows — never reintroduce shell interpolation of a URL.
• Token file is written 0o600 in a 0o700 directory. Never log tokens.