load-dicom-series

Load DICOM medical image series into memory using Series UID for processing in the DICOM-MCP server system.

Instructions

Load a DICOM series into memory for processing

Input Schema

TableJSON Schema

Name	Required	Description	Default
`series_uid`	Yes	Series UID of the DICOM series to load

Implementation Reference

src/dicom_mcp/server.py:296-324 (handler)

The handler function for the 'load-dicom-series' tool within the @server.call_tool() dispatcher. It validates the series_uid argument, retrieves the corresponding DicomSeries from dicom_data, loads the image data using the load_dicom_image helper, caches the numpy array and metadata, computes shape and intensity range, and returns a text content summary.

elif name == "load-dicom-series":
    series_uid = arguments.get("series_uid")
    if not series_uid or series_uid not in dicom_data:
        raise ValueError(f"Invalid or unknown series UID: {series_uid}")
        
    series = dicom_data[series_uid]
    
    # Load the DICOM series
    image_array, metadata = load_dicom_image(series.path)
    
    # Cache the loaded data
    dicom_cache[series_uid] = {
        "image": image_array,
        "metadata": metadata
    }
    
    # Return summary information
    shape = image_array.shape
    intensity_range = (float(image_array.min()), float(image_array.max()))
    
    return [
        types.TextContent(
            type="text",
            text=f"Loaded DICOM series {series_uid}\n" +
                 f"Shape: {shape}\n" +
                 f"Intensity range: {intensity_range}\n" +
                 f"Metadata: {json.dumps(metadata, indent=2, default=str)}"
        )
    ]

src/dicom_mcp/server.py:188-198 (registration)

The tool registration in the @server.list_tools() handler, defining the tool name, description, and input JSON schema requiring 'series_uid'.

types.Tool(
    name="load-dicom-series",
    description="Load a DICOM series into memory for processing",
    inputSchema={
        "type": "object",
        "properties": {
            "series_uid": {"type": "string", "description": "Series UID of the DICOM series to load"},
        },
        "required": ["series_uid"],
    },
),

src/dicom_mcp/dicom_tools.py:118-142 (helper)

Helper function that performs the actual DICOM series loading using ITK to read the series directory into a 3D numpy array and extracts geometric metadata (size, spacing, origin, direction). Called by the tool handler.

def load_dicom_image(series_path: str) -> Tuple[np.ndarray, Dict[str, Any]]:
    """Load a DICOM series into a 3D numpy array and metadata dictionary"""
    try:
        # Use ITK to read the DICOM series
        itk_image = itk.imread(series_path, itk.F)
        
        # Convert to numpy array
        np_array = itk.GetArrayFromImage(itk_image)
        
        # Extract metadata
        size = itk_image.GetLargestPossibleRegion().GetSize()
        spacing = itk_image.GetSpacing()
        origin = itk_image.GetOrigin()
        direction = itk_image.GetDirection().GetVnlMatrix().as_matrix().flatten().tolist()
        
        metadata = {
            "size": (int(size[0]), int(size[1]), int(size[2])),
            "spacing": (float(spacing[0]), float(spacing[1]), float(spacing[2])),
            "origin": (float(origin[0]), float(origin[1]), float(origin[2])),
            "direction": direction
        }
        
        return np_array, metadata
    except Exception as e:
        raise RuntimeError(f"Failed to load DICOM image: {e}")

src/dicom_mcp/dicom_tools.py:38-47 (schema)

Pydantic model used to represent and store DICOM series information, including the path used for loading and series_uid as key in server state.

class DicomSeries(BaseModel):
    """Model representing a DICOM series"""
    series_uid: str
    study_uid: Optional[str] = None
    modality: str
    description: Optional[str] = None
    path: str
    file_count: int
    patient_id: Optional[str] = None

DICOM-MCP