Health Record Agent

这是一个可独立运行、可单独上传到 Git 的 Python 电子病历 Agent。目录中已经 包含运行所需的 Python 源码、依赖清单、环境变量模板和中文演示病历数据库， 不依赖原 health-record-mcp 项目的 Bun、Node.js 或 TypeScript 文件。

目录结构

Agent/
├── data/
│   └── chinese-demo-record.sqlite  # 中文 FHIR 演示病历
├── mcp/
│   ├── a2a_server.py               # A2A JSON-RPC 服务
│   ├── ehr_service.py              # 只读 SQLite 业务层
│   ├── eval_worker.py              # 受限表达式计算子进程
│   ├── file_service.py             # 受限文本文件读写层
│   ├── import_service.py           # CSV 校验、FHIR 转换与事务入库
│   ├── llm_agent.py                # A2A 使用的 LangChain Agent
│   └── mcp_server.py               # stdio/HTTP MCP 服务
├── .env.example
├── .gitignore
├── LICENSE.txt
├── main.py                         # 终端问答入口
└── requirements.txt

Related MCP server: MCP FHIR Server

环境要求

• Python 3.11 或更高版本

• 一个兼容 OpenAI Chat Completions API、并支持工具调用的模型服务

以下命令均在 Agent 目录中执行。

安装

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
Copy-Item .env.example .env

Linux/macOS：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env

编辑 .env，至少填写：

LLM_BASE_URL=https://your-openai-compatible-endpoint/v1
LLM_API_KEY=your-api-key
LLM_MODEL=your-tool-calling-model

默认数据库为 data/chinese-demo-record.sqlite。若要使用其他兼容数据库， 可将 EHR_DB_PATH 改为相对于本目录的路径或绝对路径。

运行终端问答 Agent

python main.py

可用命令：

• /clear：清空对话上下文

• /tools：显示 MCP 工具

• /exit：退出

终端 Agent 会自动通过 stdio 启动本目录中的 Python MCP 服务。

单独运行 MCP

stdio：

python mcp/mcp_server.py --transport stdio

Streamable HTTP：

python mcp/mcp_server.py --transport http --host 127.0.0.1 --port 8000

HTTP MCP 地址为 http://127.0.0.1:8000/mcp。

服务提供七个只读病历工具：

• get_patient_summary

• get_medication_review_context

• grep_record

• query_record

• eval_record

• read_resource

• read_attachment

药物审查应调用：

get_medication_review_context(patientId, asOf?)

该工具只读且严格限定到选定患者，返回 schema 1.0 的统一响应封装和稳定的 FHIR:<resourceType>/<id> 证据引用。它会明确列出 missingFields；这些字段表示 病历中“未记录”，不能解释为阴性或正常；缺少必需上下文时状态为 INSUFFICIENT_EVIDENCE，不会返回 OK。活动用药包含可识别的记录强度 strength。返回值不包含原始附件正文或 Base64。

例如，按患者编号获取截至指定日期的审查上下文：

get_medication_review_context(patientId="DEMO-P001", asOf="2026-08-31")

以及五个受控 CSV 导入/状态工具：

• validate_csv_from_url：从平台 MinIO 预签名 URL 下载 CSV 并生成 FHIR 预览。

• validate_csv_content：平台只提供附件正文时，接收完整 CSV 文本并生成 FHIR 预览。

• validate_csv_import：校验 uploads/inbox 中的宽表病例并生成 FHIR 预览。

• commit_csv_import：用户确认后将暂存资源事务写入 SQLite。

• get_import_status：查询导入状态、警告、错误和资源数量。

终端 Agent 和 A2A Agent 还会直接注册三个本地文件工具；这些工具不经过 MCP：

• list_files：列出文件根目录内的 CSV、JSON、TXT。

• read_text_file：分段读取文本，单文件最大 2 MB。

• write_text_file：原子写入文本，最大 1 MB；覆盖需显式确认。

本地文件根目录由 EHR_FILE_ROOT 配置，默认为 uploads。工具拒绝绝对路径、 上级目录、隐藏路径和其他扩展名，不能读取 .env 或修改 Python 源码。

本地 CSV 导入

默认上传目录为：

uploads/
├── inbox/       # 新上传、等待校验
├── processing/  # 已校验、等待用户确认
├── archived/    # 已成功写入数据库
├── failed/      # 格式或字段校验失败
└── reports/     # 每个任务的 JSON 校验报告

文件应先完整写入 inbox。本地 write_text_file 使用临时文件和原子替换， 不会让导入器读到半个 CSV。调用 validate_csv_import 后，文件会移动到 processing 或 failed；只有用户看过预览并明确确认后，Agent 才能调用 commit_csv_import。数据库提交成功后，原始文件移动到 archived。

当前支持一行一份门诊病历的中文宽表，必填列为 病历编号、患者姓名、 性别、就诊日期。建议同时提供 患者编号 和 出生日期；缺少患者编号时 只生成临时哈希 ID，并返回警告。每行可生成 Patient、Encounter、Composition、 Condition、体温 Observation 和血压 Observation。

导入使用 SHA-256 防止相同文件重复处理；正式资源在一个 SQLite 事务内写入。 遇到同 ID、不同内容的资源默认拒绝覆盖。多患者数据库调用 get_patient_summary 时必须传入 patientId，防止患者数据混用。 未识别的 CSV 列不会静默丢弃：校验结果会列出这些字段，并将每行原始内容 保存在 import_job_rows.raw_json 中，便于后续补充映射和审计。

从宿主平台接收上传文件

宿主平台需要把上传接口返回的 MinIO filepath 和原始文件名作为 MCP 工具 参数提供给模型。用户要求导入上传的 CSV 时，模型调用：

validate_csv_from_url(fileUrl=<附件 filepath>, fileName=<附件原始文件名>)

MCP 服务会把文件原子下载到 uploads/inbox，随后复用本地 CSV 校验流程。 fileUrl 的主机必须出现在 EHR_UPLOAD_ALLOWED_HOSTS 中；多个主机用英文逗号 分隔，例如同一 Docker 网络使用 EHR_UPLOAD_ALLOWED_HOSTS=minio。工具禁止 跨主机重定向，下载大小上限与本地 CSV 导入一致，当前为 2 MB。

如果宿主平台只把附件正文放入模型上下文而不提供 filepath，模型应改为调用：

validate_csv_content(fileName=<附件原始文件名>, csvContent=<完整原始 CSV 正文>)

csvContent 必须包含表头和全部数据行，不得总结、补写或改写。它可以是原始 CSV， 也可以是宿主平台解析附件后生成的 Markdown 表格；MCP 会按必填病历表头识别并 规范化表格，包括平台将数据行放在表头之前的情况。如果平台完全丢失表头，只有 Markdown 分隔行存在且每条记录严格匹配本服务规定的20列模板时，MCP才会补回 标准表头；列数不符或普通管道文本仍会拒绝。此兼容路径受模型上下文长度限制， 适合小型 CSV；大文件仍应优先使用 validate_csv_from_url。

运行 A2A Agent

python mcp/a2a_server.py --host 127.0.0.1 --port 9999

端点：

• Agent Card：http://127.0.0.1:9999/.well-known/agent-card.json

• A2A JSON-RPC：http://127.0.0.1:9999/a2a

安全说明

• 病历查询连接以只读模式打开，SQL 查询也受 SQLite authorizer 限制。

• CSV 导入使用独立读写连接和固定参数化语句，不接受任意写 SQL。

• eval_record 仅接受 AST 白名单中的 Python 表达式，但它不是操作系统级 强沙箱。

• 未配置 TLS、身份认证和请求限制时，不要把 HTTP MCP 或 A2A 服务直接暴露 到公网。

• Agent 会把相关工具结果发送到 LLM_BASE_URL。接入真实病历前，请确认模型 服务的数据隔离、访问控制、日志留存和合规策略。

• .env 已被 Git 忽略，请勿提交 API Key。目录内的 SQLite 文件是演示数据； 替换为真实病历后应根据组织政策决定是否提交。

上传为独立 Git 仓库

git init
git add .
git status
git commit -m "Initial health record agent"