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，架构细节见 mcp-stdio-server-exploration.md。

快速开始

1. 添加设备配置

创建项目根目录下的 devices.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. 安装依赖

npm install

3. 构建

npm run build

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

4. 运行

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 中启用：

{
  "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 中添加：

{
  "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

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 字段：

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

MCP Inspector（调试）

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	完整工具目录（按 StoneOS API 层级结构，113 条）
mcp-stdio-server-exploration.md	架构设计、认证流程、FwClient 实现、工具注册机制