DICOM/HL7/FHIR Interoperability MCP Server

Instructions

Implementation Reference

• src/dicom_hl7_mcp/tools/field_mapper.py:13-40 (handler)

  The main entry point for the 'map_dicom_to_hl7' tool, which handles user input, performs a premium check, and processes tags individually.

  def map_dicom_to_hl7(tag: str) -> str:
      """Map DICOM tag(s) to equivalent HL7 v2 fields.
  
      Args:
          tag: DICOM tag identifier(s). Accepts tag number or keyword.
              Separate multiple tags with commas for batch lookup.
  
      Returns:
          Corresponding HL7 segment.field, mapping notes, data type conversions.
      """
      premium_check = require_premium("map_dicom_to_hl7")
      if premium_check:
          return premium_check
  
      # Handle multiple tags separated by semicolons
      tags = [t.strip() for t in tag.replace(";", ",").split(",") if t.strip()]
      # But only if they look like separate tags (not a single tag like "0010,0010")
      if len(tags) == 2:
          # Check if this is actually a single DICOM tag in GGGG,EEEE format
          parsed = _parse_tag_input(tag.strip())
          if parsed is not None:
              tags = [tag.strip()]
  
      results = []
      for single_tag in tags:
          results.append(_map_single_dicom_to_hl7(single_tag))
  
      return "\n\n".join(results)

• src/dicom_hl7_mcp/tools/field_mapper.py:43-114 (handler)

  The core logic implementation that maps a single validated DICOM tag to HL7 documentation using mappings and utility functions.

  def _map_single_dicom_to_hl7(tag: str) -> str:
      """Map a single DICOM tag to HL7."""
      # Resolve the tag
      parsed = _parse_tag_input(tag)
      tag_key = None
      tag_info = None
  
      if parsed is not None:
          tag_key = parsed
          tag_info = DICOM_TAGS.get(parsed)
      else:
          results = _find_by_keyword(tag)
          if results:
              tag_key, tag_info = results[0]
  
      if tag_key is None or tag_info is None:
          return f"DICOM tag '{tag}' not found. Use 'lookup_dicom_tag' to find the correct tag."
  
      mapping = DICOM_TO_HL7_MAP.get(tag_key)
      if not mapping:
          return (
              f"No HL7 mapping found for {format_dicom_tag(*tag_key)} ({tag_info['keyword']}).\n"
              f"This tag may not have a standard HL7 v2 equivalent. Some DICOM-specific "
              f"attributes (acquisition parameters, pixel data characteristics) have no "
              f"direct HL7 representation."
          )
  
      parts = [
          f"## DICOM -> HL7 Mapping",
          f"",
          f"DICOM Tag:  {format_dicom_tag(*tag_key)}  {tag_info['keyword']}",
          f"DICOM Name: {tag_info['name']}",
          f"DICOM VR:   {tag_info['vr']}",
          f"",
          f"HL7 Field:  {mapping['hl7_field']}",
          f"HL7 Segment: {mapping['hl7_segment']}",
      ]
  
      if mapping.get("hl7_component"):
          parts.append(f"Component:  {mapping['hl7_component']}")
  
      parts.extend([
          f"",
          f"Data Type Conversion: {mapping['data_type_conversion']}",
          f"Bidirectional: {'Yes' if mapping['bidirectional'] else 'No (DICOM -> HL7 only)'}",
          f"",
          f"Mapping Notes:",
          f"  {mapping['mapping_notes']}",
      ])
  
      # Add HL7 field details if available
      seg_id = mapping["hl7_segment"].split(" / ")[0].split(" ")[0]
      seg_info = HL7_SEGMENTS.get(seg_id)
      if seg_info:
          # Try to find the field position from the field reference
          field_ref = mapping["hl7_field"]
          import re
          pos_match = re.search(r"-(\d+)", field_ref)
          if pos_match:
              pos = int(pos_match.group(1))
              for field_def in seg_info.get("fields", []):
                  if field_def["position"] == pos:
                      parts.append(f"")
                      parts.append(f"HL7 Field Details:")
                      parts.append(f"  Name: {field_def['name']}")
                      parts.append(f"  Data Type: {field_def['data_type']}")
                      parts.append(f"  Required: {field_def['required']}")
                      if field_def.get("description"):
                          parts.append(f"  Description: {field_def['description']}")
                      break
  
      return "\n".join(parts)