Packet Tracer MCP Server

Servidor MCP que permite a cualquier LLM (Copilot, Claude, etc.) crear, configurar, validar y desplegar topologías de red completas en Cisco Packet Tracer.

Le decís "creame una red con 3 routers, DHCP y OSPF" y el servidor planifica la topología, valida todo, genera los scripts y configs, y lo despliega directo en PT en tiempo real.

Python 3.11+ · Pydantic 2.0+ · FastMCP · Streamable HTTP

---

Instalación

git clone <repo>
cd PACKET-TRACER
pip install -e .

---

Uso

1. Levantar el servidor

python -m src.packet_tracer_mcp

Esto inicia:

• Servidor MCP en http://127.0.0.1:39000/mcp (streamable-http)
• Bridge HTTP en http://127.0.0.1:54321 (comunicación con Packet Tracer)

Ambos arrancan automáticamente. No se necesita ningún script adicional.

Para modo stdio (debug/legacy): python -m src.packet_tracer_mcp --stdio

2. Configurar el cliente MCP

VS Code — .vscode/mcp.json:

{
  "servers": {
    "packet-tracer": {
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "packet-tracer": {
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}

3. Usar desde el LLM

Pedile al LLM que cree una red. El servidor expone 22 tools MCP que cubren todo el pipeline:

Tool	Qué hace
pt_list_devices	Catálogo de dispositivos disponibles
pt_list_templates	Templates de topologías predefinidas
pt_get_device_details	Detalle de puertos/interfaces de un modelo
pt_estimate_plan	Estimación rápida sin generar plan completo
pt_plan_topology	Genera un plan completo (dispositivos, links, IPs, DHCP, rutas)
pt_validate_plan	Valida que el plan sea correcto
pt_fix_plan	Auto-corrige errores comunes
pt_explain_plan	Explicación en lenguaje natural del plan
pt_generate_script	Genera script JavaScript para PTBuilder
pt_generate_configs	Genera configuraciones CLI por dispositivo
pt_full_build	Pipeline completo de una sola vez
pt_deploy	Copia script al portapapeles con instrucciones
pt_live_deploy	Envía comandos directo a PT en tiempo real
pt_bridge_status	Verifica conexión con PT
pt_query_topology	Consulta dispositivos existentes en PT
pt_delete_device	Elimina un dispositivo de PT
pt_rename_device	Renombra un dispositivo en PT
pt_move_device	Mueve un dispositivo en el canvas
pt_delete_link	Elimina un enlace de PT
pt_send_raw	Envía JS arbitrario a PT
pt_export	Exporta plan + scripts + configs a archivos
pt_list_projects / pt_load_project	Gestión de proyectos guardados

---

¿Por qué el servidor corre en el puerto 39000?

El servidor MCP usa streamable-http en lugar de stdio. Esto significa que el servidor se levanta una vez como un proceso HTTP persistente y los clientes MCP se conectan a él por red.

Ventajas sobre stdio:

• Persistencia — el servidor queda corriendo, no se reinicia con cada sesión del editor
• Múltiples clientes — podés conectar VS Code, Claude Desktop u otros clientes al mismo servidor simultáneamente
• Estado compartido — el bridge HTTP hacia Packet Tracer se mantiene activo entre requests
• Debug más fácil — podés hacer curl al servidor, ver logs en la terminal donde corre
• Desacoplamiento — el servidor no depende del ciclo de vida del editor

El puerto 39000 fue elegido para no colisionar con puertos comunes (3000, 5000, 8000, 8080) ni con el bridge interno de PT que usa el 54321.

---

Live Deploy — Despliegue en tiempo real

La feature principal: enviar comandos directamente a Packet Tracer sin copiar/pegar nada.

┌─────────┐         ┌──────────────┐   HTTP    ┌──────────────┐  $se()  ┌──────────────┐
│   LLM   │  MCP    │  MCP Server  │  :54321   │  PTBuilder   │  IPC   │ Packet Tracer│
│(Copilot)│ ──────► │  (:39000)    │ ────────► │  (WebView)   │ ─────► │   (Engine)   │
└─────────┘         └──────────────┘           └──────────────┘        └──────────────┘

Hay dos servidores HTTP corriendo:

Puerto	Qué es	Para qué
39000	Servidor MCP (streamable-http)	Recibe requests de tools del LLM/editor
54321	Bridge HTTP interno	Envía comandos JS a PTBuilder dentro de Packet Tracer

Setup del bridge (una vez por sesión de PT):

1. Abrí Packet Tracer 8.2+
2. Abrí Builder Code Editor (Extensions > Builder Code Editor)
3. Pegá este bootstrap y hacé clic en Run:

/* PT-MCP 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)");

Eso hace que PTBuilder haga polling cada 500ms al bridge. Cuando el LLM genera comandos, el MCP Server los encola en el bridge y PT los ejecuta en tiempo real.

---

Arquitectura

src/packet_tracer_mcp/
├── adapters/mcp/          # Tools y resources MCP
├── application/           # Use cases + DTOs
├── domain/
│   ├── models/           # TopologyPlan, DevicePlan, LinkPlan
│   ├── services/         # Orchestrator, IPPlanner, Validator, AutoFixer
│   └── rules/            # Reglas de validación
├── infrastructure/
│   ├── catalog/          # Catálogo de dispositivos, cables, templates
│   ├── generator/        # Generador de scripts JS + configs CLI
│   ├── execution/        # Bridge HTTP + Live Executor
│   └── persistence/      # Proyectos guardados
├── server.py             # Entry point del servidor
└── settings.py           # Configuración

Flujo de datos

1. Request → el LLM describe qué red quiere
2. Planificación → el Orchestrator genera un TopologyPlan completo
3. Validación → el Validator verifica modelos, puertos, cables, IPs
4. Auto-fix → el AutoFixer corrige errores comunes automáticamente
5. Generación → se produce el script JS para PTBuilder + configs CLI
6. Deploy → se envía a PT vía bridge HTTP o se exporta a archivos

Direccionamiento IP

• LANs: 192.168.X.0/24 — gateway en .1, PCs desde .2
• Links inter-router: 10.0.X.0/30 — 2 hosts por enlace

Routing soportado

• static — genera ip route completas
• ospf — genera router ospf con áreas
• none — sin routing

---

Tests

python -m pytest tests/ -v

---

Requisitos

• Python 3.11+
• Cisco Packet Tracer 8.2+ (para live deploy)
• PTBuilder extension instalada en PT (incluida en PTBuilder/)

5. Listo. El MCP server puede crear dispositivos, enlaces y configurar routers automáticamente.

Nota técnica: El bootstrap inyecta un setInterval en el webview que hace polling HTTP. El $se('runCode', ...) bridgea del webview al Script Engine de PT. PTBuilder usa executeCode() que internamente hace code.replace(/\n/g, ""), por eso el bootstrap usa /* */ comments en vez de //.

Setup permanente (opcional):

Para que el polling arranque automáticamente al abrir Builder Code Editor:

1. En PT: Extensions > Scripting Interface
2. Seleccioná el módulo Builder
3. Reemplazá main.js e interface.js con las versiones modificadas en PTBuilder/source/
4. Guardá y reiniciá el módulo

---

MCP Tools (22)

Consulta

Tool	Descripción
pt_list_devices	Lista todos los dispositivos disponibles con sus puertos
pt_list_templates	Lista las plantillas de topología disponibles
pt_get_device_details	Detalles completos de un modelo específico

Estimación

Tool	Descripción
pt_estimate_plan	Dry-run: estima dispositivos, enlaces y complejidad sin generar

Planificación

Tool	Descripción
pt_plan_topology	Genera un plan completo desde parámetros (routers, PCs, routing, etc.)

Validación

Tool	Descripción
pt_validate_plan	Valida un plan con 15 tipos de error tipificados
pt_fix_plan	Auto-corrige errores comunes (cables, modelos, puertos)
pt_explain_plan	Genera explicación en lenguaje natural de cada decisión

Generación

Tool	Descripción
pt_generate_script	Genera script JavaScript para PTBuilder
pt_generate_configs	Genera configuraciones CLI (IOS) por dispositivo

Pipeline completo

Tool	Descripción
pt_full_build	Todo en uno: planifica, valida, genera y exporta

Despliegue en vivo

Tool	Descripción
pt_deploy	Copia script al portapapeles + instrucciones manuales
pt_live_deploy	Envía comandos directo a PT en tiempo real via HTTP bridge
pt_bridge_status	Verifica si el bridge está activo y PT está conectado

Interacción con topología existente

Tool	Descripción
pt_query_topology	Consulta qué dispositivos existen actualmente en PT
pt_delete_device	Elimina un dispositivo y sus enlaces de PT
pt_rename_device	Renombra un dispositivo en la topología activa
pt_move_device	Mueve un dispositivo a nuevas coordenadas en el canvas
pt_delete_link	Elimina el enlace de una interfaz específica
pt_send_raw	Envía código JS arbitrario al Script Engine de PT

Exportación y proyectos

Tool	Descripción
pt_export	Exporta a archivos (JS script, CLI configs, JSON plan)
pt_list_projects	Lista proyectos guardados
pt_load_project	Carga un proyecto guardado

---

MCP Resources (5)

URI	Descripción
pt://catalog/devices	Todos los dispositivos con puertos
pt://catalog/cables	Tipos de cable
pt://catalog/aliases	Aliases de modelos
pt://catalog/templates	Plantillas de topología
pt://capabilities	Capacidades del servidor

---

Dispositivos soportados

Routers

Modelo	Puertos
1941	Gig0/0, Gig0/1, Se0/0/0, Se0/0/1
2901	Gig0/0, Gig0/1, Se0/0/0, Se0/0/1
2911	Gig0/0, Gig0/1, Gig0/2, Se0/0/0, Se0/0/1
4321 (ISR4321)	Gig0/0/0, Gig0/0/1

Switches

Modelo	Puertos
2960-24TT	Fa0/1–24, Gig0/1–2
3560-24PS	Fa0/1–24, Gig0/1–2

End Devices

Modelo	Puertos
PC-PT	Fa0
Server-PT	Fa0
Laptop-PT	Fa0

Otros

Modelo	Tipo
Cloud-PT	WAN Cloud
AccessPoint-PT	Wireless AP

---

Tipos de cable

Cable	Uso típico
straight	Switch↔Router, Switch↔PC
cross	Router↔Router, Switch↔Switch, PC↔PC
serial	Router Serial↔Router Serial (WAN)
fiber	Conexiones de fibra óptica
auto	Detección automática

---

Direccionamiento IP

• LANs: 192.168.X.0/24 — Gateway en .1, PCs desde .2
• Inter-router links: 10.0.X.0/30 — Punto a punto entre routers
• DHCP: Pool automático por LAN con exclusión del gateway

---

Routing soportado

Protocolo	Estado	Genera
static	✅ Completo	ip route commands
ospf	✅ Completo	router ospf configs
eigrp	🔲 Enum only	No implementado
rip	🔲 Enum only	No implementado
none	✅	Sin routing

---

Templates

Template	Descripción
single_lan	1 router + 1 switch + PCs
multi_lan	N routers interconectados, cada uno con su LAN
multi_lan_wan	Multi LAN con nube WAN
star	Router central con routers satelitales
hub_spoke	Hub-and-spoke
branch_office	Sucursales
router_on_a_stick	Inter-VLAN routing
three_router_triangle	3 routers en triángulo
custom	Personalizado

---

Arquitectura

src/packet_tracer_mcp/
├── adapters/mcp/              # MCP protocol layer
│   ├── tool_registry.py       # 22 MCP tools
│   └── resource_registry.py   # 5 MCP resources
├── application/               # Use cases + DTOs (requests/responses)
├── domain/                    # Core business logic
│   ├── models/               # TopologyPlan, DevicePlan, LinkPlan, errors
│   ├── services/             # Orchestrator, IPPlanner, Validator, AutoFixer
│   └── rules/                # Validation rules (devices, cables, IPs)
├── infrastructure/
│   ├── catalog/              # Device catalog, cables, templates, aliases
│   ├── generator/            # PTBuilder JS + CLI config generators
│   ├── execution/            # Executors + HTTP bridge
│   │   ├── live_bridge.py    # PTCommandBridge (HTTP server :54321)
│   │   ├── live_executor.py  # LiveExecutor (sends plan → bridge → PT)
│   │   ├── deploy_executor.py# DeployExecutor (clipboard + instructions)
│   │   └── manual_executor.py# ManualExecutor (file export)
│   └── persistence/          # Project save/load
├── shared/                    # Enums, constants, utilities
├── server.py                  # MCP server entry point
└── settings.py                # Version + config

Flujo de datos

TopologyRequest → Orchestrator → IPPlanner → Validator → AutoFixer
                                                            ↓
                                              TopologyPlan (validated)
                                                            ↓
                                    ┌───────────────────────┼──────────────────┐
                                    ↓                       ↓                  ↓
                            PTBuilder Script          CLI Configs        Live Deploy
                           (addDevice/addLink)    (hostname, IPs,     (HTTP bridge
                                                   DHCP, routing)      → PT real-time)

---

PTBuilder (extensión de PT)

El directorio PTBuilder/ contiene el código fuente del Script Module "Builder Code Editor":

Archivo	Función
source/main.js	Entry point — crea menú y webview
source/runcode.js	runCode(scriptText) — ejecuta JS en Script Engine
source/userfunctions.js	addDevice(), addLink(), configureIosDevice(), configurePcIp(), queryTopology(), deleteDevice(), renameDevice(), moveDevice(), deleteLink()
source/devices.js	Mapeo modelo → tipo numérico de PT
source/links.js	Mapeo tipo de cable → ID numérico
source/modules.js	Mapeo módulos de hardware
source/window.js	Gestión de la ventana webview (QWebEngine)
source/interface/	HTML + JS del editor web (status panel + real-time logging)
Builder.pts	Paquete compilado de la extensión (binario, no editable)

API principal de PTBuilder

// Crear dispositivo en coordenadas (x, y)
addDevice("R1", "2911", 100, 200);

// Crear enlace entre dos dispositivos
addLink("R1", "GigabitEthernet0/1", "S1", "GigabitEthernet0/1", "straight");

// Configurar router/switch con CLI commands
configureIosDevice("R1", "enable\nconfigure terminal\nhostname R1\ninterface GigabitEthernet0/0\nip address 192.168.0.1 255.255.255.0\nno shutdown\nexit");

// Configurar IP estática de PC
configurePcIp("PC1", false, "192.168.0.2", "255.255.255.0", "192.168.0.1");

// Configurar PC para DHCP
configurePcIp("PC1", true);

---

Tests

# Todos los tests
python -m pytest tests/ -v

# Un archivo
python -m pytest tests/test_full_build.py -v

# Un test específico
python -m pytest tests/test_full_build.py::TestFullBuild::test_basic_2_routers -v

34 tests cubriendo: IP planning, validación, auto-fix, explicación, estimación, generación y full build integration.

---

Ejemplo de uso rápido

Usuario:  "Creame una red con 2 routers, 2 switches, 4 PCs, DHCP y static routing"

→ pt_full_build genera:
  - 8 dispositivos: R1, R2, SW1, SW2, PC1, PC2, PC3, PC4
  - 7 enlaces: R1↔R2 (cross), R1↔SW1 (straight), R2↔SW2 (straight), SW1↔PC1, SW1↔PC2, SW2↔PC3, SW2↔PC4
  - IPs: LAN1 192.168.0.0/24, LAN2 192.168.1.0/24, Inter-router 10.0.0.0/30
  - DHCP pools en R1 y R2
  - Static routes bidireccionales
  - 23 comandos JavaScript enviados a PT

→ pt_live_deploy envía todo a Packet Tracer y aparecen los dispositivos configurados