How do I use Firewall Governance MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Firewall Governance MCP Server search for firewall policies matching source IP 10.1.2.50" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Firewall Governance MCP Server 🛡️

这是一个标准的 MCP (Model Context Protocol) 服务端，专为防火墙策略治理设计。它集成了 CMDB 资产查询和 Panorama/Firewall 策略审计能力，支持通过任何 MCP 客户端（Claude Desktop, Cursor, Dify, etc.）直接调用。

🛠️ 工具能力 (Tools)

本服务提供以下标准的 MCP 工具：

工具名称	功能描述	核心输入	预期输出
`search_cmdb_asset`	资产查询	`keyword`: 系统名/IP/缩写	包含 IP、Owner、DC、描述的资产列表
`get_firewall_object`	对象透视	`ip_address`: 目标 IP	防火墙对象详情 (Name, Zone, Tags)
`search_firewall_policy`	策略审计	`source_ip`: 源 IP `destination_ip`: 目的 IP (可选)	匹配的安全策略列表 (含 Action, Service, Shadow 状态)

📋 配置说明 (Configuration)

本项目遵循标准 12-Factor App 配置原则，使用环境变量管理所有敏感信息。 注意：未配置必选变量时，工具调用将直接返回错误信息，以便 Agent 进行自我诊断。

必选配置 (Firewall)

用于连接 Panorama 或 NGFW 进行策略和对象查询。

变量名	示例值	描述
`FW_HOSTNAME`	`10.1.2.150`	防火墙/Panorama 管理 IP 或域名
`FW_USERNAME`	`admin`	管理账号
`FW_PASSWORD`	`Secret123!`	管理员密码

必选配置 (CMDB)

用于查询业务系统资产信息。

变量名	示例值	描述
`CMDB_SERVER`	`http://10.1.4.100`	CMDB API 地址
`CMDB_APP_ID`	`c9a37...`	CMDB App ID
`CMDB_APP_SECRET`	`3d22e...`	CMDB App Secret
`CMDB_VIEW_ID`	`f0410...`	CMDB View ID (视图模型ID)

🚀 部署指南 (Deployment)

本项目使用 uv 进行全生命周期管理，支持多种运行模式。

方式一：开发调试 (Local Dev)

适用于本地开发调试或 Claude Desktop 直连。

# 进入目录
cd ai_agents/firewall_governance/firewall-mcp

# 1. 配置环境变量
export FW_HOSTNAME="10.1.2.150"
export FW_USERNAME="admin"
export FW_PASSWORD="your_password"
# ... 配置其他 CMDB 变量

# 2. 启动服务 (Stdio 模式)
uv run mcp_server.py

调试指南 (Debugging) 🐞

开发人员可以通过以下三种方式调试工具逻辑：

1. 脚本直测 (最快)

底层工具脚本 (fw_tool.py, cmdb_tool.py) 都包含 __main__ 测试入口。可以直接运行它们来验证 API 连通性。

# 需先设置环境变量
export FW_HOSTNAME=10.1.2.150 FW_PASSWORD=xxx

# 运行防火墙工具测试
uv run fw_tool.py

# 运行 CMDB 工具测试
uv run cmdb_tool.py

2. MCP Inspector (交互式调试)

使用官方 Inspector UI 在浏览器中测试所有 MCP Tools。

# 启动 Inspector
npx @modelcontextprotocol/inspector uv run mcp_server.py

这将打开一个 Web 界面，您可以像在 Claude 中一样点击并从网页调用工具，查看完整的输入/输出/日志。

3. IDE 断点调试 (VS Code / Cursor)

在项目根目录创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug FW Tool",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/firewall-mcp/fw_tool.py",
      "console": "integratedTerminal",
      "env": {
        "FW_HOSTNAME": "10.1.2.150",
        "FW_USERNAME": "admin",
        "FW_PASSWORD": "your_password"
      }
    },
    {
      "name": "Debug MCP Server",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/firewall-mcp/mcp_server.py",
      "console": "integratedTerminal",
      "env": { ... }
    }
  ]
}

方式二：内网无源码分发 (uvx style) - 推荐 🌟

这是公司内网最推荐的分发方式，支持离线或无源码环境。

1. 构建阶段 (Builder Machine)

# 生成 .whl 包
uv pip install build
uv run -m build
# 产物在 dist/firewall_governance_mcp-0.1.0-py3-none-any.whl

2. 运行阶段 (User Machine) 用户只需拿到 .whl 文件，无需安装依赖，单行命令即用：

# 在运行机器上配置环境变量
export FW_HOSTNAME=10.1.2.150
export FW_PASSWORD=xxx
# ...

# 一键运行 (uv 会自动全托管环境)
uvx --from ./dist/firewall_governance_mcp-0.1.0-py3-none-any.whl firewall-mcp

方式三: Claude Desktop 集成 (Remote Git) 🌟 [推荐]

这是最推荐的集成方式。利用 uvx 直接从 Git 仓库拉取安装，支持自动环境隔离与依赖管理。前提: 您的机器需要拥有该 Git 仓库的访问权限 (SSH Key)。

编辑配置文件 (claude_desktop_config.json):

{
  "mcpServers": {
    "firewall-governance": {
      "command": "uvx",
      "args": [
        "--from",
        "git+ssh://git@10.1.2.68/script/ae/mcp-server.git#subdirectory=firewall-mcp",
        "firewall-mcp"
      ],
      "env": {
        "FW_HOSTNAME": "10.1.2.150",
        "FW_USERNAME": "admin",
        "FW_PASSWORD": "your_password",
        "CMDB_SERVER": "http://10.1.4.100",
        "CMDB_APP_ID": "...",
        "CMDB_APP_SECRET": "..."
      }
    }
  }
}

方式四: Claude Desktop 集成 (Local Source) [不推荐]

仅建议在开发调试时使用。需要手动 clone 代码并维护本地路径。

{
  "mcpServers": {
    "firewall-governance-local": {
      "command": "uv",
      "args": [
        "run",
        "/absolute/path/to/ai_agents/firewall_governance/firewall-mcp/mcp_server.py"
      ],
      "env": {
        "FW_HOSTNAME": "10.1.2.150",
        "FW_USERNAME": "admin",
        "FW_PASSWORD": "..."
      }
    }
  }
}

📦 依赖列表 (Dependencies)

核心依赖如下 (详见 pyproject.toml):

mcp: 官方 Model Context Protocol SDK (实现 FastMCP 服务端)。
requests: 处理所有 HTTP REST API 调用 (PAN-OS, CMDB)。
python-dotenv: 支持从 .env 文件加载配置。
minzhi-sdk: (可选) 内部系统集成 SDK。

�️ 项目结构

.
├── pyproject.toml       # 项目元数据与依赖定义
├── mcp_server.py        # MCP Server 入口
├── fw_tool.py           # 防火墙交互逻辑
├── cmdb_tool.py         # CMDB 交互逻辑
└── data/                # 辅助数据

Firewall Governance MCP Server