How It Works
Five concrete steps take you from a plain description to a fully deployed network topology inside Cisco Packet Tracer.
The user describes a lab
A user or AI agent describes a network topology in natural language. The request is translated into structured parameters: number of routers, PCs per LAN, DHCP, WAN links, routing protocol, and device models.
"Build a 3-router OSPF lab with DHCP and 2 PCs per LAN, plus a WAN link."
The orchestrator builds the topology
The domain layer creates a complete topology plan: devices with models, links with cable types, coordinates for positioning, IP addressing scheme, DHCP pool configurations, and routing protocol blocks.
pt_plan_topology( routers=3, pcs_per_lan=2, dhcp=True, routing="ospf", has_wan=True, router_model="2911" )
The plan is checked against real PT constraints
Validators catch 15+ error types: invalid models, duplicated names, bad ports, reused interfaces, cable mismatches, DHCP issues, and IP conflicts. The auto-fixer can correct cables, upgrade router models, and reassign ports automatically.
pt_validate_plan(plan) # ✓ All device models valid # ✓ No duplicate names # ✓ No port conflicts # ✓ Cable types correct # ✓ IP addressing valid # ✓ DHCP pools consistent
Build artifacts are created
The server generates multiple outputs: PTBuilder JavaScript code for topology construction, IOS CLI configuration commands per device, host configuration instructions, project files for persistence, and natural language explanations.
pt_generate_script(plan) → topology.js
pt_generate_configs(plan) → R1_config.txt
→ R2_config.txt
→ SW1_config.txt
pt_explain_plan(plan) → explanation.md Packet Tracer receives the result
Choose your delivery method: export files for manual use, copy to clipboard for paste, or deploy live through the HTTP bridge. The bridge sends JavaScript commands directly to a running Packet Tracer session in real-time.
# Option A: Export artifacts pt_export(plan, path="./my_lab/") # Option B: Live deploy pt_live_deploy(plan) # → Devices appear in PT in real-time # → Links created automatically # → Configs applied via CLI
Live Deploy Architecture
The most innovative part of the project: a bidirectional bridge that sends JavaScript commands from the MCP server into PT's Script Engine in real-time.
Python server on port 39000. Receives MCP tool calls, runs the pipeline, sends JS to the bridge.
ThreadingHTTPServer on port 54321. Queues JS commands and relays results between Python and PT.
Chromium webview inside Packet Tracer. Polls GET /next every 500ms and executes received code.
Executes ipc.* calls to create devices, links, and send CLI configs. No HTTP access — routes through webview.
Paste this once into Packet Tracer's Builder Code Editor and click Run. It starts the polling loop that connects PT to the bridge.
window.webview.evaluateJavaScriptAsync(
"setInterval(function(){" +
"var x=new XMLHttpRequest();" +
"x.open('GET','http://127.0.0.1:54321/next',true);" +
"x.onload=function(){" +
"if(x.status===200&&x.responseText){$se('runCode',x.responseText)}" +
"};" +
"x.onerror=function(){};" +
"x.send()" +
"},500)"
); Bridge Endpoints
/next GET Webview polls this. Returns queued JS command or empty. /ping GET Health check. Returns "pong". /status GET Connection status JSON. /result GET Long-poll for result from PT (9s timeout). /result POST PT posts execution results here (via webview). /queue POST Python enqueues JS commands here. Follow the getting started guide to run your first topology build.