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í: