HL7消息处理工具

HL7工具

HL7 v2.x消息工具包——解析、检查、验证、匿名化和传输 HL7 v2消息。三个接口，零外部服务依赖：

• 网络观众 (hl7-viewer.html)--单个自包含的HTML文件，工作 从 file:// 在任何浏览器中，无需服务器或构建步骤
• 终端查看器 --Python CLI+带文本的交互式TUI
• MCP服务器 --通过模型上下文协议将所有工具暴露给AI代理 （解析、验证、匿名化、转换、区分、发送、解释）

HL7 v2.3、v2.5和v2.8的内置段/字段定义（约22-37个段，约38个段 复合数据类型）。支持集成配置文件（自定义JSON覆盖 字段名、验证规则、值映射）、字节级编码检测 （UTF-8/ISO-8859-1/带BOM的ASCII）和PID/NK1/GT1/IN1/MRG段的PHI匿名化。

安装

git clone https://github.com/klauseduard/hl7-tools.git
cd hl7-tools
python3 -m venv venv
venv/bin/pip install -e ".[dev]"

这将安装 hl7view 和 hl7view-mcp 命令进入venv。用以下方式激活它 source venv/bin/activate，或直接通过运行 venv/bin/hl7view.

或者，安装依赖项而不打包：

venv/bin/pip install -r requirements-mcp.txt

网络观众

文件： hl7-viewer.html --单个独立的HTML/CSS/JS文件，没有依赖关系，没有服务器。

快速开始

1. 打开 hl7-viewer.html 在Firefox（或任何现代浏览器）中-- file:// 作品
2. 粘贴HL7消息，拖放 .hl7 文件，或单击 打开
3. 单击任何字段行以查看右侧面板中的详细信息

布局

四选项卡界面：

使用左侧面板上方的选项卡在输入/解析/原始/比较之间切换。

特性

• HL7定义 --每个版本（v2.3、v2.5、v2.8）约22-37个段，包含约38个复合数据类型和命名组件
• 自动检测版本 从MSH-12（例如v2.3.1映射到v2.3，v2.8.x映射到v2.8定义）
• 正确的MSH编号 --MSH-1= | （字段分隔符），MSH-2=编码字符
• 组件/子组件解析 — ^ 组件， & 子部件， ~ 现场重复
• OBX-5动态打字 --从OBX-2值解析的数据类型
• 编码检测 --字节级UTF-8/ISO-8859-1/ASCII检测，支持BOM；MSH-18不匹配警告
• HL7逃逸序列 — \F\, \S\, \T\, \R\, \E\, \.br\, \.sp\, \Xhh\ 识别和解码
• 集成配置文件 --加载JSON文件以覆盖自定义字段名、描述、注释、值映射（请参见 档案)
• 匿名化 --使用ASCII或爱沙尼亚（非ASCII）名称池切换PHI匿名化（PID、NK1、GT1、IN1、MRG）
• 实时搜索 --按地址、名称、类型或值过滤字段（在“解析”和“比较”选项卡中都有效）
• 隐藏空白字段 --切换以隐藏空字段及其组件(E key），保存在本地存储中
• 单击以突出显示 --单击解析后的行以突出显示原始视图中的相应位置
• 消息比较 --比较两条消息的字段级差异选项卡，其中字符级突出显示更改的字符、摘要栏、过滤器切换（仅差异/所有差异）和详细信息面板中的并排组件细分
• 键盘导航 --箭头键，按Enter键展开，按Esc键清除搜索

键盘快捷键（Web）

终端查看器

包裹： hl7view/ --Python 3 文本的 交互式TUI。

快速开始

# Interactive TUI (default when running on a TTY)
hl7view message.hl7

# Pipe input
cat message.hl7 | hl7view

# From clipboard (requires xclip)
hl7view --clipboard

# Non-interactive table output
hl7view -v message.hl7

# Extract a single field (for scripting)
hl7view -f PID-5 message.hl7

python3 -m hl7view 如果您不想安装该软件包，也可以使用。

交互式TUI

当在没有输出模式标志的TTY上运行时，查看器会启动一个具有两个面板的交互式TUI：

附加覆盖：原始视图、文件浏览器、MLLP发送/响应拆分视图。

键盘快捷键（TUI）

非交互式输出

产生直接stdout输出（无TUI）的标志：

# Colored table with component breakdown
hl7view -v message.hl7

# Include empty fields
hl7view -v -e message.hl7

# Raw segment lines
hl7view --raw message.hl7

# Single field extraction
hl7view -f MSH-9 message.hl7

# Multiple files
hl7view file1.hl7 file2.hl7

# Disable colors (for piping)
hl7view --no-color message.hl7

# Compare two messages (field-level diff)
hl7view file1.hl7 file2.hl7 --diff

# Include identical fields in diff output
hl7view file1.hl7 file2.hl7 --diff -e

匿名化

匿名化PHI承载段字段（PID、NK1、GT1、IN1、MRG——姓名、ID、DOB、地址、电话号码、SSN）：

# ASCII name pool
hl7view --anon message.hl7

# Estonian name pool (with non-ASCII characters: Õ, Ö, Ü, Ä, Ž, Š)
hl7view --anon-non-ascii message.hl7

在TUI，按 a 切换匿名化和 n 切换名称池。按 t 将非ASCII字符音译为ASCII等效字符。当存在未保存的字段编辑时，匿名化被阻止——请先保存或放弃编辑。

MLLP发送

向远程MLLP端点发送消息并显示响应：

# Basic send (waits for ACK)
hl7view message.hl7 --send host:6001

# Fire and forget
hl7view message.hl7 --send host:6001 --send-no-wait

# Custom timeout
hl7view message.hl7 --send host:6001 --send-timeout 30

# TLS
hl7view message.hl7 --send host:6002 --tls

# TLS with custom CA
hl7view message.hl7 --send host:6002 --tls-ca /path/to/ca.pem

# mTLS (client certificate)
hl7view message.hl7 --send host:6002 --tls-cert client.pem --tls-key client-key.pem

# TLS without certificate verification
hl7view message.hl7 --send host:6002 --tls-insecure

在TUI，按 s 并输入目标。追加 --tls 或 --tls-insecure 到主机：端口：

localhost:6001              plain TCP
host:6002 --tls             TLS with system CA
host:6002 --tls-insecure    TLS without cert verification

对于需要客户端证书的端点，请在以下位置创建配置文件 ~/.config/hl7view/tls.conf:

[mllp.hospital.example:6002]
ca_cert = /opt/certs/ca.pem
client_cert = /opt/certs/client.pem
client_key = /opt/certs/client-key.pem

[test.local:6003]
tls = true
insecure = true

当发送到已配置的主机：端口时，TUI会自动应用匹配的配置。

MCP服务器

文件： hl7view/mcp_server.py --通过以下方式将HL7工具暴露给LLM代理 模型上下文协议.

设置

pip install -e .

或者没有包装： pip install -r requirements-mcp.txt

注册（克劳德代码）

之后 pip install -e .，向CLI注册：

claude mcp add hl7 -- /path/to/hl7-tools/venv/bin/hl7view-mcp --transport stdio

或手动添加到 ~/.claude.json 在...之下 mcpServers:

"hl7": {
  "type": "stdio",
  "command": "/path/to/hl7-tools/venv/bin/hl7view-mcp",
  "args": ["--transport", "stdio"],
  "cwd": "/path/to/hl7-tools",
  "env": {}
}

这 cwd 必须指向repo根目录，以便服务器可以找到 samples/ 和 profiles/.

何时使用MCP与原始Claude

Raw-Claude擅长直接读取常见的HL7段（PID、MSH、OBR）。MCP工具在以下方面最有价值：

• 匿名/转换/发送 --Claude无法对原始文本执行的操作
• 验证 --配置文件驱动的检查（必填字段、值映射）
• 解释 --克劳德可能产生幻觉的罕见领域（PV1-36、ORC-14）的精确定义
• 差异 --两条消息的逐字段结构化比较

工具

资源

集成配置文件

这两个查看器都支持集成配置文件——JSON文件，将自定义字段名、描述、注释和值映射叠加到解析的视图上。与一起使用时 hl7_validate，配置文件还驱动验证：所需的字段检查和值图执行。

• Web查看器： 通过工具栏加载 负载配置文件 按钮
• 终端查看器： hl7view --profile profiles/sample-profile.json message.hl7
• MCP服务器： 将配置文件名称传递给 hl7_parse 或 hl7_validate

看 profiles/sample-profile.json 对于记录的模式。

配置文件架构摘要：

{
  "name": "Integration Name",
  "description": "Optional description",
  "segments": {
    "MSH": {
      "description": "Custom segment description",
      "fields": {
        "9": {
          "customName": "Override field name",
          "required": true,
          "description": "Field description shown in detail panel",
          "notes": "Implementation notes",
          "valueMap": { "ADT^A01": "Admission", "ADT^A08": "Update" }
        }
      }
    },
    "ZDS": {
      "description": "Custom Z-segment",
      "custom": true,
      "fields": { ... }
    }
  }
}

配置文件验证（web查看器：内联图标+摘要栏；MCP服务器： hl7_validate 具有配置文件参数）：

• required: true --如果字段为空，则标记错误（红色指示器）
• valueMap --如果字段值不是预期的编码值之一，则发出警告（橙色指示器）
• 缺失的片段 --配置文件定义了消息中不存在的段（摘要栏）

示例消息

这 samples/ 目录包含测试消息：

• adt-a01-admit-v25.hl7 --ADT^A01录取通知书（v2.5）
• orm-o01-order-v23.hl7 --ORM^O01订单（v2.3）
• oru-r01-lab-v25.hl7 --ORU^R01实验室结果（v2.5）
• oru-r01-lab-v28.hl7 --ORU^R01 CBC实验室结果（v2.8），SFT、SPM、执行组织

许可证

麻省理工学院