DICOM/HL7/FHIR Interoperability MCP Server

Instructions

Implementation Reference

• src/dicom_hl7_mcp/tools/hl7_parser.py:176-256 (handler)

  The `explain_hl7_segment` function takes an HL7 segment identifier and returns a detailed explanation of the segment, including its name, description, field definitions (position, requirement, data type), and a list of message types that use this segment.

  def explain_hl7_segment(segment_name: str) -> str:
      """Explain what an HL7 segment does and list all its fields.
  
      Args:
          segment_name: Segment identifier (e.g., "PID", "OBX", "MSH").
  
      Returns:
          Detailed explanation of the segment with all field positions and descriptions.
      """
      segment_name = segment_name.strip().upper()
  
      seg_info = HL7_SEGMENTS.get(segment_name)
      if not seg_info:
          # Try to find partial match
          matches = [k for k in HL7_SEGMENTS if segment_name in k]
          if matches:
              return (
                  f"Segment '{segment_name}' not found. Did you mean one of these?\n"
                  + "\n".join(f"  - {m}: {HL7_SEGMENTS[m]['name']}" for m in matches)
              )
          available = ", ".join(sorted(HL7_SEGMENTS.keys()))
          return (
              f"Segment '{segment_name}' not found in dictionary.\n\n"
              f"Available segments: {available}"
          )
  
      parts = [
          f"## {segment_name} — {seg_info['name']}",
          "",
          seg_info["description"],
          "",
      ]
  
      # List all fields
      parts.append(f"### Fields ({len(seg_info['fields'])} defined)")
      parts.append("")
      parts.append(f"{'Pos':<5} {'Required':<10} {'Data Type':<10} {'Name'}")
      parts.append(f"{'---':<5} {'--------':<10} {'---------':<10} {'----'}")
  
      for field in seg_info["fields"]:
          req = field["required"]
          req_str = {
              "R": "Required",
              "RE": "Req/Empty",
              "O": "Optional",
              "C": "Conditnl",
              "B": "Backward",
          }.get(req, req)
  
          repeat = " (repeating)" if field.get("repeating") else ""
          table = f" [Table {field['table']}]" if field.get("table") else ""
  
          parts.append(
              f"{field['position']:<5} {req_str:<10} {field['data_type']:<10} "
              f"{field['name']}{repeat}{table}"
          )
          if field.get("description"):
              parts.append(f"{'':>30}{field['description']}")
          parts.append("")
  
      # Notes
      if seg_info.get("notes"):
          parts.append("### Notes")
          parts.append(seg_info["notes"])
          parts.append("")
  
      # Show which message types use this segment
      used_in = []
      for msg_type, msg_info in HL7_MESSAGE_TYPES.items():
          all_segs = msg_info.get("required_segments", []) + msg_info.get("optional_segments", [])
          if segment_name in all_segs:
              req = "required" if segment_name in msg_info.get("required_segments", []) else "optional"
              used_in.append(f"  - {msg_type} ({msg_info['name']}) [{req}]")
  
      if used_in:
          parts.append(f"### Used In Message Types")
          parts.extend(used_in[:15])
          if len(used_in) > 15:
              parts.append(f"  ... and {len(used_in) - 15} more")
  
      return "\n".join(parts)