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.