surfmeter-mcp: Instructions file for Codex

CLAUDE.md

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

Commands

Node.js 20+ and pnpm 10 are required.

• pnpm install — install dependencies
• pnpm check — type check without emitting
• pnpm test — run all vitest suites; the integration suites skip themselves when credentials are absent
• pnpm vitest run test/mcp.test.ts — run a single test file
• pnpm vitest run -t "reports validation errors" — run a single test by name
• pnpm build — compile to build/ and mark build/index.js executable
• pnpm test:all — type check, test, and build together; run this before committing
• pnpm format / pnpm format:check — Biome formatting (only the formatter is enabled, there are no lint rules)

The integration tests need a reachable Surfmeter development server and send read-only requests only:

API_ENDPOINT=http://localhost:3001 \
API_KEY=client_admin-replace-me \
pnpm test:integration

Add SURFMETER_FULL_INTEGRATION=1 to also run the extended pass that reads every collection, both search services, settings, and AI status.

Architecture

The server is a thin, layered wrapper around one HTTP API. Requests flow index.ts (stdio bootstrap) → server.ts (McpServer plus the host-facing instructions string) → tools.ts (schemas, safety categories, handlers) → client.ts (HTTP, X-API-KEY, error mapping) → result.ts (wrapping into CallToolResult).

config.ts turns API_ENDPOINT into a complete management endpoint: it appends /client_admin_api/v1 unless the value already ends with it, so both a server origin and a full endpoint work. Handlers therefore pass bare paths such as clients/7.

client.ts handles both plain JSON and Elasticsearch NDJSON scroll responses, and raises SurfmeterApiError carrying the status and the parsed error body. result.ts converts thrown errors into isError tool results instead of protocol errors, so tool failures stay readable to the model.