网络拓扑自动化工具

Packet Tracer MCP

Servidor MCP para crear, configurar, validar y desplegar topologías de Cisco Packet Tracer desde prompts en lenguaje natural.

Con este proyecto puedes pedirle a un cliente MCP como Claude Desktop, VS Code, Copilot/Codex u otro agente:

Crea una red con 2 routers, 2 switches, 4 PCs, DHCP y OSPF. Despliégala en Packet Tracer.

El servidor convierte el prompt en un plan de red, valida modelos/puertos/cables/IPs, genera scripts PTBuilder, exporta artefactos y, si Packet Tracer está conectado al bridge local, envía los comandos para que los dispositivos aparezcan en el canvas.

Funcionalidades

• Prompt libre en español o inglés con pt_prompt_plan y pt_prompt_deploy.
• Despliegue en vivo hacia Packet Tracer mediante bridge HTTP local.
• Planificación automática de routers, switches, PCs, laptops, servidores, APs y WAN.
• Direccionamiento IPv4 automático para LANs y enlaces punto a punto.
• DHCP, rutas estáticas, OSPF, RIP y EIGRP.
• Validación y auto-fix de modelos, puertos, cables, IPs y DHCP.
• Exportación de proyecto: plan JSON, scripts JS, configuraciones CLI y metadatos.
• Presets de laboratorio para CCNA/CCNP, sucursales, DMZ y enterprise.

Requisitos

• Python 3.11 o superior.
• Cisco Packet Tracer 8.2 o superior.
• Extensión PTBuilder instalada en Packet Tracer.
• Un cliente MCP compatible con HTTP streamable o stdio.

Instalación

git clone <repo-url>
cd MCP_Packet_Tracer
python -m pip install -e .

Para desarrollo y pruebas:

python -m pip install -e ".[dev]"
python -m pytest tests/ -v

Ejecutar el servidor

Modo recomendado, HTTP persistente:

python -m src.packet_tracer_mcp

Endpoints locales:

Modo stdio para clientes legacy:

python -m src.packet_tracer_mcp --stdio

Puerto MCP personalizado:

PT_MCP_PORT=39001 python -m src.packet_tracer_mcp

Configurar 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"
    }
  }
}

Quickstart: Prompt A Packet Tracer

1. Inicia el servidor MCP:

python -m src.packet_tracer_mcp

2. Abre Cisco Packet Tracer.

3. Abre Extensions > Builder Code Editor.

4. En tu cliente MCP ejecuta:

Usa pt_bridge_status y dime si Packet Tracer está conectado.

5. Si el bridge indica que PT no está conectado, copia el bootstrap que devuelve pt_bridge_status, pégalo en Builder Code Editor y presiona Run.

6. Ahora pide el despliegue completo:

Usa pt_prompt_deploy con este prompt:
"Crea una red con 2 routers, 2 switches, 4 PCs, DHCP y OSPF. Despliégala en Packet Tracer."

Si Packet Tracer está conectado, los dispositivos, enlaces y configuraciones se enviarán al canvas. Si no está conectado, el proyecto queda exportado en projects/<project_name>/ y la respuesta incluye el bootstrap exacto para conectar PT.

Flujo Recomendado Para Agentes

Para automatización completa, usa esta secuencia:

1. pt_bridge_status
2. pt_prompt_deploy
3. pt_query_topology
4. pt_export_documentation

Cuando el usuario solo quiera planificar sin tocar Packet Tracer:

1. pt_prompt_plan
2. pt_validate_plan
3. pt_generate_script
4. pt_export

Tools Principales

El servidor expone 36 tools MCP. Las más importantes:

Recursos MCP

Artefactos Exportados

pt_prompt_deploy, pt_export y pt_deploy generan una carpeta de proyecto:

projects/<project_name>/
├── topology.js       # Solo dispositivos y enlaces
├── full_build.js     # Topología + configs CLI como referencia
├── live_deploy.js    # Script ejecutable con addDevice/addLink/configuración
├── plan.json         # TopologyPlan completo
├── metadata.json     # Resumen del proyecto
└── R*_config.txt     # Configs IOS por router/switch

Bridge De Packet Tracer

Packet Tracer no acepta conexiones MCP directamente. El flujo live deploy usa un bridge local:

Cliente MCP -> MCP Server :39000 -> Bridge :54321 -> PTBuilder WebView -> Packet Tracer

El servidor inicia el bridge automáticamente. Packet Tracer debe ejecutar una vez por sesión el bootstrap que devuelve pt_bridge_status. Ese bootstrap hace polling local a http://127.0.0.1:54321/next y ejecuta los comandos recibidos en PTBuilder.

Ejemplos De Prompts

Crea una red pequeña de oficina con un router, un switch, 5 PCs y DHCP.

Haz un laboratorio CCNA con 2 routers, 2 switches, 4 PCs, rutas estáticas y DHCP.

Diseña tres sedes con salida a internet, OSPF, 3 PCs por LAN y un servidor central.

Crea una red en estrella con 1 router central, 3 routers de sucursal, DHCP y rutas flotantes.

Para forzar parámetros desde un agente:

{
  "prompt": "red de sucursales con internet",
  "overrides_json": "{\"routers\": 3, \"routing\": \"ospf\", \"pcs_per_lan\": 4}"
}

Modelos Soportados

El catálogo incluye más de 50 modelos de Packet Tracer, entre ellos:

Consulta el catálogo real desde el cliente MCP con pt_list_devices o pt://catalog/devices.

API PTBuilder Usada

El script de despliegue usa funciones provistas por la extensión PTBuilder:

addDevice("R1", "2911", 100, 100);
addLink("R1", "GigabitEthernet0/0", "SW1", "GigabitEthernet0/1", "straight");
configureIosDevice("R1", "hostname R1\ninterface GigabitEthernet0/0\nno shutdown");
configurePcIp("PC1", false, "192.168.0.2", "255.255.255.0", "192.168.0.1", "8.8.8.8");

No inventes funciones JavaScript. Si un agente necesita generar código manual, primero debe leer pt://prompts/ptbuilder-guide.

Troubleshooting

Bridge active but PT is NOT connected

• Abre Packet Tracer.
• Abre Extensions > Builder Code Editor.
• Ejecuta el bootstrap devuelto por pt_bridge_status.
• Vuelve a ejecutar pt_bridge_status hasta ver CONNECTED.

Port 39000 already in use

Usa otro puerto para el MCP server:

PT_MCP_PORT=39001 python -m src.packet_tracer_mcp

Port 54321 already in use

El bridge HTTP está ocupado. Cierra el proceso anterior o reinicia la sesión del servidor MCP.

Los dispositivos no aparecen en Packet Tracer

• Confirma que pt_bridge_status diga CONNECTED.
• Mantén abierto Builder Code Editor.
• Ejecuta pt_ping_bridge para ver bridge_up y pt_connected.
• Reintenta con pt_prompt_deploy o pt_live_deploy.

function not defined en Packet Tracer

• Verifica que estás usando el V1-MCP-BUILDER.pts compatible con este repo.
• El live deploy genera addDevice, addLink, configureIosDevice y configurePcIp.
• Si PTBuilder tiene otra API, actualiza la extensión o ajusta el generador.

Arquitectura

src/packet_tracer_mcp/
├── adapters/mcp/          # Tools y resources MCP
├── application/           # Use cases y DTOs
├── domain/                # Modelos, reglas, planificación, validación
├── infrastructure/        # Catálogo, generadores, bridge, persistencia
├── shared/                # Constantes, enums, prompts y logging
├── server.py              # Entry point MCP HTTP/stdio
└── settings.py            # Configuración global

Estado Del Proyecto

Versión actual: 0.6.0

Este servidor está orientado a educación, laboratorios de red y automatización de Packet Tracer. El primer bootstrap en PTBuilder sigue siendo necesario por limitaciones de integración de Packet Tracer; después de eso, el flujo puede ser prompt-to-deploy desde el cliente MCP.