dicom-mcp: un servidor de protocolo de contexto de modelo DICOM

Este repositorio es parte de una publicación de blog: LLM de Agentic Healthcare

Descripción general

Un servidor de Protocolo de Contexto de Modelo para interacciones DICOM (Imágenes Digitales y Comunicaciones en Medicina). Este servidor proporciona herramientas para consultar e interactuar con servidores DICOM, lo que permite que los Modelos de Lenguaje Grandes accedan y analicen metadatos de imágenes médicas.

dicom-mcp permite a los asistentes de IA consultar información de pacientes, estudios, series e instancias desde servidores DICOM mediante protocolos de red DICOM estándar. También permite extraer texto de documentos PDF encapsulados en formato DICOM, lo que permite analizar informes clínicos. Está basado en pynetdicom y sigue la especificación del Protocolo de Contexto de Modelo.

Herramientas

list_dicom_nodes
- Enumera todos los nodos DICOM configurados y los títulos AE que los llaman
- Entradas: Ninguna
- Devuelve: nodo actual, nodos disponibles, título de AE que realiza la llamada actual y títulos de AE que realizan la llamada disponibles
switch_dicom_node
- Cambia a un nodo DICOM configurado diferente
- Entradas:
  - node_name (cadena): Nombre del nodo al que cambiar
- Devoluciones: Mensaje de éxito
switch_calling_aet
- Cambia a un título de AE de llamada configurado diferente
- Entradas:
  - aet_name (cadena): Nombre del título AE que llama al que se cambiará
- Devoluciones: Mensaje de éxito
verify_connection
- Prueba la conectividad con el nodo DICOM configurado mediante C-ECHO
- Entradas: Ninguna
- Devuelve: Mensaje de éxito o fracaso con detalles
query_patients
- Búsqueda de pacientes que coincidan con los criterios especificados
- Entradas:
  - name_pattern (cadena, opcional): Patrón de nombre del paciente (puede incluir comodines)
  - patient_id (cadena, opcional): ID del paciente
  - birth_date (cadena, opcional): Fecha de nacimiento del paciente (AAAAMMDD)
  - attribute_preset (cadena, opcional): nivel de detalle preestablecido (mínimo, estándar, extendido)
  - additional_attributes (string[], opcional): atributos DICOM adicionales para incluir
  - exclude_attributes (string[], opcional): atributos DICOM a excluir
- Devuelve: Matriz de registros de pacientes coincidentes
query_studies
- Búsqueda de estudios que coincidan con los criterios especificados
- Entradas:
  - patient_id (cadena, opcional): ID del paciente
  - study_date (cadena, opcional): Fecha o rango del estudio (AAAAMMDD o AAAAMMDD-AAAAMMDD)
  - modality_in_study (cadena, opcional): Modalidades en estudio
  - study_description (cadena, opcional): Descripción del estudio (puede incluir comodines)
  - accession_number (cadena, opcional): Número de acceso
  - study_instance_uid (cadena, opcional): UID de la instancia de estudio
  - attribute_preset (cadena, opcional): Nivel de detalle preestablecido
  - additional_attributes (string[], opcional): atributos DICOM adicionales para incluir
  - exclude_attributes (string[], opcional): atributos DICOM a excluir
- Devuelve: Matriz de registros de estudio coincidentes
query_series
- Búsqueda de series dentro de un estudio
- Entradas:
  - study_instance_uid (cadena): UID de la instancia de estudio (obligatorio)
  - modality (cadena, opcional): Modalidad (p. ej., "CT", "MR")
  - series_number (cadena, opcional): Número de serie
  - series_description (cadena, opcional): Descripción de la serie
  - series_instance_uid (cadena, opcional): UID de instancia de serie
  - attribute_preset (cadena, opcional): Nivel de detalle preestablecido
  - additional_attributes (string[], opcional): atributos DICOM adicionales para incluir
  - exclude_attributes (string[], opcional): atributos DICOM a excluir
- Devuelve: Matriz de registros de series coincidentes
query_instances
- Buscar instancias dentro de una serie
- Entradas:
  - series_instance_uid (cadena): UID de instancia de serie (obligatorio)
  - instance_number (cadena, opcional): Número de instancia
  - sop_instance_uid (cadena, opcional): UID de instancia de SOP
  - attribute_preset (cadena, opcional): Nivel de detalle preestablecido
  - additional_attributes (string[], opcional): atributos DICOM adicionales para incluir
  - exclude_attributes (string[], opcional): atributos DICOM a excluir
- Devuelve: Matriz de registros de instancia coincidentes
get_attribute_presets
- Enumera los ajustes preestablecidos de atributos disponibles para las consultas
- Entradas: Ninguna
- Devuelve: Diccionario de ajustes preestablecidos disponibles y sus atributos por nivel
retrieve_instance

Recupera una instancia DICOM específica y la guarda en el sistema de archivos local
Entradas:
- study_instance_uid (cadena): UID de la instancia de estudio
- series_instance_uid (cadena): UID de instancia de serie
- sop_instance_uid (cadena): UID de instancia de SOP
- output_directory (cadena, opcional): Directorio donde guardar la instancia recuperada (predeterminado: "./retrieved_files")
Devuelve: Diccionario con información sobre la operación de recuperación

extract_pdf_text_from_dicom

Recupera una instancia DICOM que contiene un PDF encapsulado y extrae su contenido de texto
Entradas:
- study_instance_uid (cadena): UID de la instancia de estudio
- series_instance_uid (cadena): UID de instancia de serie
- sop_instance_uid (cadena): UID de instancia de SOP
Devuelve: Diccionario con información de texto extraída y estado

Instalación

Prerrequisitos

Python 3.12 o superior
Un servidor DICOM al que conectarse (por ejemplo, Orthanc, dcm4chee, etc.)

Usando pip

Instalar mediante pip:

pip install dicom-mcp

Configuración

dicom-mcp requiere un archivo de configuración YAML que define los nodos DICOM y los títulos de AE de llamada. Cree un archivo de configuración con la siguiente estructura:

# DICOM nodes configuration
nodes:
  orthanc:
    host: "localhost"
    port: 4242
    ae_title: "ORTHANC"
    description: "Local Orthanc DICOM server"
  
  clinical:
    host: "pacs.hospital.org"
    port: 11112
    ae_title: "CLIN_PACS"
    description: "Clinical PACS server"

# Local calling AE titles
calling_aets:
  default:
    ae_title: "MCPSCU"
    description: "Default calling AE title"
  
  modality:
    ae_title: "MODALITY"
    description: "Simulating a modality"

# Currently selected node
current_node: "orthanc"

# Currently selected calling AE title
current_calling_aet: "default"

Uso

Línea de comandos

Ejecute el servidor utilizando el punto de entrada del script:

dicom-mcp /path/to/configuration.yaml

Si utiliza uv:

uv run dicom-mcp /path/to/configuration.yaml

Configuración con Claude Desktop

Agregue esto a su claude_desktop_config.json :

"mcpServers": {
  "dicom": {
    "command": "uv",
    "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
  }
}

Uso con Zed

Añade a tu configuración Zed settings.json:

"context_servers": [
  "dicom-mcp": {
    "command": {
      "path": "uv",
      "args": ["--directory", "/path/to/dicom-mcp", "run", "dicom-mcp", "/path/to/configuration.yaml"]
    }
  }
],

Consultas de ejemplo

Lista de nodos DICOM disponibles

list_dicom_nodes()

Cambiar a un nodo diferente

switch_dicom_node(node_name="clinical")

Cambiar a un título de AE de llamada diferente

switch_calling_aet(aet_name="modality")

Verificar la conexión

verify_connection()

Búsqueda de pacientes

# Search by name pattern (using wildcard)
patients = query_patients(name_pattern="SMITH*")

# Search by patient ID
patients = query_patients(patient_id="12345678")

# Get detailed information
patients = query_patients(patient_id="12345678", attribute_preset="extended")

Búsqueda de estudios

# Find all studies for a patient
studies = query_studies(patient_id="12345678")

# Find studies within a date range
studies = query_studies(study_date="20230101-20231231")

# Find studies by modality
studies = query_studies(modality_in_study="CT")

Búsqueda de series en un estudio

# Find all series in a study
series = query_series(study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1")

# Find series by modality and description
series = query_series(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    modality="CT",
    series_description="CHEST*"
)

Buscar instancias en una serie

# Find all instances in a series
instances = query_instances(series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2")

# Find a specific instance by number
instances = query_instances(
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    instance_number="1"
)

Recuperar una instancia DICOM

# Retrieve a specific instance
result = retrieve_instance(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.2.1.3",
    output_directory="./dicom_files"
)

Extraer texto de un PDF encapsulado DICOM

# Extract text from an encapsulated PDF
result = extract_pdf_text_from_dicom(
    study_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.1",
    series_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.2",
    sop_instance_uid="1.2.840.10008.5.1.4.1.1.104.1.3"
)

Depuración

Puede utilizar el inspector MCP para depurar el servidor:

npx @modelcontextprotocol/inspector uv --directory /path/to/dicom-mcp run dicom-mcp /path/to/configuration.yaml

Desarrollo

Configurar el entorno de desarrollo

Clonar el repositorio:
git clone https://github.com/yourusername/dicom-mcp.git cd dicom-mcp
Crear un entorno virtual:
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
Instalar dependencias:
pip install -e .

Ejecución de pruebas

Las pruebas requieren un servidor Orthanc en ejecución. Puedes iniciar uno usando Docker:

cd tests
docker-compose up -d

A continuación ejecute las pruebas:

pytest tests/test_dicom_mcp.py

Para probar la funcionalidad de extracción de PDF:

pytest tests/test_dicom_pdf.py

Estructura del proyecto

src/dicom_mcp/ : Paquete principal
- __init__.py : Inicialización del paquete
- __main__.py : Punto de entrada
- server.py : implementación del servidor MCP
- dicom_client.py : implementación del cliente DICOM
- attributes.py : ajustes preestablecidos de atributos DICOM
- config.py : Gestión de configuración con Pydantic

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

Construido en pynetdicom
Sigue la especificación del Protocolo de Contexto de Modelo
Utiliza PyPDF2 para la extracción de texto PDF

DICOM MCP Server

Integrations