medical-terminologies-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.

Commands

npm run build           # esbuild bundle: src/index.ts -> dist/index.js (Node, ESM, node20)
npm run build:worker-lib # esbuild bundle: src/worker-lib.ts -> dist/worker-lib.js (the Worker's view of the package)
npm run build:all       # both bundles
npm start               # node dist/index.js (runs the MCP server over stdio)
npm run dev             # build + start (stdio)
npm test                # vitest run (skips integration tests by default)
npm run test:watch      # vitest in watch mode
npm run typecheck       # tsc --noEmit (strict; not invoked by `npm run build`)

node scripts/smoke-mcp.mjs           # smoke against the hosted Worker (initialize/tools/list/calls)
node scripts/smoke-mcp.mjs --stdio   # same smoke over local STDIO (requires npm run build)

The Cloudflare Worker (worker/, not published to npm) is an instance of the portfolio's Fase 0 hosting template (mcp-br-commons/templates/cloudflare-worker) and has its own scripts, run from inside worker/ (each first rebuilds dist/worker-lib.js at the root):

cd worker && npm run dev        # wrangler dev — local HTTP transport on :8787
cd worker && npm run deploy     # wrangler deploy
cd worker && npm run typecheck  # tsc --noEmit
cd worker && npm test           # vitest — auth, rate limit, usage, status, surface

The Worker intentionally does not list @modelcontextprotocol/server or zod in its own deps — they resolve from the parent package's node_modules so there is a single SDK copy (avoids duplicate-instance type clashes with registerAll). worker/.npmrc pins legacy-peer-deps=true so npm does not install a second copy to satisfy the agents package's hard peer ranges.

Run a single test: npx vitest run src/utils/cache.test.ts (or -t '<name pattern>' for a single case).

The package is published to npm with "bin": { "medical-terminologies-mcp": "dist/index.js" }, so consumers can launch the stdio server via npx medical-terminologies-mcp without cloning. prepublishOnly runs npm run build automatically before npm publish so the bundle is fresh in every release.