batfish-q-mcp

batfish-q-mcp

BatfishをAIアシスタント向けのツールとして公開するMCP（Model Context Protocol）サーバーです。ネットワーク設定のスナップショットを指定すれば、Batfishクエリを自分で書かずに、自然な言葉で質問できます。

このサーバーを使うと、アシスタントは次のことができます。

• 厳選された60個のBatfishの質問（ノードのプロパティ、ルーティング、ACL、到達可能性、解析の問題など）を実行する
• 「転送ループがないこと」などのアサーションを個別に、またはYAMLの一括テストとして実行する
• 失敗したノードやインターフェースを使ってスナップショットをフォークし、元のスナップショットとの差分を確認する
• レイヤー3トポロジーとルーティングトポロジーをノードとエッジとして返す

このプロジェクトは、Batfishを使ったStreamlit GUIであるBat-Qから派生したものです。謝辞を参照してください。

プロンプトの例

MCP クライアントにサーバーを接続してスナップショットを読み込んだら、次のように試してみてください。

• 「スナップショットの一覧を表示して、設定が問題なく解析されたか教えてください。」
• 「このスナップショットに転送ループはありますか？」
• 「レイヤー3トポロジーを表示してください。」
• 「r1がダウンした場合、r2からr3への到達可能性はどうなりますか？」
• 「BGPが設定されているノードと、そのピアを教えてください。」

裏では、アシスタントが以下に示すツールを呼び出します。

クイックスタート

1. Batfishを起動する

サーバーを実行するには、起動中のBatfishインスタンスが必要です。最も手早い方法はDockerです。

docker run --rm -p 9996:9996 -p 9997:9997 batfish/allinone

サーバーはデフォルトで 127.0.0.1 に接続します。Batfishが別の場所で実行されている場合は、BATFISH_SERVER を設定してください（例：BATFISH_SERVER=<batfish-host>）。

2. batfish-q-mcpをインストールする

Python >=3.10 が必要です。

git clone https://github.com/martimy/batfish-q-mcp.git
cd batfish-q-mcp

# Recommended: use a virtual environment
python3 -m venv .batmcp
source .batmcp/bin/activate
pip install -e .

別の方法：

pip install -r requirements.txt
pip install -e ".[dev]"   # includes test dependencies

これにより、stdio経由でMCPサーバーを起動するコンソールスクリプト batfish-q-mcp がインストールされます。

3. MCPクライアントを接続する

Claude Desktop、Cursor、その他のstdioクライアント

{
  "mcpServers": {
    "batfish-q-mcp": {
      "command": "batfish-q-mcp",
      "env": { "BATFISH_SERVER": "127.0.0.1" }
    }
  }
}

仮想環境にインストールした場合は、代わりにスクリプトの絶対パスを指定してください（環境を有効にした状態で which batfish-q-mcp を実行すると確認できます）。

{
  "mcpServers": {
    "batfish-q-mcp": {
      "command": "/path/to/batfish-q-mcp/.batmcp/bin/batfish-q-mcp",
      "env": { "BATFISH_SERVER": "127.0.0.1" }
    }
  }
}

新しいサーバーを認識させるため、クライアントを再起動してください。

OpenCode

OpenCodeでは、mcp.servers、type: "local"、配列で指定する command を含む opencode.json（スキーマ：https://opencode.ai/config.json）を使用します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "batfish-q-mcp": {
        "type": "local",
        "command": ["/path/to/batfish-q-mcp/.batmcp/bin/batfish-q-mcp"],
        "environment": {
          "BATFISH_SERVER": "127.0.0.1"
        }
      }
    }
  }
}

このファイルをプロジェクトのルート（または ~/.config/opencode/）に置き、そのディレクトリからOpenCodeを起動または再起動して、MCPサーバーを再読み込みしてください。

注記： OpenCode Code Modeではツールが分離されています。直接呼び出せる batfish_* ツールはありません。たとえば、execute ツールを通じて呼び出してください。

await tools["batfish-q-mcp"].batfish_list_questions({});

4. スナップショットを読み込んで質問する

設定をスナップショットのZIPファイルにまとめ（スナップショットの提供を参照）、ワークスペースに置いて、ファイル名をアシスタントに伝えてください。アシスタントがアップロードし、質問された内容を実行します。

新しいサーバープロセスには、Batfishネットワークがまだ設定されていません。スナップショットを必要とする最初の呼び出しで network（例："NETWORK"）を渡してください。以降、プロセスの終了までその値が使用されます。network を指定せずに batfish_list_snapshots を呼び出すと、Network must be set エラーになります。

サーバーを手動で実行する（任意）

クライアントを介さずにサーバーが起動することを確認するには、次を実行してください。

export BATFISH_SERVER=127.0.0.1
batfish-q-mcp
# or
python -m batfish_mcp.server

stdio経由のJSON-RPC（FastMCP）で通信し、ログをstdoutには出力しません。

スナップショットの提供

• 形式： 設定ファイルを含む Batfish zip を1つ用意します。batfish/ と hosts/ フォルダーは任意です。 たとえば、abc_net.zip には abc_net/configs/R1.cfg、R2.cfg、R3.cfg、FW.cfg と hosts/server_*.json が含まれます。

• 場所： zip をワークスペースに置き、アシスタントにファイル名を伝えます。

• アップロード： アシスタントは zip を base64 でエンコードし、batfish_upload_snapshot(name, zip_base64, network?, overwrite?) を呼び出します。

  • name はサニタイズされます（safe_snapshot_name）。名前が重複する場合、overwrite=true でない限り、一意になるように変更されます（name_1 など）。
  • zip_base64 は、正しいパディング（= または ==）を含む有効な base64 である必要があります。検証はサーバー側で行われます。

• Batfish サーバーにすでにある場合： アシスタントに snapshot と network の名前を伝えれば、アップロードは不要です。

• シェルアクセス： pybatfish を使って直接アップロードすることもできます。

  PYTHONPATH=src python3 - <<'PY'
  import os
  from pybatfish.client.session import Session
  bf = Session(host=os.getenv("BATFISH_SERVER", "127.0.0.1"))
  bf.set_network("NETWORK")
  bf.init_snapshot("abc_net.zip", name="abc_net", overwrite=True)
  print(bf.list_snapshots())
  PY
  

ツール

サーバーは9つのツールを提供します。batfish_run_question を使うと、60個の質問からなるカタログ全体を利用できます。

ツール	説明
batfish_list_questions(category?)	入力タイプと TYPE_HINTS の説明を含む、厳選された60個の質問のカタログです。Batfish サーバーは不要です。
batfish_list_snapshots(network?)	ネットワークのスナップショットです。
batfish_upload_snapshot(name, zip_base64, network?, overwrite?)	スナップショットの zip をアップロードします（base64）。名前はサニタイズされ（safe_snapshot_name）、重複する場合は一意になるように変更されます（name_1 など）。
batfish_run_question(fun, options?, snapshot?, reference_snapshot?, network?)	カタログにある任意の質問を実行します。reference_snapshot と snapshot を指定すると、差分の質問を実行します。JSON セーフな {fun, snapshot, reference_snapshot, status, rows, removed_columns} を返します。
batfish_list_assertions()	pybatfish のライブアサーション名と、パラメーターの説明を含む16項目のレジストリ（specs）を返します。
batfish_run_assertion(name, params?, question?, snapshot?, network?)	アサーションを1つ検証して実行します（回答ベースのアサーションでは、先に回答を取得します）。{type, status, message, snapshot, ran_at, runtime, fun?, answer_rows?} を返します。
batfish_run_assertion_suite(suite_yaml, snapshot?, network?)	YAML スイートを検証（全件成功または全件失敗）して実行します。スキーマについては examples/assertions.yaml を参照してください。results[]、errors[]、summary を返します。
batfish_fork_snapshot(base_name, name?, failed_nodes?, failed_interfaces?, overwrite?, network?)	スナップショットをフォークし、必要に応じてノードまたはインターフェイスを停止してから、差分の質問でフォークとベースを比較します。
batfish_get_topology(kind, snapshot?, network?)	kind="layer3"（インターフェイスのタイトルを含む layer3Edges に基づく）または "routing"（bgpEdges に基づく）を指定します。{kind, snapshot, node_count, edge_count, nodes, edges} を返します。

すべてのツールは、ロックで処理を直列化し、1つの Batfish セッション（BATFISH_SERVER を使用。デフォルトは 127.0.0.1）を共有します。

ツール呼び出しの例

参考までに、プロンプトの例を依頼した場合にアシスタントが呼び出す内容は、おおむね次のとおりです。abc_net.zip をアップロードしてから、次を実行します。

batfish_upload_snapshot(name="abc_net.zip", zip_base64="UEsDBB==", network="NETWORK")
batfish_run_question(fun="nodeProperties", snapshot="abc_net")
batfish_run_assertion(name="assert_no_forwarding_loops", snapshot="abc_net")
batfish_fork_snapshot(base_name="abc_net", failed_nodes=["r1"])
batfish_run_question(fun="differentialReachability",
    options={"pathConstraints": {"startLocation": "r2", "endLocation": "r3"},
             "headers": {"dstIps": "192.168.3.1"}},
    snapshot="abc_net_Fail", reference_snapshot="abc_net")

トポロジー：

batfish_get_topology(kind="layer3", snapshot="abc_net", network="NETWORK")
batfish_get_topology(kind="routing", snapshot="abc_net", network="NETWORK")

OpenCode では、たとえば次のように execute で囲みます。

await tools["batfish-q-mcp"].batfish_run_question({
  fun: "initIssues", snapshot: "abc_net", network: "NETWORK"
});

詳しい手順については、HOW-TO.md を参照してください。

トラブルシューティング

• Network must be set：最初の呼び出しで network="NETWORK" を渡してください。
• zip_base64 is not valid base64: Incorrect padding：base64 -w 0 abc_net.zip で再エンコードします（改行なし）。末尾の = または == はそのまま残してください。手動で削除しないでください。
• スナップショットがすでに存在する：overwrite: true を渡すか、name_1 の接尾辞を受け入れてください。
• 解析上の問題はないのに IP アドレスが間違っている場合：最初に batfish_run_question(fun="initIssues") と fileParseStatus を実行してください。
• 240.254.254.1 への到達性は失敗するが、8.8.8.8 には到達できる場合：240.0.0.0/4 は予約済みであり、Block outgoing traffic using reserved addresses のような ISP の外向きフィルターによって破棄されます。インターネットへの外向き通信をテストするには、パブリック IP を使用してください。

構成

src/batfish_mcp/
  server.py           # FastMCP tools over the headless core
  session.py          # thread-safe singleton Session
  catalog.py          # curated question catalog (60 questions)
  assertion_specs.py  # assertion registry (params as {name, type, optional})
  assertion_io.py     # assertion YAML load/validate/dump
  assertions.py       # assertion runner (session- vs answer-based, PASS/FAIL/ERROR)
  queries.py          # question runner (incl. differential snapshots)
  utils.py            # snapshot-name sanitizing, template helpers
  presenter.py        # pure DataFrame/trace serialization helpers
  hints.py            # TYPE_HINTS: tool-parameter descriptions
  topology.py         # L3 + routing graph construction from answers
tests/
  fakes.py            # FakeBatfish + assertion fake (no server needed)
  test_queries.py
  test_assertions.py
  test_server.py      # MCP tools + wire round-trip
examples/assertions.yaml
HOW-TO.md             # mini tutorial

テスト

pip install -e ".[dev]"
pytest          # no Batfish server required (fakes + one in-memory MCP round-trip)

tests/test_assertions.py では、assertion_specs.py がインストール済みの pybatfish（スクリプト化されたアサーションのシグネチャ）と同期していることも確認します。

謝辞

batfish-q-mcp は、Batfish を使った Streamlit GUI である Bat-Q から派生して始まりました。再利用可能なヘッドレスコア（質問カタログ、アサーションレジストリと実行ツール、回答のシリアライズ、スナップショットツール）は Bat-Q から引き継ぎ、GUI レイヤーを取り除いて MCP トランスポートに置き換えました。両プロジェクトとも Apache-2.0 です。

ライセンス

Apache-2.0（LICENSE を参照）。