validate_diagram_spec

Instructions

Implementation Reference

• src/diagrams_mcp/tools/core.py:854-921 (handler)

  The main asynchronous handler function that executes the tool's validation logic: checks node references, connection validity, cluster memberships, collects errors and warnings, and formats the output.

  async def validate_diagram_spec(
      nodes: Annotated[List[NodeDef], Field(description="Nodes to validate")],
      connections: Annotated[List[ConnectionDef], Field(description="Connections to validate")],
      clusters: Annotated[
          Optional[List[ClusterDef]], Field(description="Clusters to validate")
      ] = None,
  ) -> str:
      """Validate diagram specification."""
      errors = []
      warnings = []
  
      try:
          # Validate nodes
          node_ids = {node.id for node in nodes}
  
          for node in nodes:
              try:
                  validate_node_reference(node.provider, node.category, node.type)
              except ValueError as e:
                  errors.append(f"Node '{node.id}': {str(e)}")
  
          # Validate connections
          for conn in connections:
              if conn.from_node not in node_ids:
                  errors.append(f"Connection references unknown source 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:
                      errors.append(f"Connection references unknown target node '{target}'")
  
          # Validate clusters
          if clusters:
              cluster_names = {cluster.name for cluster in clusters}
  
              for cluster in clusters:
                  # Check node references
                  for node_id in cluster.node_ids:
                      if node_id not in node_ids:
                          errors.append(
                              f"Cluster '{cluster.name}' references unknown node '{node_id}'"
                          )
  
                  # Check parent cluster exists
                  if cluster.parent_cluster and cluster.parent_cluster not in cluster_names:
                      errors.append(
                          f"Cluster '{cluster.name}' references unknown parent '{cluster.parent_cluster}'"
                      )
  
                  # Check for empty clusters
                  if not cluster.node_ids:
                      warnings.append(f"Cluster '{cluster.name}' is empty")
  
          # Determine if valid
          valid = len(errors) == 0
  
          # Build metadata
          metadata = {
              "node_count": len(nodes),
              "edge_count": len(connections),
              "cluster_count": len(clusters) if clusters else 0,
          }
  
          return format_validation_result(valid, errors, warnings, metadata)
  
      except Exception as e:
          return format_error(f"Validation failed: {str(e)}")

• src/diagrams_mcp/tools/core.py:842-853 (registration)

  The MCP tool decorator that registers the 'validate_diagram_spec' function as a tool with name, description, input schema via annotations, and execution hints.

  @mcp.tool(
      name="validate_diagram_spec",
      description="""Validate diagram before generation (dry-run).
  
  Checks: node validity, connection references, cluster memberships.
  Returns: {"valid": true/false, "errors": [...], "warnings": [...]}""",
      annotations={
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
      },
  )

• src/diagrams_mcp/tools/core.py:855-860 (schema)

  Pydantic input schema definitions using Annotated types (NodeDef, ConnectionDef, ClusterDef) with Field descriptions for validation and documentation.

      nodes: Annotated[List[NodeDef], Field(description="Nodes to validate")],
      connections: Annotated[List[ConnectionDef], Field(description="Connections to validate")],
      clusters: Annotated[
          Optional[List[ClusterDef]], Field(description="Clusters to validate")
      ] = None,
  ) -> str: