validate_diagram_spec

Validate diagram specifications before generation to check node validity, connection references, and cluster memberships, returning validation results with any errors or warnings.

Instructions

Validate diagram before generation (dry-run).

Checks: node validity, connection references, cluster memberships. Returns: {"valid": true/false, "errors": [...], "warnings": [...]}

Input Schema

TableJSON Schema

Name	Required	Description
`nodes`	Yes	Nodes to validate
`connections`	Yes	Connections to validate
`clusters`	No	Clusters to validate

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:

Diagrams MCP Server