Cml Topology Builder

CML Topology Builder

MCP Server

• Command: cml-mcp (pip-installed, stdio transport)
• Requires: CML_URL, CML_USERNAME, CML_PASSWORD environment variables

Available Tools

Node Management

Interface Management

Link Management

Annotations

Available Node Definitions

Common node types available in CML (use get_node_defs to get the full list):

Workflow: Build Topology from Description

When the user describes a topology:

1. Create the lab (or get an existing one via get_lab)
2. Get node definitions: get_node_defs to know what's available
3. Plan the layout: Calculate x,y coordinates for visual placement
   • Use a grid layout: 200px spacing horizontally, 200px vertically
   • Group by role: core in center, edge on sides, servers at bottom
4. Create nodes: create_node for each device with meaningful labels
5. Create interfaces: create_interface for each connection point
6. Wire links: create_link to connect interface pairs
7. Set conditions (if requested): set_link_condition for WAN links
8. Add annotations: create_annotation for labels, IP addressing plans
9. Report the topology: List all nodes, interfaces, and links

Layout Guidelines

When placing nodes, use this visual grid approach:

Copy code
Topology Layout (x, y coordinates):

Layer 0 (Top):     Core routers         y=100
Layer 1:           Distribution          y=300
Layer 2:           Access / Leaf         y=500
Layer 3 (Bottom):  Servers / Endpoints   y=700

x spacing: 200px between nodes in the same layer
Center the topology: start x at 100, distribute evenly

Example for a 2-spine, 4-leaf topology:

Copy code
Spine1: (300, 100)    Spine2: (500, 100)
Leaf1:  (100, 300)    Leaf2:  (300, 300)    Leaf3:  (500, 300)    Leaf4:  (700, 300)
Srv1:   (100, 500)    Srv2:   (300, 500)    Srv3:   (500, 500)    Srv4:   (700, 500)

Link Conditioning

Use set_link_condition to simulate real-world WAN characteristics:

Workflow: Annotate Topology

After building a topology, add visual documentation:

1. Title annotation: Lab name and purpose at the top
2. IP addressing: Annotation blocks showing subnet assignments per link
3. AS numbers: Label BGP AS boundaries
4. Area labels: Mark OSPF areas, VRF names, VLAN IDs
5. Notes: Any special instructions or test scenarios

Workflow: Simulate Link Failure

When testing network resilience:

1. Get the link: get_links to find the link ID between the two nodes
2. Capture baseline: Use execute_command to check routing tables before failure
3. Bring link down: set_link_state with state "down"
4. Observe convergence: Execute show commands on affected nodes (OSPF neighbors, BGP summary, routing table)
5. Optionally capture traffic: Use cml-packet-capture to capture reconvergence traffic
6. Restore link: set_link_state with state "up"
7. Verify recovery: Confirm routing adjacencies re-establish
8. Report: Document failover/failback time and behavior

Important Rules

• Always use get_node_defs first to verify available node types before creating nodes
• Create interfaces before links — you need interface IDs to wire links
• Use descriptive labels — "R1-Core" not "Node1"
• Plan before building — figure out the full topology before starting to create nodes
• Lab must be STOPPED to add nodes — cannot modify topology of a running lab
• Position nodes logically — hierarchical layout makes the topology readable in CML UI
• Record in GAIT — log topology creation for audit trail

Failure Behavior

• On a tool error (timeout, unreachable host, malformed response), report the failure and its error message directly to the user rather than fabricating or guessing at results.
• Do not automatically retry a write/mutating operation after a failure — surface the error and get explicit confirmation before retrying, since a blind retry on a partially-applied change can leave state inconsistent.