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で、私が空き時間に個人的な実験として作成しました。私のPCでPT 9.0.0.0810を対象に動作し、スモークテストにも合格していますが、本番環境で使える状態とは考えないでください。バグ、APIの変更、PTのアップデートによる不具合が起こる可能性があります。試してみる場合は、気づいたことをissueで報告してください。

_{15倍速のデモ：MCPクライアントがレシピを実行すると、Packet Tracer 9のキャンバスにデバイス、ケーブル、設定が次々と追加されます。}

作者：Juan Cordero Pascual · ライセンス：MIT 言語：スペイン語（このファイル） · 英語

目次

• Packet Tracer向けMCPをもう1つ作った理由
• 設計思想：キャンバスファースト
• 要件
• クイックスタート
  • MCPクライアントの接続
  • 単一バイナリへのコンパイル
  • テスト
  • エンドツーエンドの手順
• 機能
• 同梱レシピ
• 設定
• ドキュメント
• FAQ
• プロジェクト構成
• 状況

Packet Tracer向けMCPをもう1つ作った理由

PT 6.x～8.x向けのプロジェクトは、サードパーティーの署名付き拡張機能から読み込まれるJSライブラリに依存していました。PT 9.0ではこの方法が使えなくなりました。App Meta Files（.pta）はCiscoによるECDSA署名が必要になったため、オープンソースプロジェクトから提供できなくなったのです。残された方法は、外部からPTのwebviewと通信することです。このサーバーはその方法を採用しています。

• PTのExtensionsメニューからインストールする独自の.pts拡張機能があります。この拡張機能が行うのは、ローカルHTTPブリッジへのポーリングループの起動だけです。
• MCPサーバーが書き込みを必要とするときは、PTのネイティブIPC APIを直接呼び出します。たとえば、ipc.appWindow().getActiveWorkspace().getLogicalWorkspace().addDevice(...)やgetDevice(...).getCommandLine().enterCommand(...)などです。中間ライブラリも、他の場所からコピーした不透明なJSも使いません。
• PTのScript Engineで実行されるJSはすべて、このリポジトリで生成されます。何が送信されているか確認したい場合は、src/ipc/を参照してください。

Canvas First の哲学

ほかのツールでは、メモリ内に「plan」オブジェクトを保持して検証し、 最後にシミュレーターへ書き出します。ここではそのようには動作しません。

• メモリ内に TopologyPlan はありません。 PT にあるものがすべてです。プランはキャンバスです。
• 各レシピは、実行前にキャンバスのスナップショットを再読み込みします。 構築途中のキャンバスに対して同じレシピを2回実行すると、2回目は デバイスを重複させるのではなく、足りないものを完成させます。 意識しなくても冪等に実行できます。
• 検証は内部構造ではなく、実際のキャンバスに対して行います。 問題（重複した 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/ にあります。

ヒント

Node ではなく Bun を使う理由は？ 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. セッションごとに1回、Extensions > MCP Bridge からウィンドウを開きます。

ウィンドウが読み込まれると、ポーリングが自動的に開始されます。すべて正常に 動作していることを確認するには、pt_bridge_status を実行します。1秒以内に connected: true が返るはずです。

インストール手順の全容は docs/BOOTSTRAP.md をご覧ください。

MCP エンドポイントは次のとおりです。

http://127.0.0.1:39001/mcp

メモ

:39001 を使う理由。 PT 9 は、Cisco の署名付きハンドシェイクを使用する 独自のネイティブ IPC（非公開）をすでに :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

単体テストでは、サブネット計算、キャンバスの検査、スナップショットのパーサー、差分、ブループリントの検証、および各レシピの CLI ビルダーを網羅しています。実行時に PT を起動しておく必要はありません。

エンドツーエンドの手順

ブリッジが接続されている場合（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 ツールを公開します。

ブリッジと診断

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（PT に触れずにレシピの IOS CLI をオフラインで生成します。ドキュメント作成、授業、または実機でのラボ再現に便利です）、pt_inspect_ports （ポートごとの状態：リンク／アップ／プロトコル、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（ネイティブ IPC API 経由で Server-PT に DHCP サーバーを設定）、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 が同じファイルシステムを共有している場合）、および .pkt をネットワーク経由で転送するための pt_save_pkt_to_bytes と pt_open_pkt_from_bytes。圧縮形式の .pkz は機能しません。API JS はメソッドを公開していますが、返されるバイト列は 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 はリストをその場で返します。組み込みレシピは次のとおりです。

最初の 3 つは 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 トランスポート、tools、レシピ、IPC ジェネレーター、HTTP bridge）、canvas-first を採用する理由、.pkt の永続化、対象範囲外の内容について説明します。
• docs/BOOTSTRAP.md — .pts 拡張機能のインストール、ポーリングの仕組み、.pts の再構築を希望する開発者向けのセクションについて説明します。
• docs/COVERAGE.md — 実際の PT 9 で検証済みの内容、その状態（verified-pt9 / contract-verified / partial / broken / dead-end）、スモークテストの実行記録への参照、ユーザーに影響するシミュレーターの既知の制限について説明します。
• docs/TOOLS.md — 57 個の MCP tools のリファレンスです。パラメーター、動作、注記を記載しています。
• docs/RECIPES.md — recipes（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 は、MCP ではなく PT API の制限により途中までしか実行できません。
• エンドツーエンドで検証済みのレイヤー：L2 スイッチング、L3 サービス（NAT、ACL、DHCP）、動的ルーティング（OSPF、BGP、HSRP、EIGRP）、OSPFv3 を使った IPv6、VoIP（CME + ephone-dn）、シミュレーションと運用、.pkt の永続化。

詳細なエビデンス（スモークテストの実行結果、スクリーンショット、既知の制限）は docs/COVERAGE.md にあります。