cml-topology-builder

---
name: cml-topology-builder
description: "Build CML topologies — add nodes, create interfaces, wire links, set link conditioning, add annotations. Use when building a network topology in CML, adding routers or switches to a lab, wiring links between nodes, or simulating WAN conditions."
version: 1.0.0
license: Apache-2.0
tags: [cml, topology, nodes, links, interfaces]
---

# 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

| Tool | Parameters | What It Does |
|------|-----------|-------------|
| `get_node_defs` | none | List all available node definitions (IOSv, NX-OS, IOS-XR, etc.) |
| `create_node` | `lab_id`/`lab_title`, `node_def`, `label`, `x`, `y` | Add a node to a lab |
| `get_nodes` | `lab_id`/`lab_title` | List all nodes in a lab |
| `get_node` | `lab_id`/`lab_title`, `node_id`/`node_label` | Get details of a specific node |

### Interface Management

| Tool | Parameters | What It Does |
|------|-----------|-------------|
| `create_interface` | `lab_id`/`lab_title`, `node_id`/`node_label`, `slot?` | Create a new interface on a node |
| `get_interfaces` | `lab_id`/`lab_title`, `node_id`/`node_label` | List all interfaces on a node |
| `get_interface` | `lab_id`/`lab_title`, `node_id`/`node_label`, `interface_id`/`interface_label` | Get interface details |

### Link Management

| Tool | Parameters | What It Does |
|------|-----------|-------------|
| `create_link` | `lab_id`/`lab_title`, `src_node`/`src_label`, `src_intf`, `dst_node`/`dst_label`, `dst_intf` | Create a link between two interfaces |
| `get_links` | `lab_id`/`lab_title` | List all links in a lab |
| `get_link` | `lab_id`/`lab_title`, `link_id` | Get link details |
| `set_link_condition` | `lab_id`/`lab_title`, `link_id`, `bandwidth?`, `latency?`, `jitter?`, `loss?` | Set link conditioning (WAN simulation) |
| `set_link_state` | `lab_id`/`lab_title`, `link_id`, `state` | Set link state (up/down) — simulate link failures |

### Annotations

| Tool | Parameters | What It Does |
|------|-----------|-------------|
| `create_annotation` | `lab_id`/`lab_title`, `annotation_type`, `content`, `x`, `y`, `width?`, `height?` | Add a text/shape annotation |
| `get_annotations` | `lab_id`/`lab_title` | List all annotations |
| `delete_annotation` | `lab_id`/`lab_title`, `annotation_id` | Remove an annotation |

## Available Node Definitions

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

| Node Definition ID | Description | Typical Use |
|--------------------|-------------|-------------|
| `iosv` | Cisco IOSv (IOS 15.x) | Routing, switching labs |
| `iosvl2` | Cisco IOSv L2 | Layer 2 switching labs |
| `iosxrv9000` | Cisco IOS XR 9000v | SP, MPLS, Segment Routing |
| `nxosv9000` | Cisco NX-OS 9000v | Data center, VXLAN |
| `csr1000v` | Cisco CSR 1000v (IOS-XE) | SD-WAN, routing |
| `cat8000v` | Cisco Catalyst 8000v | Enterprise routing |
| `asav` | Cisco ASAv | Firewall labs |
| `server` | Ubuntu/Alpine server | Traffic gen, testing |
| `external_connector` | External bridge | Connect lab to host/internet |
| `unmanaged_switch` | Unmanaged L2 switch | Simple L2 connectivity |
| `wan_emulator` | WAN emulator | Add latency/loss between nodes |

## 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:

```
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:
```
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:

| Scenario | Bandwidth | Latency | Jitter | Loss |
|----------|-----------|---------|--------|------|
| LAN | (none) | (none) | (none) | (none) |
| Metro Ethernet | 100 Mbps | 5 ms | 1 ms | 0% |
| WAN (good) | 50 Mbps | 20 ms | 5 ms | 0.1% |
| WAN (poor) | 10 Mbps | 100 ms | 20 ms | 1% |
| Satellite | 5 Mbps | 300 ms | 50 ms | 2% |
| Congested link | 1 Mbps | 200 ms | 100 ms | 5% |

## 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