# Packet Tracer MCP

Servidor MCP que permite a **Claude Code** construir y configurar topologías en
**Cisco Packet Tracer** hablando en lenguaje natural: crear dispositivos,
cablearlos, aplicar comandos IOS, VLANs, OSPF, NAT, ACLs, VoIP, o reproducir una
red completa a partir de la imagen de un diagrama.

```
Tu -> Claude Code --stdio--> mcp_server.py --HTTP--> bridge :54321
                                                         |
                              Packet Tracer  <-----------+
                              modulo Builder:
                                bridge.js         (pagina: hace el polling)
                                bridge_runner.js  (motor: ejecuta y devuelve)
```

El bridge HTTP corre **dentro** del servidor MCP: no hace falta una terminal
aparte para levantarlo. Y el loop de polling vive dentro del modulo Builder:
tampoco hay que pegar nada en Packet Tracer.

## Requisitos

| | |
|---|---|
| [uv](https://docs.astral.sh/uv/) | gestiona Python y las dependencias |
| Cisco Packet Tracer | probado en 9.0.0 (Windows) |
| Claude Code | cliente MCP |

## Puesta en marcha (una sola vez)

### 1. Dependencias

```bash
uv sync
```

### 2. Instalar el modulo Builder en Packet Tracer

`packet_tracer/Builder.pts` es el modulo de script que define dentro de PT las
funciones que usa este proyecto (`addDevice`, `addLink`, `addModule`,
`configureIosDevice`, `configurePcIp`, `getDevices`, `removeLink`, `addLabel`,
`saveTopology`) y el puente que lo comunica con el bridge HTTP.
**Sin este modulo nada funciona.**

En Packet Tracer (menus en ingles, verificado en PT 9.0.0):

1. `Extensions` -> `Scripting` -> `Configure PT Script Modules`
2. `Add` -> selecciona `packet_tracer/Builder.pts` de este repo
3. Selecciona **Builder** en la lista -> `Settings` -> marca **On Startup**,
   para que el modulo arranque solo cada vez que abras PT
4. Para confirmar que esta corriendo: en el menu `Extensions` debe aparecer la
   entrada **Builder Code Editor**. Si no aparece, el modulo no arranco.

Al arrancar, el modulo abre solo la ventana **Builder Code Editor**. Esa ventana
es la que hospeda el loop de polling, asi que **debe quedarse abierta** mientras
trabajas; si su titulo dice "bridge activo", el puente esta funcionando.

### 3. Abrir el proyecto en Claude Code

Desde una terminal, en la carpeta del proyecto:

```bash
claude
```

Claude Code lee [.mcp.json](.mcp.json) y levanta el servidor MCP (y con el, el
bridge HTTP) automaticamente. La primera vez puede pedirte que confirmes que
confias en la carpeta.

Para comprobar que el servidor esta conectado, escribe `/mcp` dentro de Claude
Code: debe aparecer **packet-tracer** con sus herramientas.

## Uso diario

```
1. Abre Packet Tracer
   -> la ventana "Builder Code Editor" se abre sola y debe quedarse abierta

2. En una terminal, en la carpeta del proyecto:
      cd ruta/al/pt_MCP
      claude

3. Dentro de Claude Code:
      /pt-iniciar     -> confirma que las 3 piezas responden
```

No hay que arrancar nada mas: ni `main.py`, ni pegar scripts en Packet Tracer,
ni terminales adicionales.

Y a partir de ahi, en lenguaje natural:

- «Crea dos routers 2911 unidos por serial con la 10.0.0.0/30 y una PC en cada LAN»
- `/pt-desde-imagen diagramas/ejemplo-red1.jpeg` — reproduce la topologia de un diagrama
- «Configura VLAN 10 VENTAS en SW1 y pon los puertos 1-4 en access»

Si algo no aparece en el canvas, pidele a Claude que llame `verificar_entorno()`:
dice cual de las tres piezas esta caida y como levantarla.

## Estructura

| Archivo | Rol |
|---|---|
| `mcp_server.py` | Servidor MCP: 38 herramientas de red + bridge HTTP embebido |
| `main.py` | App FastAPI del bridge (colas de comandos y resultados) |
| `packet_tracer/Builder.pts` | Modulo de script de PT, listo para importar |
| `packet_tracer/bridge.js` | Loop de polling (va en Custom Interfaces del modulo) |
| `packet_tracer/bridge_runner.js` | Ejecutor con canal de vuelta (va en Script Engine) |
| `CLAUDE.md` | Instrucciones y reglas que sigue Claude Code |
| `.claude/commands/` | `/pt-iniciar` y `/pt-desde-imagen` |
| `diagramas/` | Diagramas de entrada para /pt-desde-imagen (ver su README) |
| `build_red1.py` | Script suelto que habla directo al bridge: ejemplo y depuracion sin Claude |

Los dos `.js` de `packet_tracer/` ya van dentro de `Builder.pts`; estan sueltos en
el repo para poder leerlos, versionarlos y reimportarlos si hace falta.

`uv run python main.py` sigue sirviendo para levantar el bridge solo, sin MCP
(es lo que necesitan esos scripts de depuracion).

## Como viaja un comando

1. Claude llama a una herramienta MCP, que traduce a una linea de JS de PT.
2. `mcp_server.py` la encola con `POST /add_command`.
3. `bridge.js`, dentro de la ventana Builder Code Editor, la recoge con
   `GET /next_command` (cada 2 s) y llama `$se('runCodeBridge', codigo)`.
4. `bridge_runner.js` la ejecuta en el script engine y, si devuelve un valor,
   se lo entrega de vuelta a la pagina con `evaluateJavaScriptAsync`.
5. La pagina lo publica con `POST /command_result` y `mcp_server.py` lo recoge.

El paso 4 es necesario porque `$se()` solo confirma que despacho la llamada
(resuelve a `true`), nunca entrega el valor del codigo ejecutado.

Cada consulta viaja envuelta en una marca unica (`a1b2c3d4|...`) y solo se
acepta el resultado que la trae de vuelta. Sin eso, una respuesta que llega
tarde se queda en la cola y la siguiente consulta recoge la respuesta
equivocada.

## Limitaciones conocidas

- Packet Tracer **no expone el output de los comandos IOS**: `hacer_ping()` y
  `obtener_tabla_routing()` envian el comando, pero su salida solo se ve en la
  consola del dispositivo dentro de PT. Las consultas por API (`getDevices()`,
  estado de puertos) si devuelven datos.
- `crear_dispositivo()`, `conectar_dispositivos()`, `agregar_modulo_router()` y
  `eliminar_conexion()` confirman el resultado real ([OK] / [ERROR]). El resto de comandos de escritura (configuracion IOS) se
  encolan sin confirmacion: `Exito: Comando enviado` significa encolado, no
  ejecutado.
- Al crear ciertos dispositivos, PT agrega automaticamente un
  `Power Distribution Device0` al canvas. Aparece en los inventarios y no es un
  error.
- `obtener_puertos_dispositivo()` lee los puertos reales del dispositivo en PT,
  incluidos los de las tarjetas instaladas, y dice cuales estan libres.
- `diagnosticar_red()` no ve subinterfaces 802.1Q, VLANs ni tablas de routing:
  que no reporte fallos no garantiza conectividad.
- La ventana Builder Code Editor debe permanecer abierta: es donde vive el loop.