Add official MCP server for Batfish (beta)

[Copilot]

• Create pybatfish/mcp/ package with MCP server implementation
• Implement MCP tools: snapshot management, traceroute, reachability, ACL analysis, routing, BGP
• Add mcp>=1.23.0 optional dependency to pyproject.toml
• Add batfish-mcp console script entry point
• Write unit tests for the MCP server in tests/mcp/ (78 tests, 99.4% coverage)
• Add integration tests in tests/integration/test_mcp_server.py (14 tests against live Batfish)
• Mark server as beta in module docstrings, __init__.py, __main__.py, and server instructions
• Remove bf_ prefix from all 23 tool names
• Drop legacy next-hop columns from route results; keep structured Next_Hop
• Fix all mypy errors
• Cache Session per host so question templates are loaded once per process lifetime (single shared session for all tools)
• Fix _parse_interfaces() to raise ValueError for bare node tokens (not node[interface] format)
• Fix get_bgp_session_compatibility docstring to clarify it returns full table unless status is specified
• Fix CI integration test failure: detect_loops fails with empty snapshot; switch to tracert_snapshot
• Extract _resolve_host(), _mgmt_session(), _analysis_session() helpers to centralize duplicated setup logic across all 23 tools
• Remove non-existent Next_Hop_Type / NextHopType columns from _LEGACY_NEXTHOP_COLUMNS
• Unify to single cached session for all tools (remove load_questions=False path)
• Improve unit test coverage to 99.4%: add TestRunBidirectionalTracerouteTool and optional parameter branch tests for all analysis tools

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature Request: Official MCP (Model Context Protocol) Server for Batfish</issue_title>
<issue_description>## Summary

We'd love to see an official MCP (Model Context Protocol) server maintained by the Batfish team, making Batfish natively accessible to AI agents like Claude, Cursor, and any other MCP-compatible client.

Background

Model Context Protocol is an open standard by Anthropic for connecting AI agents to external tools and data sources. It's rapidly becoming the standard integration layer for AI-powered workflows.

The community has already built unofficial MCP wrappers around Batfish (e.g., batfish-mcp-container), which demonstrates clear demand. However, unofficial wrappers have gaps — shallow diffs, missing test coverage, incomplete docs — that an officially maintained server would solve.

Use Case: Pre-Deployment Change Validation

The most compelling use case is AI-assisted change validation:

1. Engineer proposes a config change
2. AI agent loads baseline + proposed snapshots into Batfish via MCP
3. Agent runs compare_snapshots, reachability, traceroute, analyze_acl_rules
4. Agent explains in plain English what changed, what broke, and what the blast radius is
5. Engineer gets a natural language validation report before pushing to production

This closes the gap between "Batfish is powerful" and "most network engineers can actually use it."

What We're Asking For

An official batfish-mcp package or server that exposes core Batfish operations as MCP tools, ideally covering:

• Snapshot management — load, list, delete snapshots (network configs + AWS)
• Change diff — deep comparison of two snapshots (routes, ACLs, interfaces — not just counts)
• Reachability analysis — bidirectional reachability between nodes/subnets
• Traceroute simulation — packet path through proposed topology
• ACL/filter analysis — what flows are permitted/denied and what changed
• Failure impact — blast radius of a node/link failure
• Routing table queries — per-device route changes between snapshots

Why Official Matters

• Ensures tool outputs stay in sync with pybatfish API changes
• Provides test coverage and reliable diffs (the biggest gap in community wrappers)
• Gives the network engineering community a trusted, supported integration point
• Enables CI/CD pipelines to use Batfish via AI agents without custom glue code

References

• MCP Specification
• Community wrapper for reference
• FastMCP — Python MCP server framework

Happy to contribute or collaborate if the team is open to it.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Feature Request: Official MCP (Model Context Protocol) Server for Batfish #969

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[batfish-bot]

This change is 

[dhalperi]

Please mark this clearly as a beta in the docs and MCP instructions and everywhere else it makes sense to do so.

[codecov]

Codecov Report

❌ Patch coverage is 97.06960% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.77%. Comparing base (6582a49) to head (c0f1e8f).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
pybatfish/mcp/__main__.py	0.00%	6 Missing ⚠️
pybatfish/mcp/server.py	99.24%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #970      +/-   ##
==========================================
+ Coverage   86.93%   87.77%   +0.84%     
==========================================
  Files          23       26       +3     
  Lines        3490     3763     +273     
  Branches      457      501      +44     
==========================================
+ Hits         3034     3303     +269     
- Misses        324      330       +6     
+ Partials      132      130       -2     

Files with missing lines	Coverage Δ
pybatfish/mcp/__init__.py	100.00% <100.00%> (ø)
pybatfish/mcp/server.py	99.24% <99.24%> (ø)
pybatfish/mcp/__main__.py	0.00% <0.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dhalperi]

@copilot read review feedback, also get checks and tests to pass

[Copilot]

Pull request overview

Adds a first-party pybatfish.mcp package implementing an MCP (Model Context Protocol) server so MCP clients can drive Batfish workflows via registered tools.

Changes:

• Introduces pybatfish.mcp.server.create_server() (FastMCP) with 23 Batfish tools (snapshots, reachability/traceroute, ACLs, routes, BGP, properties, validations).
• Adds a stdio entrypoint (python -m pybatfish.mcp / batfish-mcp) and packages/dependency wiring via pyproject.toml.
• Adds a new tests/mcp/ suite with mocked-Session integration-style tests plus helper unit tests.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pybatfish/mcp/server.py	Implements the MCP server and tool handlers plus helper functions.
pybatfish/mcp/__main__.py	Provides stdio runtime entrypoint for MCP server execution.
pybatfish/mcp/__init__.py	Exposes create_server() as the package’s public API.
pyproject.toml	Adds mcp optional extra, includes mcp in dev, and registers batfish-mcp console script.
tests/mcp/test_server.py	Adds coverage for helper functions and all tool registrations/behaviors with mocked Session.
tests/mcp/__init__.py	Adds test package marker.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Please mark this clearly as a beta in the docs and MCP instructions and everywhere else it makes sense to do so.

Done in 89bc611. Added [BETA] to the server's instructions string (shown to MCP clients), and .. warning:: **beta** Sphinx warnings to all three module docstrings (__init__.py, __main__.py, server.py + create_server).

[dhalperi]

@copilot please respond to my and your review and push new fixes . Also review the Ci results and make those pass, and review the code coverage from the coverlay check

[Copilot]

@copilot read review feedback, also get checks and tests to pass

Addressed all review feedback in d2ed184 (and prior commits eb54113, 89bc611):

• Session question caching: done (eb54113)
• _parse_interfaces() raises ValueError for bare node tokens: done (d2ed184)
• get_bgp_session_compatibility docstring clarified: done (d2ed184)
• CI integration test detect_loops failure fixed by switching to tracert_snapshot (real configs): done (d2ed184)
• Format check: all files pass ruff format

[Copilot]

@copilot please respond to my and your review and push new fixes . Also review the Ci results and make those pass, and review the code coverage from the coverlay check

All review feedback addressed in a144def (and prior commits d2ed184, eb54113):

Remaining reviewer comment (duplicated setup logic) — done in a144def. Extracted three private helpers:

• _resolve_host(host) — resolves the effective Batfish hostname (arg → BATFISH_HOST env → "localhost")
• _mgmt_session(host, network="") — fresh uncached session for management tools (no questions)
• _analysis_session(host, network, snapshot) — cached session for analysis tools (questions loaded)

All 23 tool functions now use one of these two helpers instead of repeating the 3-4 line setup block. Also fixed a bug: init_snapshot and init_snapshot_from_text were unnecessarily loading question templates (they're management operations). Added 10 new tests for the helpers (65 total).

CI: The integration test failure (detect_loops with empty snapshot) was fixed in d2ed184 by switching to tracert_snapshot. The latest pre-commit run on d2ed184 shows action_required status which is a branch-protection policy (awaiting approval), not a code issue.

Coverage: pybatfish/mcp/server.py was at 50.1% from integration tests (run before the detect_loops fix). With the fix applied and all 14 integration tests passing, coverage will be higher. Unit test coverage of server.py is 84.8%.

[dhalperi]

@copilot few more fixes and questions

[dhalperi]

@copilot - review the code coverage, seems like some important functionality still uncovered

[Copilot]

@copilot - review the code coverage, seems like some important functionality still uncovered

Addressed in c0f1e8f. Added 13 new unit tests covering the uncovered branches:

• New TestRunBidirectionalTracerouteTool class — the run_bidirectional_traceroute tool had no tests at all
• Optional parameter (nodes, vrfs, filters, status, remote_nodes, properties, interfaces, actions) branch tests for check_reachability, analyze_acl, search_filters, compare_routes, get_bgp_session_status, get_bgp_session_compatibility, get_node_properties, get_interface_properties, compare_filters, and get_undefined_references

Coverage improved from 84.6% → 99.4% (78 tests). Only lines 35–36 remain uncovered — the ImportError branch for when the mcp package is not installed, which is not testable in an environment where the package is present.

@copilot read review feedback, also get checks and tests to pass

CI (Pre-commit) is passing (success) on commit a376a16. The latest round of coverage improvements is in c0f1e8f — 78 unit tests, 99.4% coverage of server.py.

[dhalperi]

@dhalperi reviewed 7 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on copilot[bot]).