meloQA-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.

What this is

@meloqa/mcp-server (binary meloqa-mcp) — a public MCP server that wraps the meloQA public v1 API. The repo is intentionally separate from the main meloQA codebase so it can be distributed via npm to any MCP client. ~70 tools, one per OpenAPI operation.

Architecture

spec/openapi.json   ← source of truth (snapshot of meloQA v1 OpenAPI spec)
       │
       ▼
scripts/generate.ts ← build-time codegen
       │
       ▼
src/tools.generated.ts  ← committed; one ToolDef per operation
       │
       ▼
src/server.ts       ← MCP Server, registers tools from the generated file
src/client.ts       ← HTTP client (auth header, rate limiter, error mapping)
src/index.ts        ← stdio entrypoint (bin)

The whole pipeline is build-time codegen. The runtime does not read the OpenAPI spec — it only consumes src/tools.generated.ts. To change tool surface, edit the spec and rerun npm run gen (or npm run build).

Tool naming (derived in scripts/generate.ts)

Names come from path + method, not operationId (the spec doesn't define any):

• GET /v1/<res> → <res>_list
• GET /v1/<res>/{id} → <res>_get
• POST /v1/<res> → <res>_create
• PATCH /v1/<res>/{id} → <res>_update
• DELETE /v1/<res>/{id} → <res>_delete
• POST /v1/<res>/{id}/<action> → <res>_<action> (e.g. test_cases_unarchive)
• Sub-collections: GET /v1/<res>/{id}/<sub> → <res>_<sub>_list

Action-style paths whose name is itself the verb (e.g. /v1/executions-run) are listed in NAME_OVERRIDES in scripts/generate.ts to avoid executions_run_create.

Codegen output shape

For each operation the generator emits a ToolDef (src/types.ts) with:

• name, description (summary + tag + spec description so the LLM sees validation rules).
• inputSchema: JSON Schema literal — sent verbatim to the MCP client. Path params, query params, and body fields are merged into a single flat object; the generator throws on name collisions.
• request(input): pure function that returns { method, path, query?, body? }. Path params are interpolated with encodeURIComponent; query params only included when defined; body fields gated on !== undefined.