cml

CML

Build and operate CML labs through the CML MCP tools. The guidance below covers the conventions and pitfalls an agent will not infer correctly on its own. General networking knowledge (e.g., what OSPF is, how a switch works) is assumed and not repeated here.

IDs are opaque — copy them, never reconstruct them. When a tool returns an identifier (lab, node, interface, or link UUID), pass that exact value to later calls. Never retype an ID from memory or rebuild one from context; a single altered character makes the call fail, and the corrupted value can still look well-formed, so you cannot catch the error by inspecting it. If you are not certain you have the exact value, re-fetch it with the relevant listing tool (get_nodes_for_cml_lab, get_interfaces_for_node, get_all_links_for_lab) rather than guessing. One exception: send_cli_command identifies its node by label, not UUID — see Configuration.

Default approach: build incrementally, not in one shot

Build a lab by composing small, verifiable steps. Do not try to hand-assemble a complete topology object and import it in one call unless the user has explicitly provided a finished model.

Default sequence:

1. create_empty_lab (title, optional description/notes) → capture the returned lab_id. Lab notes are rendered as Markdown in the CML UI, so record the topology's purpose / high-level description there — it's what a human sees when they open the lab.
2. get_cml_node_definitions once, to learn valid node_definition values for this server. Do not guess names like csr1000v/iosv — servers differ in what's installed. If get_cml_node_definitions returns an error or an empty list, stop immediately and tell the user: the server returned no node definitions and you cannot proceed without them. Do not guess any node_definition value. If the device type the user asked for isn't in the returned list, stop and tell them — name the closest available definitions and let them choose. Never silently substitute a different device type. If get_cml_node_definitions returns 2 or more definitions whose names or descriptions could reasonably satisfy the user's request (i.e., they are the same device family or serve the same functional role — e.g. "a Cisco router" matching iol-xe, iosv, csr1000v, cat8000v), list every matching definition by its exact name and ask the user to pick one before proceeding. Do not silently choose the first match. For which definition to recommend as the default among installed options (e.g. iol-xe for routers, ioll2-xe for switches), see references/node_selection_guidance.md.
3. add_node_to_cml_lab per device. Set label, node_definition, and x/y (see Layout). Each add auto-creates that definition's default interfaces.
4. Connect nodes (see Connecting nodes — this is the step most often done wrong).
5. Apply configuration (see Configuration).
6. Start nodes when the user wants the lab running. To start an entire lab, use start_cml_lab(lab_id). To start nodes in a specific order (e.g., core infrastructure before edge devices), call start_cml_node(lab_id, node_id) sequentially, using wait_for_convergence=true on each node before starting the next when a later node depends on an earlier one being reachable. See references/operations.md for full lifecycle details.