modify_diagram

Instructions

Implementation Reference

• src/excalidraw_mcp/server.py:187-281 (handler)

  The modify_diagram tool handler function registered with @mcp.tool. Parses raw operation dicts into typed ModifyOperation objects (AddNodeOp, RemoveNodeOp, etc.) then delegates to apply_modifications().

  def modify_diagram(
      file_path: str,
      operations: list[dict[str, Any]],
      theme: str = "default",
  ) -> str:
      """Modify an existing Excalidraw diagram created by this tool.
  
      Supports iterative editing: add components, remove nodes, update labels,
      and rewire connections - without recreating the entire diagram.
  
      IMPORTANT: Call get_diagram_info first to understand the current diagram
      state before making modifications.
  
      Args:
          file_path: Path to the existing .excalidraw file.
          operations: Ordered list of operations. Each dict has:
              - op: "add_node" | "remove_node" | "update_node" |
                    "add_connection" | "remove_connection"
  
              For add_node:
                - id (str): New node identifier
                - label (str): Display text
                - component_type (str, optional): Technology for auto-styling
                - shape (str, optional): Shape override
                - near (str, optional): Place near this existing node id
  
              For remove_node:
                - id (str): Node to remove (also removes its connections)
  
              For update_node:
                - id (str): Node to update
                - label (str, optional): New label
                - component_type (str, optional): New component type
  
              For add_connection:
                - from_id (str): Source node id
                - to_id (str): Target node id
                - label (str, optional): Edge label
  
              For remove_connection:
                - from_id (str): Source node id
                - to_id (str): Target node id
  
          theme: Color theme for re-rendering. Default: "default"
  
      Returns:
          Summary of applied modifications.
      """
      parsed_ops: list[ModifyOperation] = []
      for op_dict in operations:
          op_type = op_dict.get("op", "")
          match op_type:
              case "add_node":
                  parsed_ops.append(
                      AddNodeOp(
                          id=op_dict["id"],
                          label=op_dict.get("label", op_dict["id"]),
                          component_type=op_dict.get("component_type"),
                          shape=(
                              ShapeType(op_dict["shape"])
                              if "shape" in op_dict
                              else ShapeType.RECTANGLE
                          ),
                          near=op_dict.get("near"),
                      )
                  )
              case "remove_node":
                  parsed_ops.append(RemoveNodeOp(id=op_dict["id"]))
              case "update_node":
                  parsed_ops.append(
                      UpdateNodeOp(
                          id=op_dict["id"],
                          label=op_dict.get("label"),
                          component_type=op_dict.get("component_type"),
                      )
                  )
              case "add_connection":
                  parsed_ops.append(
                      AddConnectionOp(
                          from_id=op_dict["from_id"],
                          to_id=op_dict["to_id"],
                          label=op_dict.get("label"),
                      )
                  )
              case "remove_connection":
                  parsed_ops.append(
                      RemoveConnectionOp(
                          from_id=op_dict["from_id"],
                          to_id=op_dict["to_id"],
                      )
                  )
              case _:
                  return f"Error: Unknown operation type '{op_type}'"
  
      return apply_modifications(file_path, parsed_ops, theme=theme)

• src/excalidraw_mcp/core/models.py:178-222 (schema)

  Defines the typed operation models (AddNodeOp, RemoveNodeOp, UpdateNodeOp, AddConnectionOp, RemoveConnectionOp) and the ModifyOperation union type used by the modify_diagram tool.

  class AddNodeOp(BaseModel):
      """Operation to add a new node to an existing diagram."""
  
      op: str = "add_node"
      id: str
      label: str
      component_type: str | None = None
      shape: ShapeType = ShapeType.RECTANGLE
      near: str | None = None
  
  
  class RemoveNodeOp(BaseModel):
      """Operation to remove a node and its connections."""
  
      op: str = "remove_node"
      id: str
  
  
  class UpdateNodeOp(BaseModel):
      """Operation to update an existing node's properties."""
  
      op: str = "update_node"
      id: str
      label: str | None = None
      component_type: str | None = None
  
  
  class AddConnectionOp(BaseModel):
      """Operation to add a new connection between existing nodes."""
  
      op: str = "add_connection"
      from_id: str
      to_id: str
      label: str | None = None
  
  
  class RemoveConnectionOp(BaseModel):
      """Operation to remove a connection."""
  
      op: str = "remove_connection"
      from_id: str
      to_id: str
  
  
  ModifyOperation = AddNodeOp | RemoveNodeOp | UpdateNodeOp | AddConnectionOp | RemoveConnectionOp

• src/excalidraw_mcp/server.py:186-187 (registration)

  Registration of modify_diagram as an MCP tool via the @mcp.tool decorator on line 186.

  @mcp.tool
  def modify_diagram(

• src/excalidraw_mcp/parsers/state.py:120-168 (helper)

  The apply_modifications function that reads existing diagram metadata, applies each operation (add/remove/update nodes and connections), recomputes layout, and saves the updated .excalidraw file.

  def apply_modifications(
      file_path: str | Path,
      operations: list[ModifyOperation],
      theme: ThemeName | str = ThemeName.DEFAULT,
  ) -> str:
      """Apply a list of modification operations to an existing diagram.
  
      Returns a summary string describing what was changed.
      """
      meta = read_diagram_metadata(file_path)
      if meta is None:
          return (
              "Error: No excalidraw-architect-mcp metadata found in the file. "
              "Cannot modify a diagram not created by this tool."
          )
  
      changes: list[str] = []
  
      for op in operations:
          match op:
              case AddNodeOp():
                  _apply_add_node(meta, op)
                  changes.append(f"Added node '{op.id}' ({op.label})")
  
              case RemoveNodeOp():
                  _apply_remove_node(meta, op)
                  changes.append(f"Removed node '{op.id}'")
  
              case UpdateNodeOp():
                  _apply_update_node(meta, op)
                  changes.append(f"Updated node '{op.id}'")
  
              case AddConnectionOp():
                  _apply_add_connection(meta, op)
                  label_str = f" with label '{op.label}'" if op.label else ""
                  changes.append(f"Added connection {op.from_id} -> {op.to_id}{label_str}")
  
              case RemoveConnectionOp():
                  _apply_remove_connection(meta, op)
                  changes.append(f"Removed connection {op.from_id} -> {op.to_id}")
  
      graph = _metadata_to_graph(meta)
      layout = compute_layout(graph)
      doc = build_excalidraw_file(layout, theme_name=theme, direction=meta.direction)
      save_excalidraw(doc, file_path)
  
      summary = f"Applied {len(changes)} operation(s) to {Path(file_path).name}:\n"
      summary += "\n".join(f"  - {c}" for c in changes)
      return summary