Orthanc MCP

Orthanc DICOM查询和PDF提取API

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

它提供了一组干净、结构化的工具，用于导航DICOM层次结构：

患者→ 研究→ 系列→ 实例→ PDF提取

______________________________________________________________________

✨ 特性

• 🔍 查询患者 按姓名、ID或出生日期
• 📂 查询研究 对于患者（CT、MRI、X射线等）
• 🌀 查询系列 在研究中（阶段、序列、重建）
• 📑 查询实例 系列内（单个DICOM对象）
• 📖 提取PDF文本 来自封装的DICOM报告

所有工具均通过以下方式暴露 FastMCP 并且可以以编程方式或交互方式消费。

______________________________________________________________________

📂 项目结构

orthanc_mcp/
├── main.py                # Entry point: starts FastMCP server
├── config.py              # Environment variables & constants
├── orthanc_client.py      # Helper functions for Orthanc REST API
├── tools/
│   ├── __init__.py        # Makes tools importable
│   ├── patients.py        # query_patients tool
│   ├── studies.py         # query_studies tool
│   ├── series.py          # query_series tool
│   ├── instances.py      # query_instances tool
│   └── pdf_extract.py    # extract_pdf_text_from_dicom tool
└── requirements.txt       # Python dependencies

______________________________________________________________________

⚙️ 安装

1. 克隆存储库

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

1. 安装依赖项

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

1. 配置环境变量

创建一个 .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层次结构：

1. 患者 → query_patients
2. 研究 → query_studies(patient_id=...)
3. 系列 → query_series(study_id=...)
4. 实例 → query_instances(series_id=...)
5. 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")

# Step 1: Find patient
patients = client.call("query_patients", {"name": "Smith"})
patient_id = patients[0]["PatientID"]

# Step 2: Find studies
studies = client.call("query_studies", {"patient_id": patient_id})
study_id = studies[0]["OrthancStudyID"]

# Step 3: Find series
series = client.call("query_series", {"study_id": study_id})
series_id = series[0]["OrthancSeriesID"]

# Step 4: Find instances
instances = client.call("query_instances", {"series_id": series_id})
instance_id = instances[0]["OrthancInstanceID"]

# Step 5: Extract PDF text
pdf_text = client.call(
    "extract_pdf_text_from_dicom",
    {"instance_id": instance_id}
)

print(pdf_text)

______________________________________________________________________

🛠️ 依赖项

• FastMCP
• 请求：
• pydicom
• PyPDF2
• python dotenv

______________________________________________________________________

📌 备注

• Orthanc必须正在运行，并且可以在配置的 ORTHANC_URL.
• PDF提取仅适用于 封装PDF SOP类:

1.2.840.10008.5.1.4.1.1.104.1

• 如果PDF没有文本层（例如扫描图像），提取将返回警告或空结果。

______________________________________________________________________

🤝 贡献

欢迎拉取请求！

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

______________________________________________________________________

👥 贡献者

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

• Shruti Gawade女士
• 普拉纳夫·马哈迪克勋爵