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

```text
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

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

Para desarrollo y pruebas:

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

## Ejecutar el servidor

Modo recomendado, HTTP persistente:

```bash
python -m src.packet_tracer_mcp
```

Endpoints locales:

| Servicio | URL | Uso |
|---|---|---|
| MCP Server | `http://127.0.0.1:39000/mcp` | Cliente MCP llama tools/resources |
| Packet Tracer Bridge | `http://127.0.0.1:54321` | PTBuilder consulta comandos pendientes |

Modo stdio para clientes legacy:

```bash
python -m src.packet_tracer_mcp --stdio
```

Puerto MCP personalizado:

```bash
PT_MCP_PORT=39001 python -m src.packet_tracer_mcp
```

## Configurar Cliente MCP

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "packet-tracer": {
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}
```

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "packet-tracer": {
      "url": "http://127.0.0.1:39000/mcp"
    }
  }
}
```

## Quickstart: Prompt A Packet Tracer

1. Inicia el servidor MCP:

```bash
python -m src.packet_tracer_mcp
```

2. Abre Cisco Packet Tracer.

3. Abre `Extensions > Builder Code Editor`.

4. En tu cliente MCP ejecuta:

```text
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:

```text
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:

| Tool | Descripción |
|---|---|
| `pt_prompt_plan` | Convierte un prompt libre en un plan JSON validado. |
| `pt_prompt_deploy` | Pipeline completo: prompt, plan, validate/fix, export y live deploy. |
| `pt_bridge_status` | Verifica si el bridge está activo y Packet Tracer está conectado. |
| `pt_live_deploy` | Envía un plan JSON ya generado a Packet Tracer en tiempo real. |
| `pt_query_topology` | Lista los dispositivos visibles en la topología activa de PT. |
| `pt_plan_topology` | Crea un plan desde parámetros estructurados. |
| `pt_validate_plan` | Valida el plan contra reglas de catálogo, cables, puertos e IPs. |
| `pt_fix_plan` | Corrige errores comunes automáticamente. |
| `pt_generate_script` | Genera JavaScript PTBuilder. |
| `pt_generate_configs` | Genera configuraciones IOS por dispositivo. |
| `pt_full_build` | Pipeline clásico estructurado: plan, validación, scripts y configs. |
| `pt_export` | Exporta scripts, configs y plan JSON a archivos. |
| `pt_export_documentation` | Genera tabla de direccionamiento, configs y comandos de verificación. |
| `pt_list_presets` | Lista escenarios listos. |
| `pt_load_preset` | Carga un preset y genera una topología completa. |

## Recursos MCP

| URI | Descripción |
|---|---|
| `pt://catalog/devices` | Catálogo completo de modelos y puertos. |
| `pt://catalog/cables` | Tipos de cable soportados. |
| `pt://catalog/aliases` | Alias de modelos y nombres comunes. |
| `pt://catalog/templates` | Plantillas de topología. |
| `pt://capabilities` | Capacidades, límites y versión del servidor. |
| `pt://prompts/ptbuilder-guide` | Guía para generar scripts PTBuilder compatibles. |

## Artefactos Exportados

`pt_prompt_deploy`, `pt_export` y `pt_deploy` generan una carpeta de proyecto:

```text
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:

```text
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

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

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

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

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

Para forzar parámetros desde un agente:

```json
{
  "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:

| Categoría | Ejemplos |
|---|---|
| Routers | `1941`, `2901`, `2911`, `ISR4321`, `ISR4331`, `ISR4351` |
| Switches | `2960-24TT`, `2960-48TT`, `3560-24PS`, `3650-24PS`, `3850-24T` |
| Hosts | `PC-PT`, `Laptop-PT`, `Server-PT`, `Tablet-PT`, `SMARTPHONE-PT` |
| WAN | `Cloud-PT`, `DSL-Modem-PT`, `Cable Modem-PT` |
| Seguridad/Wireless | `ASA5506`, `WRT300N`, `AccessPoint-PT`, `WLC-PT` |

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:

```javascript
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:

```bash
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

```text
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.