Diagrams MCP Server

Instructions

Implementation Reference

• src/diagrams_mcp/tools/core.py:368-385 (registration)

  The @mcp.tool decorator that registers the 'create_diagram_with_custom_icons' tool, including name, description, and annotations.

  @mcp.tool(
      name="create_diagram_with_custom_icons",
      description="""Create diagrams with custom icons from web URLs or local files.
  
  USE WHEN: Brand logos (Stripe, Vercel, Supabase, Fly.io) not in diagrams library.
  GitHub avatars work well: https://avatars.githubusercontent.com/u/{org_id}
  
  Examples:
  URL: custom_nodes=[{"id":"stripe","icon_source":"url","icon_path":"https://avatars.githubusercontent.com/u/856813"}]
  Mixed: nodes=[{...AWS nodes...}], custom_nodes=[{...}], connections=[...]
  
  HTTPS-only for URLs, 5MB limit, PNG/JPG supported. Automatic caching.""",
      annotations={
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": True,
      },
  )

• src/diagrams_mcp/core/validators.py:50-96 (schema)

  Pydantic BaseModel CustomNodeDef defining the structure and validation for custom nodes used in the tool.

  class CustomNodeDef(BaseModel):
      """Definition of a custom node with icon from URL or local file."""
  
      id: str = Field(
          description="Unique node ID",
          min_length=1,
          max_length=200,
      )
      label: str = Field(
          description="Display label",
          min_length=1,
      )
      icon_source: Literal["url", "local"] = Field(description="Icon from web URL or local file")
      icon_path: str = Field(
          description="HTTPS URL or local file path",
          min_length=1,
      )
      cache_icons: bool = Field(
          default=True,
          description="Cache downloaded icons",
      )
  
      @field_validator("id")
      @classmethod
      def validate_id_format(cls, v: str) -> str:
          """Validate ID format."""
          if not re.match(r"^[a-zA-Z0-9_-]+$", v):
              raise ValueError(
                  f"Invalid node ID '{v}': only alphanumeric characters, "
                  "underscores, and hyphens allowed"
              )
          return v
  
      @field_validator("icon_path")
      @classmethod
      def validate_icon_path(cls, v: str, info) -> str:
          """Validate icon path format based on source type."""
          icon_source = info.data.get("icon_source")
  
          if icon_source == "url":
              if not v.startswith("https://"):
                  raise ValueError(f"Icon URL must start with 'https://', got: {v}")
          # For local paths, we'll validate existence at runtime
  
          return v

• src/diagrams_mcp/tools/core.py:386-566 (handler)

  The core handler function that executes the tool: loads custom icons, builds diagram using diagrams.Diagram and Custom, handles mixed standard/custom nodes, connections, outputs in multiple formats.

  async def create_diagram_with_custom_icons(
      name: Annotated[str, Field(description="Diagram title")],
      custom_nodes: Annotated[
          List[CustomNodeDef], Field(description="Custom nodes with icon URLs/paths")
      ],
      connections: Annotated[List[ConnectionDef], Field(description="Connections between nodes")],
      nodes: Annotated[
          Optional[List[NodeDef]],
          Field(description="Optional standard provider nodes to mix with custom"),
      ] = None,
      clusters: Annotated[Optional[List[ClusterDef]], Field(description="Optional clusters")] = None,
      direction: Annotated[
          Literal["LR", "RL", "TB", "BT"], Field(description="Layout direction")
      ] = "LR",
      curvestyle: Annotated[Literal["ortho", "curved"], Field(description="Edge style")] = "ortho",
      output_format: Annotated[
          str | List[str], Field(description="Output format(s): png, pdf, jpg, dot")
      ] = "png",
      output_dir: Annotated[
          Optional[str],
          Field(
              description="Output directory (default: current directory). Auto-created if missing."
          ),
      ] = None,
      graph_attr: Annotated[Optional[Dict[str, Any]], Field(description="Graph attributes")] = None,
      return_base64: Annotated[bool, Field(description="Return base64 images")] = False,
  ) -> str:
      """Generate diagram with custom node icons."""
      start_time = time.time()
  
      try:
          from diagrams.custom import Custom
  
          # Initialize icon manager
          icon_manager = IconManager()
  
          # Validate all custom icons and get paths
          custom_icon_paths = {}
          for custom_node in custom_nodes:
              try:
                  icon_path = icon_manager.get_icon_path(
                      custom_node.icon_source,
                      custom_node.icon_path,
                      cache=custom_node.cache_icons,
                  )
                  custom_icon_paths[custom_node.id] = icon_path
              except Exception as e:
                  return format_error(
                      f"Failed to load icon for node '{custom_node.id}': {str(e)}",
                      suggestion="Check icon_path is valid HTTPS URL or existing local file",
                  )
  
          # Build combined node ID set
          node_ids = {node.id for node in custom_nodes}
          if nodes:
              node_ids.update({node.id for node in nodes})
  
          # Validate connections
          for conn in connections:
              if conn.from_node not in node_ids:
                  raise ValueError(f"Connection references unknown node '{conn.from_node}'")
  
              targets = [conn.to_node] if isinstance(conn.to_node, str) else conn.to_node
              for target in targets:
                  if target not in node_ids:
                      raise ValueError(f"Connection references unknown node '{target}'")
  
          # Prepare output
          formats = [output_format] if isinstance(output_format, str) else output_format
  
          # Reject SVG - it's buggy and unsupported
          if any("svg" in fmt.lower() for fmt in formats):
              raise ValueError("SVG output is not supported. Use png, pdf, jpg, or dot instead.")
  
          # Change directory if needed
          original_dir = os.getcwd()
          if output_dir:
              os.makedirs(output_dir, exist_ok=True)
              os.chdir(output_dir)
  
          try:
              # Hide diagram title by setting label to empty string
              default_graph_attr = {"label": ""}
              merged_graph_attr = {**default_graph_attr, **(graph_attr or {})}
  
              with Diagram(
                  name=name,
                  show=False,
                  direction=direction,
                  curvestyle=curvestyle,
                  outformat=formats,
                  graph_attr=merged_graph_attr,
              ) as _:
                  # Create all nodes
                  node_objects = {}
  
                  # Create custom nodes
                  for custom_node in custom_nodes:
                      icon_path = custom_icon_paths[custom_node.id]
                      node_obj = Custom(custom_node.label, icon_path)
                      node_objects[custom_node.id] = node_obj
  
                  # Create standard nodes if provided
                  if nodes:
                      for node in nodes:
                          NodeClass = import_node_class(node.provider, node.category, node.type)
                          node_obj = NodeClass(node.label)
                          node_objects[node.id] = node_obj
  
                  # Create connections
                  edge_count = 0
                  for conn in connections:
                      from_obj = node_objects[conn.from_node]
                      targets = [conn.to_node] if isinstance(conn.to_node, str) else conn.to_node
  
                      for target in targets:
                          to_obj = node_objects[target]
  
                          if conn.label or conn.color or conn.style:
                              edge = Edge(
                                  label=conn.label or "",
                                  color=conn.color or "black",
                                  style=conn.style or "solid",
                              )
                              if conn.direction == "forward":
                                  _ = from_obj >> edge >> to_obj
                              elif conn.direction == "reverse":
                                  _ = from_obj << edge << to_obj
                              else:
                                  _ = from_obj - edge - to_obj
                          else:
                              if conn.direction == "forward":
                                  _ = from_obj >> to_obj
                              elif conn.direction == "reverse":
                                  _ = from_obj << to_obj
                              else:
                                  _ = from_obj - to_obj
  
                          edge_count += 1
  
              # Get file paths
              diagram_filename = name.replace(" ", "_").replace("-", "_").lower()
              file_paths = []
              for fmt in formats:
                  file_path = f"{diagram_filename}.{fmt}"
                  if output_dir:
                      file_path = os.path.join(output_dir, file_path)
                  file_paths.append(os.path.abspath(file_path))
  
              # Build metadata
              generation_time_ms = (time.time() - start_time) * 1000
              total_nodes = len(custom_nodes) + (len(nodes) if nodes else 0)
              metadata = build_diagram_metadata(
                  file_paths,
                  node_count=total_nodes,
                  edge_count=edge_count,
                  cluster_count=len(clusters) if clusters else 0,
                  generation_time_ms=generation_time_ms,
              )
  
              # Base64 encoding if requested
              base64_images = None
              if return_base64:
                  base64_images = {}
                  for path in file_paths:
                      ext = Path(path).suffix[1:]
                      if ext != "dot":
                          try:
                              base64_images[ext] = encode_file_base64(path)
                          except Exception:
                              pass
  
              return format_diagram_result(file_paths, metadata, base64_images)
  
          finally:
              if output_dir:
                  os.chdir(original_dir)
  
      except Exception as e:
          return format_error(f"Failed to generate diagram with custom icons: {str(e)}")

• src/diagrams_mcp/core/icon_manager.py:202-229 (helper)

  Key helper method in IconManager class used by the handler to resolve and validate custom icon paths from URL (with download/cache) or local files.

  def get_icon_path(
      self,
      icon_source: str,
      icon_path: str,
      cache: bool = True,
  ) -> str:
      """Get icon path, downloading from URL or validating local file.
  
      This is the main entry point for getting icon paths.
  
      Args:
          icon_source: Either "url" or "local"
          icon_path: URL or local file path
          cache: Whether to cache downloaded icons
  
      Returns:
          Absolute path to the icon file
  
      Raises:
          ValueError: If icon source is invalid or icon cannot be retrieved
      """
      if icon_source == "url":
          return self.download_icon(icon_path, cache=cache)
      elif icon_source == "local":
          return self.validate_local_icon(icon_path)
      else:
          raise ValueError(f"Invalid icon_source '{icon_source}'. Must be 'url' or 'local'")