# HS-StoneOS-MCP Server

基于 MCP (Model Context Protocol) 协议的 Hillstone StoneOS 防火墙数据查询服务器。通过 stdio 传输将 129 个防火墙管理工具暴露给 AI 助手，实现自然语言驱动的网络运维。

## 功能概览

提供 **129 个 MCP 工具**，覆盖 7 大业务模块：

| 模块 | 文件 | 工具数 | 典型工具 |
|------|------|--------|----------|
| 设备管理 | `tools/index.ts` | 1 | `list_devices` |
| 系统管理 | `tools/system.ts` | 35 | `get_system_info`、`emulate_packet_trace`、HA 配置、SNMP、许可证、虚拟系统、抓包、丢包统计 |
| 网络配置 | `tools/network.ts` | 44 | `get_interface_list`、`get_zone_list`、路由、VPN（IPSec/SSL/GRE/VXLAN）、DNS、组播、隧道 |
| 流量监控 | `tools/monitor.ts` | 22 | `get_app_rank`、`get_current_session_count`、CPU/内存趋势、链路性能、日志 |
| 策略管理 | `tools/policy.ts` | 11 | `get_policy_list`、SNAT/DNAT/BNAT、`get_qos_config`、策略统计 |
| 威胁安全 | `tools/threat.ts` | 7 | `get_threat_event_list`、威胁日志聚合、热点威胁情报 |
| 特征库 | `tools/feature.ts` | 9 | `get_signature_config`��IPS 模板、URL 过滤、应用类别 |

完整工具目录见 [`TOOLS_CATALOG.md`](./TOOLS_CATALOG.md)，架构细节见 [`mcp-stdio-server-exploration.md`](./mcp-stdio-server-exploration.md)。

## 快速开始

### 1. 添加设备配置

创建项目根目录下的 `devices.json`：

```json
{
  "devices": [
    {
      "id": "fw-192.168.76.188",
      "name": "云界防火墙",
      "host": "192.168.76.188",
      "username": "admin",
      "password": "your_password",
      "protocol": "https",
      "isDefault": true
    }
  ],
  "defaultLocale": "zh_CN"
}
```

> **认证方式**（二选一）：
> - `username` + `password`：传统用户名/密码登录
> - `api_token`：API Token 登录（StoneOS 5.5R12 / 5.5R10F5 以上版本支持，**推荐**，优先级高于用户名/密码）
>
> `password` 和 `api_token` 以明文存储，请注意文件系统权限。配置多台设备时只需在 `devices` 数组中追加条目。

### 2. 安装依赖

```bash
npm install
```

### 3. 构建

```bash
npm run build
```

构建产物为 `dist/hs-stoneos-mcp.js`，esbuild 打包的单文件 ESM，约 1.7 MB，无需 node_modules 即可独立运行。

### 4. 运行

```bash
npm start          # 开发模式：tsx 直接执行 TypeScript 源码
node dist/hs-stoneos-mcp.js   # 生产模式：运行构建产物
```

服务启动后将通过 stdio 监听 MCP JSON-RPC 消息。

## 配置详解

### devices.json — 多设备凭据

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | string | 是 | 设备唯一标识，各工具通过 `device_id` 参数引用 |
| `name` | string | 是 | 设备显示名称 |
| `host` | string | 是 | 设备 IP 或域名 |
| `username` | string | 否* | 用户名（需配合 password） |
| `password` | string | 否* | 密码（需配合 username） |
| `api_token` | string | 否* | API Token（5.5R12+，优先于 username/password） |
| `protocol` | string | 否 | 协议，默认 `https` |
| `isDefault` | boolean | 否 | 是否为默认设备，不传 `device_id` 时使用 |

> *username+password 与 api_token 至少提供一种。

### tools-config.json — 工具开关

129 个工具默认大多禁用，按需在 `src/tools-config.json` 中启用：

```json
{
  "tools": [
    { "name": "get_system_info", "description": "...", "enabled": true },
    { "name": "get_threat_event_list", "description": "...", "enabled": false }
  ]
}
```

修改后重启 MCP Server 生效。可通过环境变量 `TOOLS_CONFIG_PATH` 指定自定义路径。

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DEVICES_CONFIG_PATH` | devices.json 的绝对路径 | `./devices.json` |
| `TOOLS_CONFIG_PATH` | tools-config.json 的绝对路径 | `src/tools-config.json` |

> 早期版本使用 `HILLSTONE_HOST`、`HILLSTONE_USER` 等环境变量存放凭据，已被 `devices.json` 替代，不再支持。

## 项目结构

```
HS-StoneOS-MCP-20260506/
├── src/
│   ├── index.ts                  # 入口：DeviceManager + ToolFilter + 工具注册 + Stdio 启动
│   ├── .env                      # 环境变量（凭据已迁移至 devices.json）
│   ├── tools-config.json         # 工具启用/禁用开关
│   ├── client/
│   │   ├── fw-client.ts          # StoneOS API 客户端（双重认证、session 管理、自动重登录）
│   │   └── device-manager.ts     # 多设备管理器（配置加载、FwClient 懒加载、缓存）
│   ├── tools/
│   │   ├── index.ts              # 工具注册编排器 + list_devices
│   │   ├── system.ts             # 系统管理（35 工具）
│   │   ├── network.ts            # 网络配置（44 工具）
│   │   ├── monitor.ts            # 流量监控（22 工具）
│   │   ├── policy.ts             # 策略/NAT/QoS（11 工具）
│   │   ├── threat.ts             # 威胁/安全（7 工具）
│   │   └── feature.ts            # 特征库（9 工具）
│   └── utils/
│       ├── response.ts           # MCP 响应构造器（ok / err / pickFields）
│       ├── traffic-utils.ts      # Zod schema + 流量字段白名单
│       └── tool-filter.ts        # 工具启用/禁用运行时过滤器
├── scripts/
│   ├── build.ts                  # esbuild 打包 + 静态资源复制
│   └── list-tools.ts             # 工具枚举脚本
├── dist/                         # 构建产物（git ignored）
│   └── hs-stoneos-mcp.js         # 单文件 ESM，~1.7 MB
├── devices.json                  # 多设备凭据配置
├── package.json
├── tsconfig.json
├── README.md
├── TOOLS_CATALOG.md              # 完整工具目录
└── mcp-stdio-server-exploration.md  # 架构/实现文档
```

## MCP Client 集成

### WorkBuddy

在 `~/.workbuddy/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "hs-stoneos": {
      "command": "node",
      "args": ["F:/Workbuddy_path/StoneOS MCP/HS-StoneOS-MCP-20260506/dist/hs-stoneos-mcp.js"],
      "env": {
        "DEVICES_CONFIG_PATH": "F:/Workbuddy_path/StoneOS MCP/HS-StoneOS-MCP-20260506/devices.json"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio hs-stoneos -- node "F:/Workbuddy_path/StoneOS MCP/HS-StoneOS-MCP-20260506/dist/hs-stoneos-mcp.js" --scope user
```

然后在 `~/.claude.json` 的对应条目中添加 `env` 字段：

```json
"env": {
  "DEVICES_CONFIG_PATH": "F:/Workbuddy_path/StoneOS MCP/HS-StoneOS-MCP-20260506/devices.json"
}
```

### MCP Inspector（调试）

```bash
npx @modelcontextprotocol/inspector
```

- Transport Type: `STDIO`
- Command: `node`
- Arguments: `dist/hs-stoneos-mcp.js`

> 注意：Inspector 的工作目录需能访问 `devices.json`，或通过 `DEVICES_CONFIG_PATH` 环境变量指定绝对路径。

## 可用脚本

| 命令 | 说明 |
|------|------|
| `npm start` | 使用 tsx 直接运行 TypeScript 源码（开发模式） |
| `npm run build` | esbuild 构建：单文件打包 + 复制静态资源 |
| `npm run typecheck` | TypeScript 类型检查（`tsc --noEmit`，不输出文件） |

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 运行时 | Node.js 20+ / TypeScript 6.x | ESM 模块系统 |
| MCP SDK | @modelcontextprotocol/sdk ^1.29.0 | stdio 传输 |
| HTTP 客户端 | axios ^1.15.2 | StoneOS REST API 调用 |
| Schema 验证 | zod ^4.3.6 | 工具参数校验 |
| 构建 | esbuild ^0.28.0 | 单文件 ESM 打包 |
| 目标 API | StoneOS REST API 5.5R12P2 | 100+ API 路径 |

## 相关文档

| 文档 | 内容 |
|------|------|
| [`TOOLS_CATALOG.md`](./TOOLS_CATALOG.md) | 完整工具目录（按 StoneOS API 层级结构，113 条） |
| [`mcp-stdio-server-exploration.md`](./mcp-stdio-server-exploration.md) | 架构设计、认证流程、FwClient 实现、工具注册机制 |