packet-tracer-mcp

Servidor Model Context Protocol para controlar Cisco Packet Tracer 9.0 desde fuera. Una extensión propia se cuelga del editor de PT, abre un bridge HTTP local y desde ahí el servidor MCP llama a la API IPC nativa de PT para crear topologías, configurar routers, lanzar simulaciones, etc. Escrito en TypeScript sobre Bun.

[!WARNING] Proyecto experimental. Es la versión 0.1.0, hecha en mis ratos libres como experimento personal. Funciona contra PT 9.0.0.0810 en mi PC y pasa los smoke tests, pero no la consideres lista para producción. Espera bugs, cambios de API y cosas que se rompen al actualizar PT. Si te animas a probarla, abre issues con lo que veas.

_{Demo acelerada x15: el cliente MCP lanza una receta y el canvas de Packet Tracer 9 se va llenando solo (devices, cableado, configuración).}

Autor: Juan Cordero Pascual · Licencia: MIT Idiomas: español (este archivo) · English

Tabla de contenidos

• Por qué otro MCP de Packet Tracer
• Filosofía: canvas-first
• Requisitos
• Arranque rápido
  • Conectar un cliente MCP
  • Compilar a binario único
  • Tests
  • Recorrido end-to-end
• Capacidades
• Recetas incluidas
• Configuración
• Documentación
• FAQ
• Estructura del proyecto
• Estado

Por qué otro MCP de Packet Tracer

Los proyectos para PT 6.x–8.x se apoyaban en librerías JS cargadas por una extensión firmada de terceros. PT 9.0 cerró ese camino: los App Meta Files (.pta) ahora tienen que ir firmados con ECDSA por Cisco, así que ningún proyecto open-source puede entregar uno. La alternativa que queda es hablar con la webview de PT desde fuera, y eso es lo que hace este servidor:

• Hay una extensión .pts propia que se instala desde el menú Extensions de PT. Lo único que hace es arrancar un bucle de polling contra el bridge HTTP local.
• Cuando el servidor MCP necesita escribir, llama a la API IPC nativa de PT directamente: cosas como ipc.appWindow().getActiveWorkspace().getLogicalWorkspace().addDevice(...) o getDevice(...).getCommandLine().enterCommand(...). Sin librerías intermedias, sin JS opaco copiado de otros sitios.
• Todo el JS que termina ejecutándose en el Script Engine de PT lo genera este repo. Si quieres saber qué se está mandando, está en src/ipc/.

Filosofía: canvas-first

Otras herramientas mantienen un objeto "plan" en memoria, lo validan y al final lo vuelcan al simulador. Aquí no funciona así:

• No hay ningún TopologyPlan en memoria. Lo que hay en PT es lo que hay; el plan es el canvas.
• Cada receta vuelve a leer un snapshot del canvas antes de actuar. Si la lanzas dos veces sobre un canvas a medio construir, la segunda vez termina lo que faltaba en lugar de duplicar dispositivos. Sale idempotente sin tener que pensarlo.
• La validación se hace contra el canvas vivo, no contra una estructura interna. Cuando algo falla (IPs duplicadas, peers en subredes distintas, un router apagado) lo ves directamente en PT, no en un grafo abstracto.
• La persistencia guarda snapshots, no planes. Volver atrás significa comparar el canvas actual con un dump anterior y ver qué ha cambiado. No hay rehidratación mágica.

Si quieres el detalle, está en docs/ARCHITECTURE.md.

Requisitos

• Cisco Packet Tracer 9.0 (macOS, Windows o Linux).
• Bun >=1.2. Con Node solo no vale: el código es TypeScript y se ejecuta directamente con Bun, sin paso previo de compilación.
• La extensión mcp-bridge.pts instalada en PT. Viene en el repo en extension/dist/.

[!TIP] ¿Por qué Bun y no Node? Bun ejecuta .ts nativamente, arranca en milisegundos y trae fetch, HTTP y test runner de serie sin instalar dependencias. Si solo tienes Node, puedes instalar Bun con curl -fsSL https://bun.sh/install | bash (o brew install bun en macOS). Convive con Node sin pisarse.

Arranque rápido

git clone https://github.com/jcorderop02/packet-tracer-mcp.git
cd packet-tracer-mcp
bun install
bun run start              # streamable-HTTP en :39001 (default)
# o bien:
bun run src/index.ts --stdio   # modo stdio para clientes MCP que lo prefieran

En Packet Tracer 9:

1. Extensions > Scripting > Configure PT Script Modules > Add y selecciona extension/dist/mcp-bridge.pts.
2. Marca la extensión como activa.
3. Abre la ventana desde Extensions > MCP Bridge una vez por sesión.

El polling arranca solo en cuanto la ventana se carga. Para comprobar que todo está bien, lanza pt_bridge_status: en menos de un segundo debería responder connected: true.

El proceso completo de instalación está en docs/BOOTSTRAP.md.

El endpoint MCP queda en:

http://127.0.0.1:39001/mcp

[!NOTE] Por qué :39001. PT 9 ya tiene su propio IPC nativo (no documentado, con handshake firmado por Cisco) escuchando en :39000. Para no chocar y dejar claro que el servidor MCP es algo aparte, este escucha en :39001. Si te molesta, cámbialo con la variable de entorno PACKETTRACER_MCP_PORT.

Conectar un cliente MCP

claude mcp add --transport http packet-tracer http://127.0.0.1:39001/mcp

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

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

{
  "mcpServers": {
    "packet-tracer": {
      "httpUrl": "http://127.0.0.1:39001/mcp"
    }
  }
}

[mcp_servers.packet-tracer]
url = "http://127.0.0.1:39001/mcp"

curl -sS -X POST http://127.0.0.1:39001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0"}}}'

Compilar a binario único

bun run build
./dist/packet-tracer-mcp

Tests

bun test

La suite unitaria cubre la aritmética de subnetting, la inspección del canvas, el parser de snapshots, los diffs, la validación de blueprints y los builders CLI de cada receta. No hace falta PT corriendo para ejecutarla.

Recorrido end-to-end

Con el bridge conectado (pt_bridge_status → connected: true), una sesión completa más o menos se ve así:

1. pt_list_recipes                          # confirmar lo disponible
2. pt_forecast recipe='chain' params={routers:3, pcsPerLan:2}
                                            # estimación dry-run, ningún cambio
3. pt_cook_topology recipe='chain'
       params={routers:3, pcsPerLan:2, routing:'ospf'}
                                            # construye el lab; idempotente
4. pt_inspect_canvas                        # findings: IPs duplicadas, etc.
5. pt_explain_canvas                        # narración legible
6. pt_save_snapshot name='chain-baseline'   # captura T-0
7. pt_run_cli device='R1' command='show ip route'
                                            # comprobación rápida desde el CLI
8. pt_diff_snapshots before='chain-baseline'
                                            # qué ha cambiado desde T-0
9. pt_save_pkt path='/abs/path/lab.pkt'     # guardar como .pkt nativo

Si algo se ha torcido por el camino, pt_mend_canvas aplica reparaciones conservadoras (encender dispositivos que ya están cableados pero apagados, ese tipo de cosas) y avisa de lo que no se atreve a tocar.

Capacidades

packet-tracer-mcp expone 57 herramientas MCP agrupadas por dominio.

Bridge y diagnóstico

pt_bridge_status, pt_ping, pt_clear_canvas.

Catálogo y descubrimiento

pt_list_devices, pt_list_modules, pt_list_recipes, pt_list_snapshots, pt_get_device_details.

Inspección del workspace en vivo (read-only)

pt_query_topology, pt_inspect_canvas, pt_explain_canvas, pt_forecast (dry-run de receta), pt_generate_configs (genera el IOS CLI offline de una receta sin tocar PT — útil para documentación, aulas o reproducir el lab en hardware real), pt_inspect_ports (estado per-puerto: link/up/proto, MAC, IP/máscara, wireless), pt_read_vlans (base VLAN viva por switch), pt_read_acl (ACLs configuradas leídas vía AclProcess), pt_show_bgp_routes (parsea show ip bgp en filas estructuradas), pt_read_project_metadata (descripción/versión/filename del .pkt actual).

Edición primitiva del canvas

pt_add_device, pt_add_module, pt_create_link, pt_delete_device, pt_delete_link, pt_move_device, pt_auto_layout (recoloca todo el canvas en una rejilla por capas, detecta routers de tránsito y los baja a un segundo piso), pt_rename_device, pt_set_pc, pt_set_device_power (toggle Device.setPower idempotente), pt_add_canvas_annotation (notas/líneas/círculos), pt_manage_clusters (lista/elimina/disuelve clusters lógicos), pt_send_raw (vía de escape: ejecuta JS arbitrario en el Script Engine).

Edición a nivel de receta (orquestación)

pt_cook_topology, pt_mend_canvas, pt_plan_review (revisión pre-flight obligatoria para topologías de ≥3 routers), pt_apply_switching, pt_apply_services, pt_configure_server_dhcp (DHCP server en Server-PT vía API IPC nativa), pt_configure_subinterface (sub-interfaces 802.1Q para router-on-a-stick), pt_apply_advanced_routing, pt_apply_ipv6, pt_apply_voip, pt_apply_wireless.

Persistencia (snapshots)

pt_save_snapshot, pt_load_snapshot, pt_diff_snapshots. Los snapshots se guardan en disco como un dump del canvas. Cargar uno no sobreescribe nada: te enseña la diferencia contra lo que tienes ahora mismo en PT y tú decides.

Persistencia .pkt nativa

pt_save_pkt, pt_open_pkt (cuando el servidor y PT comparten filesystem), más pt_save_pkt_to_bytes y pt_open_pkt_from_bytes para mover el .pkt por la red. El formato comprimido .pkz no funciona: la API JS expone los métodos pero los bytes que devuelve no son válidos en PT 9.0.0.0810.

CLI de routers y switches

pt_run_cli, pt_run_cli_bulk, pt_show_running (con | section opcional).

Simulación y operaciones

pt_simulation_mode (toggle Realtime↔Simulation), pt_simulation_play (play/back/forward/reset), pt_send_pdu (Simple PDU originado), pt_traceroute, pt_screenshot (PNG/JPG del workspace).

Recetas incluidas

pt_list_recipes devuelve la lista al vuelo. Las que vienen de fábrica:

Las primeras tres admiten routing: 'static' | 'ospf' | 'eigrp' | 'rip' | 'none' y dhcp: true|false. campus_vlan acepta además startVlanId, vlanStep y lanPool. wifi_lan acepta ssid, security, psk y channel.

Configuración

Variables de entorno (todas opcionales):

Documentación

• AGENTS.md — guía operativa para LLMs que usen este servidor: convenciones de cableado (LAN Gigabit vs WAN serial), LANs de usuario vs de tránsito, flujo recomendado de creación + auto layout, errores típicos a evitar.
• docs/ARCHITECTURE.md — capas (transporte MCP, tools, recetas, generadores IPC, bridge HTTP), por qué canvas-first, persistencia .pkt, qué queda fuera de alcance.
• docs/BOOTSTRAP.md — instalación de la extensión .pts, anatomía del polling, sección para desarrolladores que quieran reconstruir el .pts.
• docs/COVERAGE.md — qué está verificado contra PT 9 real, en qué estado (verified-pt9 / contract-verified / partial / broken / dead-end), referencias a smoke runs y limitaciones conocidas del simulador que afectan al usuario.
• docs/TOOLS.md — referencia de las 57 tools MCP, con parámetros, comportamiento y notas.
• docs/RECIPES.md — catálogo de recipes (chain, star, branch_office, campus_vlan, edge_nat, wifi_lan, voip_lab, ipv6_lab, dual_isp) con parámetros, ejemplos y resultado esperado.
• docs/TROUBLESHOOTING.md — síntomas reales, causa probable y fix. La FAQ de aquí abajo es el resumen.
• CHANGELOG.md — qué entra en cada release, en formato Keep a Changelog.
• CONTRIBUTING.md — cómo abrir issues, setup local, convenciones de código y commits.
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1.
• SECURITY.md — política de seguridad y reporte de vulnerabilidades.

Estructura del proyecto

src/
  bridge/        Bridge HTTP que sondea la webview de PT
  canvas/        Snapshot, inspección, diff y aritmética de subnetting
  catalog/       Modelos PT (54), alias humanos, tipos de cable
  ipc/           Generadores puros string-in/string-out para el IPC nativo
                 + persistencia .pkt vía systemFileManager
  recipes/       Blueprints, addressing, routing, switching, services,
                 ipv6, voip, wireless, topologías predefinidas
  persistence/   Persistencia de snapshots
  tools/         Un fichero por tool MCP; ALL_TOOLS los agrega
  config.ts      Configuración por entorno
  server.ts      Ciclo de vida (transporte MCP + bridge)
  index.ts       Entry-point CLI
extension/       Extensión .pts (módulo PT que arranca el polling)
docs/            Arquitectura, bootstrap y matriz de cobertura
scripts/         smoke.ts (suite de verificación contra PT real)

FAQ

Errores frecuentes (respuesta corta)

Lista completa en docs/TROUBLESHOOTING.md.

Estado

Probado contra Cisco Packet Tracer 9.0.0.0810:

• 54 / 54 modelos del catálogo etiquetados como verified-pt9.
• 57 tools MCP con sus tests unitarios.
• 8 de 9 recetas verificadas de principio a fin (chain, star, branch_office, campus_vlan, edge_nat, dual_isp, voip_lab, ipv6_lab). La novena, wifi_lan, se queda a medias por una limitación de la API de PT (no del MCP).
• Capas validadas end-to-end: switching L2, servicios L3 (NAT, ACL, DHCP), routing dinámico (OSPF, BGP, HSRP, EIGRP), IPv6 con OSPFv3, VoIP (CME + ephone-dn), simulación y operaciones, y persistencia .pkt.

La evidencia detallada (smoke runs, capturas de pantalla y limitaciones conocidas) está en docs/COVERAGE.md.