DICOM-MCP

Instructions

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