medical codes mcp server changelog

https://raw.githubusercontent.com/cyanheads/medical-codes-mcp-server/HEAD/AGENTS.md

− **Version:** 0.4.1− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`− **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0− **Zod:** ^4.6.5−       when: 'The code does not exist in the named or detected system.',− Output design conventions this server follows: echo the resolved `system` on every result (provenance for chaining); split validity from existence (a non-billable/terminated code is a successful result with a `whyNot`); publish `null` for a field the system's release does not carry (RxNorm `billable` and `shortDescription`, driven by `SYSTEM_TRAITS` in `types.ts`) rather than the placeholder the row stores; partial-success batch shapes (`medcode_get_code` returns `found` / `notFound`); and `ctx.−       _render.ts                        # Shared format() helpers (renderCodeLine / renderCodeBlock)− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant f− **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.− | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |− | `bun run scripts/build-index.ts` | **Build-time only.** Download the federal source files and bake the bundled `data/medical-codes.db`. Run on the federal update cadence to refresh; the server never downloads at runtime. |− `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was + **Version:** 0.5.1+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0+ **Zod:** ^4.6.7+       when: 'The code does not exist in the named system, or with no `system` in any bundled system.',+ Output design conventions this server follows: echo the resolved `system` on every result (provenance for chaining); split validity from existence (a non-billable/terminated code is a successful result with a `whyNot`); publish `null` for a field the system's release does not carry (RxNorm `billable` and `shortDescription`, driven by `SYSTEM_TRAITS` in `types.ts`) rather than the placeholder the row stores; partial-success batch shapes (`medcode_get_code` returns `found` / `notFound`); `ctx.enri+       _render.ts                        # Shared format() helpers: the literal()/tableRow() seam for untrusted text, renderCodeLine / renderCodeBlock+ Two skill trees live at the project root, written for different readers:+ | Tree | For | Written by |+ |:-----|:----|:-----------|+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |+ Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.+ **Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |+ | `bun run scripts/build-index.ts` | **Build-time only.** Bake the bundled `data/medical-codes.db` from extracted federal source files (the script never downloads; fetch RxNorm and RxClass first with the two `scripts/ingest/fetch-*.ts` fetchers). Run on the federal update cadence to refresh; the server never downloads at runtime. |+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by+ - [ ] `plugin.json` + `mcp.json` (Agent Plugins 1.0.0 — read by Codex, Cursor, GitHub Copilot, VS Code, Kiro) populated — `plugin.json` `name` = the unscoped repo name (lowercase `a-z`, `0-9`, `-`, `.` only); `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords` from `package.json`; no other top-level field, `extensions` included. `mcp.json` holds one `"type": "stdio"` entry keyed by the unscoped name, `npx -y <full package name>`, and the same fixed `env` as `.code+ - [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass+ - [ ] If the server publishes a skill in root `skills/`: `lint:packaging` passes, and `field-test` verified every gate and identifier claim in it against live tool behavior

• + medical-codes-guide

version

0.5.0 → 0.5.1

version

0.4.2 → 0.5.0

version

0.4.1 → 0.4.2

https://raw.githubusercontent.com/cyanheads/medical-codes-mcp-server/HEAD/AGENTS.md

− **Version:** 0.4.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`−       throw ctx.fail('unknown_code', `Unknown code "${input.code}".`, { ...ctx.recoveryFor('unknown_code') });− | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible — log the caller's own arguments, never index internals. |− | `ctx.enrich` | Attach typed enrichment to the result — `medcode_search_codes` / `medcode_browse_hierarchy` disclose truncation (`{ truncated, shown, cap }`) and call `ctx.enrich.notice(...)` for empty results. |− | `ctx.fail` | Throw a typed error against the tool's declared `errors[]` reason union; pair with `ctx.recoveryFor(reason)` for the contract's recovery hint. |− | `ctx.requestId` | Unique request ID. |− **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reaso−   if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));− throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });− | `npm run build` | Compile TypeScript |− | `npm run rebuild` | Clean + build |− | `npm run clean` | Remove build artifacts |− | `npm run devcheck` | Lint + format + typecheck + security + changelog sync |− | `npm run tree` | Generate directory structure doc |− | `npm run lint:mcp` | Validate MCP tool definitions against the spec (format-parity, schema, naming) |− | `npm run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |− | `npm run list-skills` | Print the skill registry |− | `npm run format` | Auto-fix formatting (safe fixes only) |− | `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |− | `npm test` | Run tests (Vitest projects: `unit`, `smoke`, `fuzz`, `integration` — narrow with `--project <name>`) |− | `npm run test:coverage` | Run tests with istanbul coverage against the framework's thresholds |− | `npm run start:stdio` | Production mode (stdio) |− | `npm run start:http` | Production mode (HTTP) |− | `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |− | `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |− | `npm run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |− **CI is one file.** `.github/workflows/codeql.yml` is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.− `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was − **Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of w+ **Version:** 0.4.1+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`+       throw ctx.fail('unknown_code', `Unknown code "${input.code}".`);+   // Enforced at lint time: every field in `output` must appear in the rendered text.+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible — log the caller's own arguments, never index internals. |+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). `medcode_search_codes` / `medcode_browse_hierarchy` disclose truncation (`{ truncated, shown, cap }`) and call `ctx.enrich.notice(...)` for empty results. |+ | `ctx.fail` | Throw a typed error against the tool's declared `errors[]` reason union; a bare `ctx.fail('reason', msg)` carries the declared `recovery` hint on the wire. |+ | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |+ **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable?, severity?, thrownBy? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) — the single source of truth for the agent's next move. The framework puts it on the+   if (!item) throw ctx.fail('no_match', `No item ${input.id}`);+ throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });+ | `bun run build` | Compile TypeScript |+ | `bun run rebuild` | Clean + build |+ | `bun run clean` | Remove build artifacts |+ | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |+ | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |+ | `bun run list-skills` | Print the skill registry |+ | `bun run tree` | Generate directory structure doc |+ | `bun run format` | Auto-fix formatting (safe fixes only) |+ | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |+ | `bun run test` | Run tests (Vitest projects: `unit`, `smoke`, `fuzz`, `integration` — narrow with `--project <name>`; use `bun run test`, not `bun test`) |+ | `bun run test:coverage` | Run tests with istanbul coverage against the framework's thresholds |+ | `bun run start:stdio` | Production mode (stdio) |+ | `bun run start:http` | Production mode (HTTP) |+ | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |+ | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |+ | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |+ **CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was + **Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewri

version

0.4.0 → 0.4.1