HLA-Verify

Official9 tools

by jasonbrelsford · JavaScript

HLA nomenclature and match checks against a pinned IPD-IMGT/HLA release. No patient identifiers.

com.hlaverify/hla-verify — MCP Server

The com.hlaverify/hla-verify Model Context Protocol (MCP) server performs HLA nomenclature and match checks against a pinned IPD-IMGT/HLA release. It operates without using patient identifiers and is focused on immunogenetics-related validation tasks.

🛠️ Key Features

HLA nomenclature checks
HLA match checks
Comparison against a pinned IPD-IMGT/HLA release
No patient identifiers

🚀 Use Cases

Immunogenetics workflows requiring HLA nomenclature verification
Automated HLA match validation against a specific reference release
Model evaluation and benchmarking related to hallucination detection in biomedical contexts

⚡ Developer Benefits

Defined grounding against a pinned IPD-IMGT/HLA release
Supports MCP tooling patterns (model-context-protocol)
Use within bioinformatics and genomics pipelines

⚠️ Limitations

Limited to HLA nomenclature and match checks against IPD-IMGT/HLA release data

Topics

benchmarkbioinformaticscloudflare-workersgenomicshallucination-detectionhlaimmunogeneticsllm-evaluationmcpmcp-servermodel-context-protocoltransplantation

Captured live from the server via tools/list.

verify_text

Scan HLA typing report text, or model output about HLA, for allele-shaped tokens and classify each one: valid / legacy (with modern form) / deleted (with successor) / fabricated. Nomenclature checking against a pinned IPD-IMGT/HLA release, not interpretation of a case. Use on any AI-generated or transcribed content mentioning HLA. Send the HLA content only, with patient identifiers removed first.

Parameters1

text

string

required

HLA typing report text, or model output about HLA typing, to scan for allele names. Send the HLA content only: strip patient names, medical record numbers, dates of birth, accession and case identifiers, and any other patient details before sending. The caller is responsible for de-identifying the text; this service neither needs nor wants identifiers and does not store request bodies.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 200000,
      "description": "HLA typing report text, or model output about HLA typing, to scan for allele names. Send the HLA content only: strip patient names, medical record numbers, dates of birth, accession and case identifiers, and any other patient details before sending. The caller is responsible for de-identifying the text; this service neither needs nor wants identifiers and does not store request bodies."
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false
}

normalize_allele

Normalize one reported HLA allele name (any era) to current 2-field form, with G group, P group, serologic equivalent, and flags.

Parameters1

name

string

required

One reported HLA allele name, any nomenclature era. An allele string only, never a patient name, medical record number or other identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 64,
      "description": "One reported HLA allele name, any nomenclature era. An allele string only, never a patient name, medical record number or other identifier."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

allele_info

Look up one exact name in the pinned release and return what it is: assigned (G/P group, first release, confirmed status, WMDA serology, null flag), valid_prefix (member count and sample), or deleted (successor). Not found if the name has never existed in any release.

Parameters1

name

string

required

Exact HLA allele name, a lower-resolution prefix, or a deleted name. An allele string only, never a patient name, medical record number or other identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 64,
      "description": "Exact HLA allele name, a lower-resolution prefix, or a deleted name. An allele string only, never a patient name, medical record number or other identifier."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

match_score

Count a donor-recipient HLA match by the published counting rules (R1-R6): allele arithmetic over chromosomes, not a donor recommendation. recipient/donor: {"A": ["A*01:01","A*02:01"], "B": [...], ...} (two reported alleles per locus, any nomenclature era; allele strings only, no patient identifiers). framework: 6/6, 8/8, 10/10, 12/12, or antigen. Returns count, per-locus verdicts, GvH/HvG mismatch counts, and flags; unresolvable typing yields 'potential', never a confident count.

Parameters3

recipient	object	required	locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.
donor	object	required	locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.
framework	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "recipient": {
      "type": "object",
      "description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "donor": {
      "type": "object",
      "description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "framework": {
      "type": "string",
      "enum": [
        "6/6",
        "8/8",
        "10/10",
        "12/12",
        "antigen"
      ],
      "default": "8/8"
    }
  },
  "required": [
    "recipient",
    "donor"
  ],
  "additionalProperties": false
}

check_typing

QC-check one HLA typing (all loci) against the pinned release: resolves every reported allele, flags unresolvable/outdated/locus-mismatched/null alleles, flags too-many/single/homozygous per locus, computes the B-leader (-21 M/T) and KIR-ligand (C1/C2/Bw4) profile, and DRB3/4/5 expected-vs-reported. Nomenclature and internal-consistency checking of the report, not clinical interpretation. typing: {"A": ["A*01:01", "A*02:01"], "B": [...], "DRB1": [...], ...} (any nomenclature era; allele strings only, no patient identifiers).

Parameters1

typing

object

required

locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.

Raw schema

{
  "type": "object",
  "properties": {
    "typing": {
      "type": "object",
      "description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "typing"
  ],
  "additionalProperties": false
}

donor_compat

Donor/recipient immunogenetic compatibility under two published rule sets: HLA-B leader match (-21 M/T, Petersdorf 2020) for a single HLA-B mismatch, and KIR ligand (C1/C2/Bw4) class comparison, computed over each side's full typing QC. Rule checking against published frameworks; it does not rank or recommend a donor. recipient/donor: {"A": [...], "B": [...], "C": [...], "DRB1": [...], ...} (allele strings only, no patient identifiers). Decision support only; not a medical device.

Parameters2

recipient	object	required	locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.
donor	object	required	locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.

Raw schema

{
  "type": "object",
  "properties": {
    "recipient": {
      "type": "object",
      "description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "donor": {
      "type": "object",
      "description": "locus -> up to 4 reported allele names. Allele strings only: never patient names, medical record numbers, dates of birth, or accession or case identifiers.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "recipient",
    "donor"
  ],
  "additionalProperties": false
}

validate_gl_string

Validate and normalize a GL String (Genotype List, ^ | + ~ / grammar): resolves every allele token, flags outdated/unresolvable names and structural problems (mixed loci within a slash-list, a repeated locus within a haplotype or across ^ blocks, more than two haplotypes, differing loci across a genotype or genotype list, empty elements), and returns the normalized string. Grammar and nomenclature checking only; send allele names, not patient identifiers.

Parameters1

string

required

GL String to validate and normalize. Allele names and GL grammar only, never patient identifiers.

Raw schema

{
  "type": "object",
  "properties": {
    "gl": {
      "type": "string",
      "maxLength": 100000,
      "description": "GL String to validate and normalize. Allele names and GL grammar only, never patient identifiers."
    }
  },
  "required": [
    "gl"
  ],
  "additionalProperties": false
}

beta_signup

Put a user on the free public beta's notification list for paid API keys. Ask before calling: it records the address they give you. Re-signing the same address is safe (status already_recorded). Someone who needs a higher rate limit today should email hello@hlaverify.com for a beta key instead of waiting.

Parameters4

email	string	required	The user's email address.
org	string	optional	Lab, company or institution (optional).
use_case	string	optional	What they would use the API for (optional). No patient details.
source	string	optional	Where the signup came from, e.g. mcp (optional).

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "description": "The user's email address."
    },
    "org": {
      "type": "string",
      "maxLength": 120,
      "description": "Lab, company or institution (optional)."
    },
    "use_case": {
      "type": "string",
      "maxLength": 500,
      "description": "What they would use the API for (optional). No patient details."
    },
    "source": {
      "type": "string",
      "maxLength": 120,
      "description": "Where the signup came from, e.g. mcp (optional)."
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}

about

What this server is and is not, what to send it, benchmark evidence for why to use it, the beta state, and terms.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

README.md10 KBView on GitHub

verifiable-science-envs

Deterministic, executable-oracle RL environments and evaluation suites for clinical genomics — starting with HLA/immunogenetics.

Every answer is computed from the pinned IPD-IMGT/HLA release's own files. No human labels, no frequency data, no licensed tables — so the grader is auditable line-by-line, the sealed split regenerates on every release, and a model cannot have memorized the post-cutoff tasks.

The benchmarks

	Tasks	What it tests	Results
HLA-Bench-A	550	Nomenclature: truncation, expression suffixes, G/P groups, serology, rename history, null-allele and near-miss traps	`bench/HLA-Bench-A.md`
HLA-Bench-C	205	Donor–recipient matching: 6/6–12/12 frameworks, antigen vs allele level, hidden nulls, GvH/HvG direction, unresolvable typing	`bench/HLA-Bench-C.md`

Working on this repo? Read CLAUDE.md first: a push to main deploys production, and the project's status, decisions and runbook live in the private portfolio hub rather than here.

Headline findings so far: every model family tested (Claude, Qwen, Mistral, Llama, Phi, Gemma) scores 0% on 2-field ambiguity expansion (0 of 30 tasks per model on the full 550-task suite), the core clinical trap; models fabricate allele names at 0.06–0.20 per task, and the anthropic/claude-sonnet-4-6 figure is 0.11 per task (54 of 550 tasks with a hallucinated name, clean re-run, all 550 tasks answered); on matching, the naive string baseline falls from 28% (family A) to 0%, and open models reach 0–14% because they count matched loci instead of chromosomes. Full tables with Wilson CIs on the bench pages; current state in the bench pages below.

Every headline figure above is recomputed from the committed run artifacts in bench/reproduce.ipynb, which prints the published number next to the recomputed one with a pass or fail for each claim. It needs no API key and no local checkout.

HLA-Verify — the graders as an API

The same engine as a verification service (no LLM, no storage): POST /v1/verify checks every allele-shaped token in free text against the pinned release (fabricated / deleted-with-successor / valid, with G groups and flags — a legacy spelling such as A*0201, Cw*0702 or Cw*07:02 is valid by the current name it stands for, flagged deprecated_name, and a fabricated Cw*9999 is caught; NMDP MAC codes are surfaced as mac_code and KIR allele names as out_of_scope, never silently skipped or counted as fabricated); POST /v1/normalize fixes typing reports; GET /v1/allele/<name> returns the facts; POST /v1/match scores a donor–recipient pair under the published rules R1–R6.

Accepted as reported typing everywhere (/v1/verify, /v1/normalize, /v1/allele, /v1/match and the lab toolkit): current names at 1–4 fields, legacy spellings (colon-less A*0101, Cw*0702; the old Cw locus label on a colon-style name, Cw*07:02), deleted names (chased to their successor), G and P group names (A*02:01:01G, DPB1*04:01P — the resolution NGS reports are issued at), the XX code (A*02:XX), two-field A*02:01g, and an optional HLA- prefix. Each shorthand leaves a flag (deprecated_name, xx_code, lg_notation) so nothing is converted silently; GET /v1/allele/A*0101 answers with the facts of A*01:01 and resolves_to. Every gene in the release is checked (all 46 IPD-IMGT/HLA genes, HLA-E/F/G, MICA/MICB, DRA, TAP among them); matching frameworks cover A, B, C, DRB1, DQB1, DPB1. Not covered: NMDP multiple allele codes (A*02:AB, recognised but not expanded), serology-only typings (A2, DR4), KIR genes (IPD-KIR; KIR3DL1*001 in free text is recognised and reported out_of_scope, not checked and not counted as fabricated), and releases other than the pinned one.

Hosted, live: api.hlaverify.com (also https://hlaverify.com/v1/…). Open for evaluation at 100 calls a day per IP (60 requests/minute, up to 250 typings per /v1/normalize call); keyed access for labs, LIMS vendors and agent platforms with higher daily quotas and larger batches (hello@hlaverify.com). Quotas reset at UTC midnight and every billable response carries x-hla-verify-daily-limit, -daily-remaining and -daily-reset.

bash

curl -s https://api.hlaverify.com/v1/verify -H 'content-type: application/json' \
  -d '{"text": "A*0101, B*15:504:01, DQB1*05:03:26:99"}'

The hosted API is a Cloudflare Worker (edge/) that looks names up in tables exported from the pinned release by this repository's Python engine (python -m sci_envs.service.edge_export); a golden test (edge/test/) proves the Worker's output is byte-identical to the Python service on thousands of generated inputs.

Self-host

From a checkout:

bash

pip install -e ".[service]" && uvicorn sci_envs.service.app:app

Or build the container image yourself (same reference data fetch, same entrypoint):

bash

docker build -t hla-verify -f sci_envs/service/Dockerfile .
docker run -p 8000:8000 hla-verify

Published images (from a tagged release) are at ghcr.io/jasonbrelsford/hla-verify once one exists:

bash

docker run -p 8000:8000 ghcr.io/jasonbrelsford/hla-verify:latest

Live demo (runs entirely in your browser — typing data never leaves your machine): hlaverify.com/demo · mirrored on Hugging Face: Spaces/jason-brelsford/hla-verify

For AI agents: MCP server

Any MCP-capable agent can add HLA-Verify as a tool server and verify HLA content before presenting it (verify_text, normalize_allele, allele_info, match_score, check_typing, donor_compat, validate_gl_string, about) — as a remote server, or self-hosted over stdio (every tool except allele_info). The remote server speaks MCP 2026-07-28 (server/discover) and the legacy initialize handshake.

Remote (Streamable HTTP, JSON-RPC 2.0, stateless — nothing to install):

json

{"mcpServers": {"hla-verify": {"url": "https://api.hlaverify.com/mcp"}}}

Add "headers": {"Authorization": "Bearer YOUR_KEY"} for a keyed tier; anonymous calls share the free tier's 100 calls a day and 60 req/min. Works in Claude Desktop, claude.ai connectors, Cursor, and any other MCP-capable client.

Local (stdio):

bash

pip install -e ".[mcp]"
python -m sci_envs.mcp_server        # stdio MCP server

Client config: {"command": "python", "args": ["-m", "sci_envs.mcp_server"]}. Also see skills/hla-verify/ (importable Claude skill) and hlaverify.com/llms.txt.

Run the benchmark

bash

pip install -e ".[dev]"
pytest -q                             # first run fetches ~33 MB of reference data
hla-bench generate                    # family A (or --family c); sealed split stays local
hla-bench run baseline-naive-string --suite runs/hla-bench-a --split dev
hla-bench run ollama/qwen2.5:7b --suite runs/hla-bench-a --split dev
hla-bench run anthropic/claude-sonnet-4-6 --suite runs/hla-bench-a --split all
hla-bench report --suite runs/hla-bench-a --out bench/HLA-Bench-A.md

Local models run free via Ollama; Anthropic/OpenAI/Gemini clients are included (keys via a gitignored .env). Raw responses and per-task scores never leave the machine; only aggregates and a stratified ≤3-per-subtype wrong-answer sample are committed.

Layout

code

sci_envs/
  reference/imgt.py         # pinned IPD-IMGT/HLA loader: fetch → md5-verify → query
  families/nomenclature/    # family A: generators, grader, normalizer
  families/phasing/         # family B: synthetic Mendelian truth generator + first graded subtypes and grader
  families/matching/        # family C: rules engine (R1–R6, documented for lab audit)
  harness/                  # runners, model clients, report
  adapters/                 # verifiers (Prime Intellect) + Inspect AI exports
  service/                  # HLA-Verify API: FastAPI service + edge table exporter (PolyForm-NC)
edge/                       # HLA-Verify API on Cloudflare Workers + golden test vs the Python oracle (PolyForm-NC)
environments/hla_nomenclature/   # pip-installable verifiers environment
harbor/                     # Terminal-Bench-style task
docs/                       # task + grader specs (families A, B, C)

Data strategy & partners

Every graded answer is computed from public, versioned data — the pinned IPD-IMGT/HLA release, synthetic Mendelian truth, and open population resources — so anyone can regenerate the suites and audit every score. Restricted registry data stays with its licensed holders: our environments run on their machines. We are seeking registry, lab, and model-developer partners — hello@hlaverify.com.

Licence

Open core: benchmark, generators, graders, harness, and adapters are Apache-2.0 (LICENSE). The HLA-Verify service (sci_envs/service/, edge/) is PolyForm Noncommercial 1.0.0 — free for research and evaluation; commercial use requires a licence from Brelsford Software LLC (hello@hlaverify.com). Reference data are fetched at runtime from IPD-IMGT/HLA under CC-BY-ND (Barker DJ et al., NAR 2025) and never redistributed.

Scope: human clinical-genomics informatics only. No sequences, no pathogens, no wet-lab protocols.

Install

Tools (9)

verify_textnormalize_alleleallele_infomatch_scorecheck_typingdonor_compatvalidate_gl_stringbeta_signup

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.hlaverify.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "hla-verify": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.hlaverify.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

com.hlaverify/hla-verify — MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

verify_text

normalize_allele

allele_info

match_score

check_typing

donor_compat

validate_gl_string

beta_signup

about

verifiable-science-envs

The benchmarks

HLA-Verify — the graders as an API

Self-host

For AI agents: MCP server

Run the benchmark

Layout

Data strategy & partners

Licence

Install

Remote endpoint

Related servers