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<br>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/                # 辅助数据