openfda: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Model Context Protocol (MCP) server that provides tools for querying drug information from the OpenFDA API. The server communicates over stdio and requires an OPENFDA_API_KEY environment variable.

Commands

npm run build      # Compile TypeScript to dist/
npm run build:cli  # Build + add shebang for bin entry (required for CLI)
npm run dev        # Start development server
npm run test       # Run Vitest tests
npm run test:ci    # Run tests in CI mode (no watch)
npm run typecheck  # TypeScript type checking
npm run lint       # Run ESLint
npm run smoke      # Manual end-to-end check against the built dist/ (hits the live API)
npm run probe:faers-codes  # Manual, live-API check that re-validates the FAERS code maps against openFDA's published field reference
npm run fields:sync      # Manual, live-API script that downloads FDA's published field reference and writes the committed src/catalog/drug-*.json files
npm run fields:coverage  # Manual, live-API script that measures what fraction of records populate each catalog field, writing src/catalog/drug-*.coverage.json
npm run fields:countable # Manual, live-API script that measures which declared count fields openFDA can actually aggregate, writing src/catalog/drug-*.countable.json
npm run probe:fields     # Manual, live-API script that checks every path every descriptor exposes actually returns data (not merely published)

For single test file: npx vitest run tests/ApiHandler.test.ts

.github/workflows/fields-drift.yml re-downloads FDA's field references every Monday and re-probes every exposed field, opening an issue on failure. It needs the OPENFDA_API_KEY repository secret. Run it by hand from the Actions tab after changing any descriptor's field list.

Key Files

• vite.config.ts: Vite build configuration; externalizes the SDK for StdioServerTransport compatibility, and injects __APP_VERSION__ from package.json at build time so the version reported in serverInfo cannot drift from the published version
• tests/: Vitest test suite (528 tests across 42 files: ApiHandler, bundle-size, catalog-conformance, catalog-coverage, catalog-shape, core/budget, core/codes, core/descriptor, core/envelope, core/escape, core/executor, core/http, core/project, core/query, core/registry, core/resources, core/strategy, datasets/drug-drugsfda, datasets/drug-enforcement, datasets/drug-event, datasets/drug-label, datasets/drug-ndc, datasets/drug-orangebook, datasets/drug-shortages, datasets/faers, docs-currency, drift-guard, env, faers-codes, format, label-fields, ndc, ndc-formats, no-raw-query, no-url-in-output, OpenFDABuilder, redact, registration, schema-budget, ToolManager, ToolManager.keyguard, version)
• docs/superpowers/notes/2026-09-20-field-selection.md: The authoritative record of which fields each drug-* descriptor exposes in its field enum, and why — including every field that was seeded but deliberately dropped. No code reads this file; it is the rationale behind src/datasets/drug/*.ts.
• scripts/capture-fixtures.mjs: Manual, live-API script that captures trimmed label fixtures into tests/fixtures/ (not run in CI)
• scripts/smoke-local.mjs (npm run smoke): Manual end-to-end check that drives the built dist/index.js over stdio as a real MCP client would, asserting the behaviours the 1.1.0 through 2.0.0 fixes introduced. Hits the live API, so it is deliberately NOT part of npm test; run it after npm run build:cli and before publishing. npm run smoke -- --no-key exercises the missing-key path instead.
• scripts/probe-faers-codes.mjs (npm run probe:faers-codes): Manual, live-API script that re-validates the FAERS code maps in src/datasets/drug/faers.ts (SERIOUSNESS, PATIENT_SEX, REACTION_OUTCOMES) against openFDA's published field reference (https://open.fda.gov/fields/drugevent.yaml). Hits the live API, so it is deliberately NOT part of npm test; run it whenever faers.ts's code maps change.
• scripts/fields-sync.mjs (npm run fields:sync): Manual, live-API script that downloads openFDA's published field reference for every drug endpoint and writes the trimmed, committed src/catalog/drug-<endpoint>.json files — the offline source of truth tests/catalog-conformance.test.ts checks every descriptor path against.
• scripts/fields-coverage.mjs (npm run fields:coverage): Manual, live-API script that asks openFDA how many records actually populate each catalog field (_exists_:<path>) and writes src/catalog/drug-<endpoint>.coverage.json. This is the evidence behind the exposed-field selection recorded in docs/superpowers/notes/2026-09-20-field-selection.md.
• scripts/fields-countable.ts (npm run fields:countable): Manual, live-API script that asks openFDA whether every declared countFields path (and its .exact alternate) can actually be aggregated, and writes src/catalog/drug-<endpoint>.countable.json. Countability is a property of openFDA's index mapping with no derivable rule — of the 30 count fields declared at 2.0.0, 14 were rejected upstream while 16 near-identical ones were accepted — so it has to be measured and committed for tests/catalog-conformance.test.ts to guard offline. Unlike fields-sync.mjs, it derives its endpoint list from DRUG_ENDPOINTS rather than a hardcoded map, so a new group needs only the drug- filename prefix parameterized, not its slugs listed separately. Hits the live API, so it is deliberately NOT part of npm test; run it whenever a descriptor's countFields change, and weekly via fields-drift.yml.
• scripts/probe-fields.ts (npm run probe:fields): Manual, live-API script that checks every path every DRUG_ENDPOINTS descriptor exposes (fields + countFields) with an _exists_:<path> count. tests/catalog-conformance.test.ts already proves a path is published, offline; this proves it is populated — a published-but-empty field presents as a valid search that always finds nothing, indistinguishable from absent data. Run through tsx against src/ directly, not dist/: vite.config.ts bundles a single dist/index.js with preserveModules: false, so dist/datasets/... does not exist for anything to import. Hits the live API, so it is deliberately NOT part of npm test; run it whenever a descriptor's fields or countFields change.