JinDaGe - orthanc-mcp MCP Details

article

README

🚀 Orthanc DICOM查询与PDF提取API

本项目提供了一个模块化的FastMCP服务器，用于查询Orthanc DICOM服务器并从封装的PDF报告中提取文本。

它提供了一套简洁、结构化的工具，用于遍历DICOM层级结构：

患者 → 检查 → 序列 → 实例 → PDF提取

✨ 主要特性

🔍 按姓名、ID或出生日期查询患者
📂 查询患者的检查信息（CT、MRI、X光等）
🌀 查询检查内的序列（阶段、序列、重建）
📑 查询序列内的实例（单个DICOM对象）
📖 从封装的DICOM报告中提取PDF文本

所有工具都通过FastMCP暴露，可以通过编程方式或交互式方式使用。

📦 安装指南

克隆仓库

git clone https://github.com/yourusername/orthanc-mcp.git
cd orthanc-mcp

安装依赖

python -m venv venv
venv\Scripts\Activate
pip install -r requirements.txt

配置环境变量 创建一个 .env 文件：

ORTHANC_URL=http://localhost:8042
MCP_HOST=localhost
MCP_PORT=5050

🚀 快速开始

运行服务器：

python main.py

FastMCP服务器将启动并暴露以下工具：

query_patients
query_studies
query_series
query_instances
extract_pdf_text_from_dicom

📚 详细文档

🔄 工作流程

这些工具必须按照自上而下的顺序调用，遵循DICOM层级结构：

患者 → query_patients
检查 → query_studies(patient_id=...)
序列 → query_series(study_id=...)
实例 → query_instances(series_id=...)
PDF提取 → extract_pdf_text_from_dicom(instance_id=...)

📊 序列流程图

flowchart TD
    A[query_patients] --> B[query_studies]
    B --> C[query_series]
    C --> D[query_instances]
    D --> E[extract_pdf_text_from_dicom]

此图展示了访问和提取PDF报告所需的层级导航。

📖 使用示例

from mcp.client import MCPClient

client = MCPClient("http://localhost:5050")

# 步骤1: 查找患者
patients = client.call("query_patients", {"name": "Smith"})
patient_id = patients[0]["PatientID"]

# 步骤2: 查找检查
studies = client.call("query_studies", {"patient_id": patient_id})
study_id = studies[0]["OrthancStudyID"]

# 步骤3: 查找序列
series = client.call("query_series", {"study_id": study_id})
series_id = series[0]["OrthancSeriesID"]

# 步骤4: 查找实例
instances = client.call("query_instances", {"series_id": series_id})
instance_id = instances[0]["OrthancInstanceID"]

# 步骤5: 提取PDF文本
pdf_text = client.call(
    "extract_pdf_text_from_dicom",
    {"instance_id": instance_id}
)

print(pdf_text)

🔧 技术细节

🛠️ 依赖项

FastMCP
requests
pydicom
PyPDF2
python-dotenv

📌 注意事项

Orthanc必须正在运行，并且可以通过配置的 ORTHANC_URL 访问。
PDF提取仅适用于封装的PDF SOP类： 1.2.840.10008.5.1.4.1.1.104.1
如果PDF没有文本层（例如扫描图像），提取将返回警告或空结果。

🤝 贡献说明

欢迎提交拉取请求！

对于重大更改，请先开一个问题讨论您想要更改的内容。

👥 贡献者

感谢以下为该项目做出贡献的人员：

orthanc-mcp