fathom-ai-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

npm run build          # Compile TypeScript to build/src/
npm run validate       # Type-check + lint + format check (runs all three)
npm run type-check     # TypeScript type checking only
npm run lint           # ESLint
npm run lint:fix       # ESLint with auto-fix
npm run format         # Prettier auto-format
npm run format:check   # Prettier check only
npm run mcpb:build     # Build + pack .mcpb bundle for Claude Desktop

Pre-commit hook runs type-check, lint, and format:check automatically.

Architecture

Three-layer MCP server over stdio:

src/index.ts          Entry point (shebang, error handling)
src/server.ts         MCP server: 5 tools, caching, pagination, formatting
src/fathom-client.ts  HTTP client wrapping Fathom API with retry logic

server.ts is the core file. It exports createServer() which registers all 5 tools via server.registerTool() (not the deprecated server.tool() API). Each tool handler follows the same pattern:

1. Get the singleton FathomClient (lazy-initialized from FATHOM_API_KEY env var)
2. Compute a cache key from tool name + sorted filter params
3. On cache miss or TTL expiry (5 min): fetch all pages from the API via fetchAll(), cache the result. API errors are caught and returned as user-friendly text responses (not thrown).
4. Slice the cached array by page/page_size via getPage()
5. Format items into LLM-friendly plaintext and return with pagination footer. All field accesses in formatters use nullish coalescing fallbacks to avoid rendering undefined literals.

fathom-client.ts uses native fetch() (no HTTP library). Key details:

• Base URL: https://api.fathom.ai/external/v1 -- paths are concatenated (BASE_URL + path), not joined via new URL(path, base) which would drop the path prefix
• Array params use [] suffix keys: calendar_invitees_domains[], recorded_by[], teams[]
• Retry: 3 attempts with linear backoff (1s, 2s) for 502/503/429