packet-tracer-mcp

packet-tracer-mcp

用于从外部控制 Cisco Packet Tracer 9.0 的 Model Context Protocol 服务。一个自定义扩展挂接到 PT 编辑器，启动本地 HTTP 桥接服务，MCP 服务再通过 PT 原生 IPC API 调用它，以创建拓扑、配置路由器、启动模拟等。使用 Bun 和 TypeScript 编写。

警告

实验性项目。 当前版本为 0.1.0，是我利用空闲时间完成的个人实验。它在我的电脑上可与 PT 9.0.0.0810 配合使用，并通过了冒烟测试，但请勿将其视为可用于生产环境的软件。请做好遇到 bug、API 变更以及 PT 更新后功能损坏的准备。如果你愿意试用，欢迎针对发现的问题提交 issues。

_{演示加速了 x15：MCP 客户端启动一份操作方案，Packet Tracer 9 的画布便会自动填满（设备、布线、配置）。}

作者：Juan Cordero Pascual · 许可证：MIT 语言：西班牙语（本文档） · English

目录

• 为什么还要做一个 Packet Tracer MCP
• 理念：画布优先
• 要求
• 快速开始
  • 连接 MCP 客户端
  • 编译为单个二进制文件
  • 测试
  • 端到端演练
• 功能
• 内置操作方案
• 配置
• 文档
• 常见问题
• 项目结构
• 状态

为什么还要做一个 Packet Tracer MCP

面向 PT 6.x–8.x 的项目依赖由第三方签名扩展加载的 JS 库。PT 9.0 封堵了这条路径：现在 App Meta Files（.pta）必须由 Cisco 使用 ECDSA 签名，因此开源项目无法提供此类文件。剩下的替代方案是从外部与 PT 的 webview 通信，而本服务正是这样做的：

• 这里有一个自定义 .pts 扩展，可通过 PT 的 Extensions 菜单安装。它唯一的作用是启动一个循环，持续轮询本地 HTTP 桥接服务。
• 当 MCP 服务需要写入内容时，会直接调用 PT 原生 IPC API：例如 ipc.appWindow().getActiveWorkspace().getLogicalWorkspace().addDevice(...) 或 getDevice(...).getCommandLine().enterCommand(...)。无需中间库，也不使用从其他地方复制的晦涩 JS。
• 最终在 PT Script Engine 中执行的所有 JS 都由此仓库生成。若想了解发送的内容，请查看 src/ipc/。

理念：画布优先

其他工具会在内存中维护一个“plan”对象，对其进行验证，然后 最后再将其写入模拟器。这里并非如此：

• 内存中没有任何 TopologyPlan。 PT 里有什么就是什么； 计划就是画布。
• 每个配方都会在执行前重新读取画布快照。 如果你在构建到一半的画布上运行两次，第二次会补齐缺少的部分， 而不是重复创建设备。无需刻意考虑，它就能实现幂等。
• 验证针对实时画布进行，而不是针对内部结构。出错时 （IP 重复、对等端位于不同子网、路由器已关闭），你可以直接在 PT 中看到， 而不是在抽象图中看到。
• 持久化保存的是快照，而不是计划。 回退 意味着将当前画布与之前的转储进行比较，查看发生了哪些变化。没有神奇的重新水合。

详情请参阅 docs/ARCHITECTURE.md。

要求

• Cisco Packet Tracer 9.0（macOS、Windows 或 Linux）。
• Bun >=1.2。仅使用 Node 不行：代码是 TypeScript，并由 Bun 直接运行，无需预先编译。
• 在 PT 中安装扩展 mcp-bridge.pts。它位于仓库的 extension/dist/ 中。

提示

为什么用 Bun 而不是 Node？ Bun 原生运行 .ts，启动仅需 几毫秒，并且内置 fetch、HTTP 和测试运行器，无需安装 依赖项。如果你只有 Node，可以使用 curl -fsSL https://bun.sh/install | bash 安装 Bun（或在 macOS 上运行 brew install bun）。它与 Node 共存，互不干扰。

快速启动

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

在 Packet Tracer 9 中：

1. 依次选择 Extensions > Scripting > Configure PT Script Modules > Add，然后 选择 extension/dist/mcp-bridge.pts。
2. 将扩展设为启用状态。
3. 每次会话中，通过 Extensions > MCP Bridge 打开窗口一次。

窗口加载后，轮询会自动启动。要确认一切正常，请运行 pt_bridge_status：应在不到一秒内返回 connected: true。

完整安装流程请参阅 docs/BOOTSTRAP.md。

MCP 端点为：

http://127.0.0.1:39001/mcp

说明

为什么是 :39001。 PT 9 已有自己的原生 IPC（未公开文档， 握手由 Cisco 签名），监听在 :39000。 为避免冲突，并明确表明 MCP 服务是独立的，该服务 监听在 :39001。如果你觉得不方便，可以通过环境变量 PACKETTRACER_MCP_PORT 更改端口。

连接 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"}}}'

编译为单个二进制文件

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

测试

bun test

单元测试套件涵盖子网划分算术、画布检查、快照解析器、差异比较、blueprint 验证，以及每个配方的 CLI 构建器。运行测试无需启动 PT。

端到端流程

在 bridge 已连接（pt_bridge_status → connected: true）的情况下，完整会话大致如下：

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

如果过程中出了问题，pt_mend_canvas 会应用保守的修复（例如，启动已经接好线但处于关闭状态的设备），并告知哪些内容它不敢改动。

功能

packet-tracer-mcp 提供 57 个 MCP 工具，按领域分组。

Bridge 和诊断

pt_bridge_status、pt_ping、pt_clear_canvas。

目录和发现

pt_list_devices、pt_list_modules、pt_list_recipes、 pt_list_snapshots、pt_get_device_details。

实时工作区检查（只读）

pt_query_topology、pt_inspect_canvas、pt_explain_canvas、 pt_forecast（配方试运行）、pt_generate_configs（离线生成配方的 IOS CLI，不会修改 PT——适用于文档、课堂教学，或在真实硬件上重现实验）， pt_inspect_ports（逐端口状态：link/up/proto、MAC、IP/掩码、无线状态）， pt_read_vlans（读取每台交换机的实时 VLAN 基础信息）、pt_read_acl（通过 AclProcess 读取已配置的 ACL）、pt_show_bgp_routes（将 show ip bgp 解析为结构化行）、pt_read_project_metadata （当前 .pkt 的描述/版本/文件名）。

画布基础编辑

pt_add_device、pt_add_module、pt_create_link、pt_delete_device、 pt_delete_link、pt_move_device、pt_auto_layout（将整个 画布重新排列为分层网格，检测中转路由器并将其放到第二层）、pt_rename_device、 pt_set_pc、pt_set_device_power（幂等切换 Device.setPower）、 pt_add_canvas_annotation（添加注释/线条/圆圈）、 pt_manage_clusters（列出/删除/解散逻辑集群）、 pt_send_raw（逃生通道：在 Script Engine 中执行任意 JS）。

配方级编辑（编排）

pt_cook_topology、pt_mend_canvas、pt_plan_review（对 ≥3 台路由器的拓扑进行强制 预检）、pt_apply_switching、pt_apply_services、pt_configure_server_dhcp（通过原生 API IPC 配置 Server-PT 上的 DHCP server）、pt_configure_subinterface（用于 router-on-a-stick 的 802.1Q 子接口）、pt_apply_advanced_routing、pt_apply_ipv6、 pt_apply_voip、pt_apply_wireless。

持久化（快照）

pt_save_snapshot、pt_load_snapshot、pt_diff_snapshots。快照会作为画布转储保存到磁盘。加载快照不会覆盖任何内容：它会显示快照与当前 PT 内容之间的差异，由你决定如何处理。

原生 .pkt 持久化

pt_save_pkt、pt_open_pkt（服务器和 PT 共用 filesystem 时），以及用于通过网络传输 .pkt 的 pt_save_pkt_to_bytes 和 pt_open_pkt_from_bytes。压缩格式 .pkz 无法使用： JS API 虽然暴露了相关方法，但它返回的字节在 PT 9.0.0.0810 中无效。

路由器和交换机 CLI

pt_run_cli、pt_run_cli_bulk、pt_show_running（可选使用 | section）。

模拟和操作

pt_simulation_mode（切换 Realtime↔Simulation）、pt_simulation_play （播放/后退/前进/重置）、pt_send_pdu（发送源自本机的 Simple PDU）、 pt_traceroute、pt_screenshot（工作区 PNG/JPG 截图）。

内置方案

pt_list_recipes 会实时返回列表。内置方案如下：

前三种方案支持 routing: 'static' | 'ospf' | 'eigrp' | 'rip' | 'none' 和 dhcp: true|false。campus_vlan 还接受 startVlanId、 vlanStep 和 lanPool。wifi_lan 接受 ssid、security、psk 和 channel。

配置

环境变量（均为可选）：

文档

• AGENTS.md — 面向使用此服务的 LLM 的操作指南：布线约定（LAN Gigabit 与 WAN serial）、用户 LAN 与传输 LAN、推荐的创建 + 自动布局流程、应避免的常见错误。
• docs/ARCHITECTURE.md — 各层（MCP 传输、工具、方案、IPC 生成器、HTTP bridge）、为何采用 canvas-first、.pkt 持久化，以及不在支持范围内的内容。
• docs/BOOTSTRAP.md — .pts 扩展的安装、轮询机制详解，以及面向希望重建 .pts 的开发者的章节。
• docs/COVERAGE.md — 已针对真实 PT 9 验证的内容及其状态（verified-pt9 / contract-verified / partial / broken / dead-end）、smoke run 参考，以及影响用户的已知模拟器限制。
• docs/TOOLS.md — 57 个 MCP 工具的参考文档，包含参数、行为和说明。
• docs/RECIPES.md — 方案目录（chain、star、branch_office、campus_vlan、edge_nat、wifi_lan、voip_lab、ipv6_lab、dual_isp），包含参数、示例和预期结果。
• docs/TROUBLESHOOTING.md — 实际遇到的症状、可能原因和修复方法。下方的 FAQ 是摘要。
• CHANGELOG.md — 按 Keep a Changelog 格式记录每个版本包含的内容。
• CONTRIBUTING.md — 如何提交 issue、本地环境设置、代码约定和提交规范。
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1。
• SECURITY.md — 安全政策和漏洞报告方式。

项目结构

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)

常见问题

常见错误（简答）

完整列表请参阅 docs/TROUBLESHOOTING.md。

状态

已针对 Cisco Packet Tracer 9.0.0.0810 完成测试：

• 目录中的 54 / 54 个型号均标记为 verified-pt9。
• 57 个 MCP 工具，均有单元测试。
• 9 个配方中有 8 个已通过端到端验证（chain、star、 branch_office、campus_vlan、edge_nat、dual_isp、voip_lab、 ipv6_lab）。第 9 个配方 wifi_lan 因 PT API 的限制（而非 MCP 的限制）而无法完成。
• 已端到端验证的层包括：L2 交换、L3 服务（NAT、ACL、 DHCP）、动态路由（OSPF、BGP、HSRP、EIGRP）、使用 OSPFv3 的 IPv6、 VoIP（CME + ephone-dn）、模拟与操作，以及 .pkt 持久化。

详细证据（冒烟测试运行、屏幕截图和已知限制）请参阅 docs/COVERAGE.md。