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. 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, 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"). This is the detail a coder needs before submitting a claim. Auto-detects the system from the code's shape; 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 that exists in no bundled system raises unknown_code.

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) — hyphenated or 10/11-digit — directly to its RxNorm product offline, tagged source: "NDC". Auto-detects the system from each code's shape; 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. 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_browse_hierarchy or medcode_map_codes). The resolved system is echoed on every result for chaining into medcode_map_codes or a billability check.

List the bundled US medical code systems with their release identifiers, effective dates, and code counts. Confirms which ICD-10-CM fiscal year, ICD-10-PCS fiscal year, HCPCS Level II release, and RxNorm normalized set 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 prefix hierarchy one level per call — immediate parent/children only (depth-1); call iteratively for the full ancestor or descendant path (ICD-10-CM/HCPCS; ICD-10-PCS codes have no prefix parent). A resolvable code with no edge in the requested direction is a successful empty result with a notice, not an error. Drug directions (RxNorm): name_to_rxcui (drug name → RXCUI), ndc_to_rxcui and rxcui_to_ndc (NDC ↔ RXCUI; NDCs accepted hyphenated or 10/11-digit), rxcui_to_ingredients and rxcui_to_brands (RXCUI → ingredient/brand RXCUIs). 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 and name_to_rxcui 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; the point directions ignore both.

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). Filter by system (ICD10CM/ICD10PCS/HCPCS/RXNORM), billableOnly to exclude headers/categories, 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.