io.github.cyanheads/medical-codes-mcp-server

Walk a US medical code system's hierarchy for discovery without a search term. With no `node`, returns the top-level entries (ICD-10-CM categories, HCPCS range buckets, or ICD-10-PCS first-axis values). With a `node`, returns its immediate children. ICD-10-CM and HCPCS use a prefix hierarchy (a shorter code is the parent of a longer one); ICD-10-PCS is axis-based — each of its 7 characters is an independent axis (section, body system, root operation, body part, approach, device, qualifier), but only the top-level Section axis is browsable (omit `node`): positions 2–7 are context-dependent on the preceding axis path and are not enumerable from a flat partial code, so list the complete codes in a three-character ICD-10-PCS table row with medcode_map_codes (direction children) instead. Lets an agent orient in an unfamiliar system or enumerate a category's specific codes. A large child set paginates: when the response carries a `nextCursor`, pass it back as `cursor` to fetch the next page.

Validate whether a US medical code exists, is current, and is billable in the active bundled release. Returns a discriminated status — valid_billable, valid_not_billable, valid_header, valid, or terminated — with a `whyNot` explaining non-billable and terminated cases (e.g. "valid ICD-10-CM category but not billable — submit a more specific child code"). A HCPCS code is terminated once its last valid date has passed; before then it checks as billable, with that date in `whyNot`. This is the detail a coder needs before submitting a claim. RxNorm has no billing concept, so a current RxNorm concept is `valid` with `billable: null` and no billing verdict. Auto-detects the system from the code's shape, and a code written in ICD-10-CM dotted form (`A01.00`) resolves to ICD-10-CM; pass an explicit `system` to disambiguate. A non-billable or terminated code is a successful result with a whyNot, not an error — only a code absent from the named system, or with no `system` from every bundled system, raises unknown_code, which names the other bundled system that holds the code, or every system the code's shape fits. A dotted all-digit value in ICD-9-CM form (`250.00`) is never read as an RXCUI, and its miss says ICD-9-CM is not bundled; an ICD-10-PCS section value from medcode_browse_hierarchy (`0`) checked under system ICD10PCS is named as a section, not a code. A code string that also exists in another bundled system carries `alsoInSystems` naming it, since the verdict applies only to the system that answered.

Decode one or more US medical codes to their official descriptions across ICD-10-CM (diagnoses), ICD-10-PCS (inpatient procedures), HCPCS Level II (supplies/drugs/services), and RxNorm (drugs, by RXCUI). Also decodes a National Drug Code (NDC) directly to its RxNorm product offline, tagged `source: "NDC"` — hyphenated in an FDA segment configuration (4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2) or as bare 10/11 digits; any other segment widths are malformed and stay unresolved. Auto-detects the system from each code's shape, and a code written in ICD-10-CM dotted form (`A01.00`) resolves to ICD-10-CM; pass an explicit `system` only when a value is genuinely ambiguous. Accepts 1–50 codes and returns partial success: resolved codes in `found`, unresolved in `notFound` with a per-code reason, so one bad code never fails the batch. Each reply holds `structuredContent` and the text to 24,000 bytes apiece: codes are decoded in request order, and once one has resolved, a code that would carry the reply past that budget is returned unprocessed in `deferred`, as sent, with every code after it — re-call with `codes` set to `deferred` and the same `system` and `includeHierarchy` until no `deferred` comes back. Three kinds of code are never deferred and can carry a reply past the budget: the first code that resolves, returned whole; the codes before it; and the unresolved codes after the last one that resolves, so a re-call always holds a code that resolves. Only a batch where nothing resolves fails: with ambiguous_system and `candidateSystems` when every code exists in more than one bundled system, otherwise with no_codes_found. Set `includeHierarchy` to attach each code's parent and immediate children (with a `childrenTruncated` flag when a code has more children than the cap returns — walk the full set via medcode_map_codes, or medcode_browse_hierarchy outside ICD-10-PCS); an ICD-10-PCS table row's children are the complete codes that begin with it. The resolved `system` is echoed on every result for chaining into a billability check or a medcode_map_codes parents/children walk; a bare integer that resolves nowhere is named as a possible CPT / HCPCS Level I code, which is out of scope, except a bare 10/11-digit one, which is named as an NDC no bundled drug maps to; a dotted all-digit value in ICD-9-CM form (`250.00`) is never read as an RXCUI and is named as ICD-9-CM, which is not bundled; an ICD-10-PCS section value from medcode_browse_hierarchy (`0`) looked up under system ICD10PCS is named as a section, not a code; a code string that also exists in another bundled system carries `alsoInSystems` naming it, so a single answer to a colliding code is never mistaken for the only one.

List the bundled US medical code systems with their release identifiers, effective dates, and code counts, and the RxClass drug-class layer the class crosswalks read, with each source’s version. Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, RxNorm normalized set, and RxClass sources are active before acting on any decode, search, or crosswalk result. The corpus is offline and built at package-build time — this call reports exactly which release is baked into the running server. ICD-10-CM/PCS are the US clinical modifications, not the ICD-10/ICD-11 base.

Crosswalk a US medical code or drug across systems and within a hierarchy. Hierarchy directions: `parents` and `children` walk a code's hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full ancestor or descendant path. ICD-10-CM and HCPCS walk the prefix hierarchy, stepping past an ICD-10-CM level padded with the placeholder X that is not itself a code (the parent of `S82.66XA` is `S82.66`); an ICD-10-PCS three-character table row's children are the complete codes that begin with it, and a complete code's parent is its table row; RxNorm concepts have no code hierarchy. A resolvable source with no edge in the requested direction is a successful empty result with a notice, not an error. A source code string that also exists in another bundled system carries `alsoInSystems` naming it, since only the resolved system's hierarchy was walked. Drug directions (RxNorm): `name_to_rxcui` (drug name → RXCUI; one name matches ingredients, combinations, and products alike, each hit tagged with its `conceptType`), `ndc_to_rxcui` and `rxcui_to_ndc` (NDC ↔ RXCUI; NDCs accepted hyphenated in an FDA segment configuration — 4-4-2, 5-3-2, 5-4-1, or the 11-digit 5-4-2 — or as bare 10/11 digits; `ndc_to_rxcui` names the product it decoded to and its `conceptType`), `rxcui_to_ingredients` and `rxcui_to_brands` (RXCUI → ingredient/brand RXCUIs, each with the target's RxNorm name and its `conceptType` — read that before counting a combination product's ingredients). Drug-class directions (RxClass): `rxcui_to_classes` (RXCUI → its classes: pharmacologic class, mechanism of action, physiologic effect, pharmacokinetics, therapeutic category, chemical structure, the diseases it may treat, prevent, diagnose, or induce or is contraindicated with, VA class, DEA controlled-substance schedule, CDC vaccine code; a drug product also carries its ingredients' classes, naming the ingredient in `via`, while DEA schedules are recorded only on drug products and VA classes almost only there, so map a product for those) and `class_to_rxcuis` (class ID → its direct member RXCUIs, each with its RxNorm name and `conceptType`). Each class hit carries `classType`, `source` (the RxClass source asserting it), and `relation` — a `ci_` relation is a contraindication, not an indication; narrow either direction with `classType`. Every result carries `source` provenance (which system or edge answered) so a chained call (e.g. into openfda with a resolved NDC) uses the right identifier. The `children`, `name_to_rxcui`, `rxcui_to_ndc`, `rxcui_to_classes`, and `class_to_rxcuis` directions can return large sets and paginate: a `nextCursor` in the response is passed back as `cursor` (with an optional `limit` page size) to walk the full set. A field the direction does not use is rejected with `field_not_applicable`: `limit` and `cursor` on the point directions, `classType` outside the class directions, and a `system` other than RXNORM on the drug and class directions.

Find US medical codes whose official descriptions match a described concept, via full-text search over the bundled index. Every search term must appear — matched first as a token prefix, then as a substring so inflected and compound forms are also found (a "neuropathy" search surfaces "mononeuropathy"/"polyneuropathy" siblings too, not only a standalone "neuropathy" token). An RxNorm concept matches on its drug name alone, never its term type (SBD, IN, …) — narrow by type with `chapter`. Filter by `system` (ICD10CM/ICD10PCS/HCPCS/RXNORM), `billableOnly` to exclude headers/categories and terminated HCPCS codes, and `chapter`. Use when you have a clinical description and need the code — the reverse of medcode_get_code. Results echo the resolved system per row for chaining, rank exact prefix matches ahead of substring-only matches with a deterministic tie-break, and disclose truncation with a `nextCursor`: pass it back as `cursor` to page through the full ranked set.