DICOM/HL7/FHIR Interoperability MCP Server

Instructions

Implementation Reference

• src/dicom_hl7_mcp/tools/field_mapper.py:117-213 (handler)

  The implementation of the `map_hl7_to_fhir` tool, which takes an HL7 field reference string and returns a FHIR resource mapping based on an internal `HL7_TO_FHIR_MAP` dictionary.

  def map_hl7_to_fhir(field_ref: str) -> str:
      """Map HL7 v2 segments/fields to FHIR R4 resources.
  
      Args:
          field_ref: HL7 field reference (e.g., "PID-3", "OBR-4", "PV1-7",
              "MSH-9"). Format: SEGMENT-POSITION.
  
      Returns:
          FHIR resource, element path, ConceptMap reference, and conversion notes.
      """
      premium_check = require_premium("map_hl7_to_fhir")
      if premium_check:
          return premium_check
  
      field_ref = field_ref.strip().upper()
  
      # Parse the field reference
      import re
      match = re.match(r"^([A-Z]{2,3})-?(\d+)(?:\.(\d+))?$", field_ref)
      if not match:
          return (
              f"Invalid field reference '{field_ref}'.\n"
              f"Expected format: SEGMENT-POSITION (e.g., 'PID-3', 'OBR-4')."
          )
  
      segment = match.group(1)
      position = int(match.group(2))
      component = int(match.group(3)) if match.group(3) else None
  
      # Look up the mapping
      lookup_key = (segment, position, component) if component else (segment, position)
      mapping = HL7_TO_FHIR_MAP.get(lookup_key)
  
      # If no component-specific mapping, try without component
      if mapping is None and component is not None:
          mapping = HL7_TO_FHIR_MAP.get((segment, position))
  
      if mapping is None:
          return (
              f"No FHIR mapping found for {field_ref}.\n\n"
              f"This field may not have a standard v2-to-FHIR mapping defined in the "
              f"HL7 v2-to-FHIR Implementation Guide.\n\n"
              f"Mapped fields for {segment}: "
              + ", ".join(
                  f"{s}-{p}" for (s, p, *_) in HL7_TO_FHIR_MAP.keys()
                  if s == segment
              )
          )
  
      parts = [
          f"## HL7 v2 -> FHIR R4 Mapping",
          f"",
          f"HL7 Field:     {field_ref}",
      ]
  
      # Add HL7 field name
      seg_info = HL7_SEGMENTS.get(segment)
      if seg_info:
          for field_def in seg_info.get("fields", []):
              if field_def["position"] == position:
                  parts.append(f"HL7 Field Name: {field_def['name']}")
                  break
  
      parts.extend([
          f"",
          f"FHIR Resource: {mapping['fhir_resource']}",
          f"FHIR Path:     {mapping['fhir_path']}",
          f"FHIR Type:     {mapping['fhir_element_type']}",
          f"",
          f"Conversion Type: {mapping['conversion_type']}",
      ])
  
      if mapping.get("concept_map"):
          parts.append(f"ConceptMap:    {mapping['concept_map']}")
  
      parts.extend([
          f"",
          f"Mapping Notes:",
          f"  {mapping['notes']}",
      ])
  
      # Add conversion guidance
      conv_type = mapping["conversion_type"]
      if conv_type == "direct":
          parts.append("")
          parts.append("Conversion Guidance: Direct mapping. Copy the value as-is (with format adjustment if needed).")
      elif conv_type == "transform":
          parts.append("")
          parts.append("Conversion Guidance: Requires data format transformation (e.g., date format, name structure).")
      elif conv_type == "lookup":
          parts.append("")
          parts.append("Conversion Guidance: Requires code/value lookup via ConceptMap or mapping table.")
      elif conv_type == "complex":
          parts.append("")
          parts.append("Conversion Guidance: Complex mapping requiring multiple component extractions and possible resource creation.")
  
      return "\n".join(parts)

• src/dicom_hl7_mcp/server.py:159-174 (registration)

  Tool registration in the MCP server setup.

      name="map_hl7_to_fhir",
      description=(
          "[Premium] Map HL7 v2 segments/fields to FHIR R4 resources. "
          "Returns FHIR resource, element path, ConceptMap reference, and conversion notes."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "field_ref": {
                  "type": "string",
                  "description": "HL7 field reference in SEGMENT-POSITION format (e.g., 'PID-3', 'OBR-4', 'PV1-7').",
              },
          },
          "required": ["field_ref"],
      },
  ),

• src/dicom_hl7_mcp/server.py:327-328 (handler)

  Dispatch logic in the server that maps the 'map_hl7_to_fhir' tool name to the implementation function.

  elif name == "map_hl7_to_fhir":
      return map_hl7_to_fhir(arguments["field_ref"])