claude code plugin · v0.6.0 · MIT

HealthIT Copilot

HL7 v2 ↔ FHIR mapping and interface debugging, inside Claude Code.

Built for Health-IT and healthcare integration engineers who live in ORU feeds, interface engines, and FHIR APIs.

# 1 — add the marketplace

/plugin marketplace add sinteco/healthit-copilot

# 2 — install the plugin

/plugin install healthit-copilot@sintayehu-health
110 tests 7/7 samples round-trip losslessly 12 deterministic tools zero pip dependencies

New in v0.6.0 — C-CDA allergies / immunizations / procedures · SIU & MDM reverse generation · FHIR R4B/R5 targets · batch directory mapping · release notes →

#Before / after

One lab result message in, one valid FHIR R4 transaction Bundle out — with every mapping gap flagged instead of silently guessed.

HL7 ORU^R01 in
MSH|^~\&|LAB|HOSP|EMR|HOSP|20240115||ORU^R01|MSG001|P|2.5
PID|1||12345^^^HOSP^MR||DOE^JOHN||19800101|M
OBR|1||ORD789|CBC^Complete Blood Count^L|||20240115
OBX|1|NM|718-7^Hemoglobin^LN||13.5|g/dL|13.0-17.0|N|||F
OBX|2|NM|4544-3^Hematocrit^LN||40.5|%|40-50|N|||F
FHIR R4 out
{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    { "fullUrl": "urn:uuid:patient-1",
      "resource": {
        "resourceType": "Patient",
        "identifier": [{ "value": "12345" }],
        "name": [{ "family": "DOE", "given": ["JOHN"] }],
        "birthDate": "1980-01-01", "gender": "male" },
      "request": { "method": "POST", "url": "Patient" } },
    { "fullUrl": "urn:uuid:report-1",
      "resource": {
        "resourceType": "DiagnosticReport",
        "status": "final",
        "code": { "text": "Complete Blood Count" },
        "subject": { "reference": "urn:uuid:patient-1" },
        "effectiveDateTime": "2024-01-15",
        "result": [{ "reference": "urn:uuid:obs-1" },
                   { "reference": "urn:uuid:obs-2" }] } },
    { "fullUrl": "urn:uuid:obs-1",
      "resource": {
        "resourceType": "Observation", "status": "final",
        "code": { "coding": [{ "system": "http://loinc.org",
                    "code": "718-7", "display": "Hemoglobin" }] },
        "valueQuantity": { "value": 13.5, "unit": "g/dL" },
        "referenceRange": [{ "text": "13.0-17.0" }],
        "interpretation": [{ "coding": [{ "code": "N" }] }] } },
    { "fullUrl": "urn:uuid:obs-2",
      "resource": {
        "resourceType": "Observation", "status": "final",
        "code": { "coding": [{ "system": "http://loinc.org",
                    "code": "4544-3", "display": "Hematocrit" }] },
        "valueQuantity": { "value": 40.5, "unit": "%" },
        "referenceRange": [{ "text": "40-50" }] } }
  ]
}
_gaps flagged:
  • OBX-3 codes are pass-through — confirm against LOINC before go-live
  • OBR-4 order code is local (^L) — verify against the order catalog
  • No UCUM validation performed on units

#Why it's not just an LLM

Parsing, validation, and transformation run as real, deterministic code — a spec-correct HL7 v2 parser and a FHIR R4 rules engine shipped with the plugin. Field positions, encoding characters, escape sequences, and status value sets come from executed output, not from a model's recollection of the HL7 spec.

Claude does what it's good at — explaining, planning the mapping, spotting semantic mismatches — while the tools guarantee that PID-7 really is the birth date and that "finalized" is not a valid Observation status. Anything the tools can't ground gets flagged in _gaps instead of guessed.

#What it does

/map-hl7-to-fhir

Convert an HL7 v2 message (ORU, ADT, ORM, SIU, MDM) or a CDA/CCD document into a valid FHIR transaction Bundle — R4, R4B, or R5 — with every unmapped field reported.

/validate-fhir

Validate FHIR JSON against R4 structural rules — required elements, status value sets, value[x] — and explain each finding.

/diag-sync

Diagnose interface failures step by step: parse the rejected message, isolate the offending field, propose the fix.

#All 12 MCP tools

Every command above is backed by deterministic tools you can also call directly.

parse_hl7v2

Parse any HL7 v2 message into structured segments, fields, and components.

hl7_to_fhir_skeleton

ORU / ADT / ORM / SIU / MDM → FHIR transaction Bundle (R4, R4B, or R5).

cda_to_fhir

CDA/CCD documents → FHIR: results, problems, meds, allergies, immunizations, procedures.

fhir_to_hl7v2

Reverse-generate HL7 v2 (ORU, ADT, ORM, SIU, MDM) from a FHIR Bundle.

round_trip_check

HL7 → FHIR → HL7 diff to prove your mapping is lossless.

validate_fhir

Structural FHIR R4 validation — required elements, status codes, value[x].

validate_fhir_hapi

Full profile validation (US Core) via the official HL7 validator CLI.

generate_engine_code

Mirth / Rhapsody / FHIR Mapping Language transformer code from a mapping.

lookup_terminology

Live LOINC / SNOMED code lookup against tx.fhir.org.

expand_valueset

Expand VSAC / tx.fhir.org ValueSets to their member codes.

explain_hl7_field

Explain any segment-field position — name, data type, table values.

map_directory

Batch map + validate a whole folder of .hl7 / .xml messages in one call.

Runs locally. Test / de-identified data only. No PHI leaves your machine.

#Roadmap

Next up: FHIR → CCD reverse generation, HL7 ACK tooling, X12 eligibility skeletons, and site-specific mapping profiles — see the full roadmap.