# 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](https://12factor.net/) 配置原则，使用环境变量管理所有敏感信息。
**注意：未配置必选变量时，工具调用将直接返回错误信息，以便 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](https://github.com/astral-sh/uv) 进行全生命周期管理，支持多种运行模式。

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

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

```bash
# 进入目录
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 连通性。

```bash
# 需先设置环境变量
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。

```bash
# 启动 Inspector
npx @modelcontextprotocol/inspector uv run mcp_server.py
```
> 这将打开一个 Web 界面，您可以像在 Claude 中一样点击并从网页调用工具，查看完整的输入/输出/日志。

#### 3. IDE 断点调试 (VS Code / Cursor)
在项目根目录创建 `.vscode/launch.json`：

```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)**
```bash
# 生成 .whl 包
uv pip install build
uv run -m build
# 产物在 dist/firewall_governance_mcp-0.1.0-py3-none-any.whl
```

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

```bash
# 在运行机器上配置环境变量
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`):

```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 代码并维护本地路径。

```json
{
  "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。

---

## �️ 项目结构

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