Skip to main content
Glama
adithyx-0

CodeWeaver

by adithyx-0
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

CodeWeaver

An MCP server that reads a clinical note and returns ranked ICD-10-CM diagnosis code candidates with clinical reasoning, validated against official CMS coding constraints (Excludes1/2 relationships, specificity rules).

Built by Team EternalBlue for the Amrita MCP Hackathon 2026 — HealthTech track.

CodeWeaver is a coding/documentation assistance tool, not a diagnostic tool. It does not make or suggest clinical/diagnostic decisions. All output must be reviewed by a qualified medical coder.

What it does

Given free-text clinical note, CodeWeaver:

  1. Segments the note into sentences and detects negation/rule-out language ("denies", "no evidence of", "r/o", etc.) so ruled-out conditions aren't coded.

  2. Fuzzy-matches affirmed segments against ICD-10-CM descriptions and inclusion terms (token-overlap / Dice coefficient — no ML, no external NLP APIs).

  3. Runs candidates through a constraint engine:

    • Excludes1 (mutually exclusive diagnoses) → hard-blocked, flagged for provider clarification.

    • Excludes2 (can co-occur but distinct) → soft-flagged for combination code review.

    • Unspecified/NOS codes → deprioritised when a more specific code is also a valid match.

    • 7th-character extensions (e.g. initial/subsequent/sequela) → flagged with the valid options when a matched code requires one; CodeWeaver does not infer which character applies.

  4. Returns each candidate with a plain-English reasoning string explaining the match and any constraint outcome.

Low-confidence matches (score < 0.5) are never presented as suggestions, even as a fallback — if nothing clears that bar, CodeWeaver says so explicitly and recommends provider clarification instead of guessing. In that case it also live-queries the NLM Clinical Tables ICD-10-CM API (full official code set, U.S. National Library of Medicine, free/no key) as a best-effort, explicitly unvalidated fallback — those results skip the Excludes1/2 engine entirely and are labeled as such.

Related MCP server: atlas_mcp

Scope

Four clinical categories, 1,934 real CMS FY2026 ICD-10-CM codes:

Category

Code range

Codes

Cardiac

I20-I25

119

Diabetes

E08-E13

322

Respiratory

J00-J99

471

Musculoskeletal (curated)

M15-M19, M25, M54, M70-M81

1,022

Musculoskeletal is a deliberately curated slice — arthritis, joint pain, back pain/sciatica, soft tissue disorders, and osteoporosis — not the full M00-M99 chapter (~7,100 codes in the source XML), which would have been far too large and far too thin on local synonym coverage to add responsibly in one pass.

This is not full ICD-10-CM coverage and CodeWeaver does not claim to be.

Data

  • ICD-10-CM codes: real CMS FY2026 data, parsed from the official icd10cm-tabular-2026.xml tabular index (src/data/parse-icd10-xml.ts). Inclusion terms are supplemented for codes with sparse official terms, using lay/clinical synonyms derived strictly from the official descriptions — not fabricated clinical claims. Final dataset: src/data/icd10-final.json (_dataSource: "cms-fy26-supplemented").

  • Clinical notes: synthetic (not real patient records), covering single-condition, multi-condition, negation, and deliberate Excludes1 conflict scenarios built around real CMS Excludes1 pairs (e.g. E10.9 ↔ E11 for T1DM vs T2DM, I22.0 ↔ I21 for subsequent MI).

Tools, resources, and prompts

Tools

Name

Input

Returns

code_clinical_note

note_text (string), max_results (int, default 10)

Ranked candidates split into suggested / flagged / blocked, each with a reasoning string, plus a confidence advisory and externalSuggestions (unvalidated NLM fallback) if nothing scores highly enough

lookup_icd10_code

code (string, e.g. "E11.9")

Full detail for one code — description, inclusion terms, Excludes1/2 relationships. Normalizes case, whitespace, and missing decimals

Resources

URI

Returns

icd10://codes

Summary of all 1,934 in-scope codes

icd10://codes/cardiac

Full detail, cardiac codes

icd10://codes/diabetes

Full detail, diabetes codes

icd10://codes/respiratory

Full detail, respiratory codes

icd10://codes/musculoskeletal

Full detail, musculoskeletal codes (curated slice)

Prompts

Name

What it does

explain_decision

Takes code_clinical_note output and produces a structured coding-rationale prompt for an LLM, for either a coder or clinician audience, with the required non-diagnostic disclaimer

Quick start

npm install
npm run dev          # start in development mode
npm run build         # compile + copy data files into dist/
npm start              # build, then start
npm run start:prod    # start an existing production build

Use NitroStudio to connect to the running server and call the tools interactively.

Testing

Rule-based pipeline logic is covered by lightweight script tests (no test framework — run directly with tsx):

npx tsx src/modules/icd10/segmentation.test.ts
npx tsx src/modules/icd10/matcher.test.ts
npx tsx src/modules/icd10/constraints.test.ts
npx tsx src/modules/icd10/pipeline.test.ts

51/51 assertions passing across all four files, exercising all 15 synthetic notes end-to-end. Or run npm test to execute all four in sequence.

Architecture

Built on NitroStack (@nitrostack/core), using its decorator-based @Tool / @Resource / @Prompt pattern with Zod schema validation. The coding pipeline itself is plain TypeScript, no ML training and no external NLP APIs — intentionally simple and explainable for a time-boxed hackathon build:

src/modules/icd10/
├── segmentation.ts   # sentence split + negation detection
├── matcher.ts         # Dice-coefficient fuzzy matching + word-form normalization
├── constraints.ts     # Excludes1/2 constraint engine + specificity ranking
├── pipeline.ts        # orchestrates the above end-to-end
├── external-lookup.ts # NLM Clinical Tables fallback (used only when no local match is confident)
├── icd10.tools.ts     # @Tool: code_clinical_note, lookup_icd10_code
├── icd10.resources.ts # @Resource: icd10://codes/*
├── icd10.prompts.ts   # @Prompt: explain_decision
└── icd10.module.ts    # module registration

Known limitations

  • Fuzzy matching is pure token-overlap with no term-importance weighting, so generic shared words (e.g. "diabetes mellitus", "acute") can produce low-score noise across many codes in a category. Excludes1/2 gating and the 0.5 suggestion threshold contain this but don't eliminate it.

  • A curated set of clinical word-form equivalences (e.g. "diabetic" ↔ "diabetes", "coughing" ↔ "cough") narrows — but doesn't eliminate — the gap from having no general stemmer.

  • Negation detection is sentence-level; a negation cue can't reach into an adjacent sentence.

  • ~85% of in-scope codes have no supplemented inclusion terms and rely on matching the raw official CMS description text, which is often too terse or formal for how notes are actually phrased — most pronounced in the musculoskeletal slice (94% unsupplemented) since it was added last.

  • 7th-character code requirements are flagged in a code's reasoning string with the valid extension characters, but CodeWeaver does not infer which one applies (e.g. initial vs. subsequent encounter) — that's left to the coder.

  • externalSuggestions (the NLM Clinical Tables fallback) only fires when no local match clears the confidence threshold, is not run through the Excludes1/2 engine, and depends on NLM's own word-prefix search semantics — it can miss valid codes on word-form mismatches (e.g. "femoral" vs. "femur").

Available Tools

2 tools
code_clinical_noteA

CODING ASSISTANCE TOOL (not a diagnostic tool). Accepts a clinical note and returns ranked ICD-10-CM diagnosis code candidates with constraint validation. Scope: cardiac (I20-I25), diabetes (E08-E13), respiratory (J00-J99), musculoskeletal (curated: M15-M19 arthritis, M25 joint disorders, M54 dorsalgia, M70-M81 soft tissue/osteoporosis). Data: CMS ICD-10-CM FY2026 (icd10cm-tabular-2026.xml), scoped to 4 categories, with supplemented inclusion terms for matchability. When no local match clears the confidence threshold, live-queries the NLM Clinical Tables ICD-10-CM API (full code set, U.S. National Library of Medicine) as an unvalidated fallback, returned under externalSuggestions.

ParametersJSON Schema
NameRequiredDescriptionDefault
note_textYesThe clinical note text to analyse (free text, any length).
max_resultsNoMaximum number of results to return across all statuses.

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses the scoped data set, data source (CMS FY2026), supplemented inclusion terms, and the unvalidated NLM API fallback under externalSuggestions. It does not detail output statuses, confidence thresholds, or constraint-validation mechanics, though it is substantially transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized: purpose first, then scope, data source, and fallback. All sentences carry information and there is no filler. It is somewhat long, but each section earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite high complexity (no annotations, no output schema, fallback API), the description covers purpose, scope, data source, and fallback behavior. However, it omits explanation of the output statuses hinted at by max_results, the confidence threshold, and what 'constraint validation' means, leaving notable gaps for a complex tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it refers to 'clinical note' and ranked results but does not elaborate on max_results or note_text format beyond what the schema already contains.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Accepts a clinical note and returns ranked ICD-10-CM diagnosis code candidates with constraint validation' and clarifies it is not a diagnostic tool. However, it does not explicitly contrast with the sibling lookup_icd10_code, so it misses the differentiation that would merit a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context by defining the tool as a coding assistance tool, listing explicit scoped categories, and describing the NLM fallback behavior. It also warns 'not a diagnostic tool,' which provides a when-not. It does not name alternatives or state when to use lookup_icd10_code instead, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_icd10_codeA

Returns full detail for a single ICD-10-CM code including inclusion terms and Excludes1/2 relationships. Data: CMS FY2026, scoped to cardiac/diabetes/respiratory/musculoskeletal (curated).

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesThe ICD-10 code to look up, e.g. "E11.9" or "J44.1".

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the data source (CMS FY2026) and scope (cardiac/diabetes/respiratory/musculoskeletal, curated), which are beyond the schema and useful for setting expectations. Since no annotations are provided, the description carries the burden, and it does so well, though it does not mention error behavior or edge cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary purpose and followed by essential data scope information. Every word earns its place, making it concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description provides sufficient context: it explains what is returned (full detail including inclusion terms and Excludes1/2 relationships) and the data scope. It does not specify return format or error handling, but for a lookup tool with this simplicity, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides a clear description of the parameter 'code' with examples. The tool description adds little beyond the schema's own parameter description, so the baseline of 3 applies here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns full detail for a single ICD-10-CM code, specifying the resource (ICD-10-CM) and the verb (Returns). It distinguishes from the sibling tool (code_clinical_note) by focusing on code lookup rather than note interaction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for looking up a single code but does not explicitly state when to use this tool versus code_clinical_note. It lacks explicit alternative names or exclusion criteria, so it only provides implied context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedcode_clinical_note
    • First observedlookup_icd10_code
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

The two tools serve clearly distinct purposes: one generates diagnosis code candidates from a clinical note, while the other retrieves detailed information for a specific ICD-10 code. There is no functional overlap.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern in snake_case: 'code_clinical_note' and 'lookup_icd10_code'. The naming is predictable and clear.

Tool Count3/5

With only 2 tools, the server feels thin for a coding/ICD-10 domain. While the two covered operations are useful, the scope is narrow and one could expect additional utilities like searching for codes or exploring categories.

Completeness4/5

The server covers the primary workflows: submitting a note for code suggestions and looking up code details. Minor gaps exist, such as no direct search-by-description or category-browsing tool, but the core use cases are addressed.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/adithyx-0/codeweaver'

If you have feedback or need assistance with the MCP directory API, please join our Discord server