AI导哈

无线控制器管理服务器

Ruckus Virtual SmartZone (vSZ)无线控制器的Model Context Protocol服务器，提供52种工具用于查询和管理AP、WLAN、区域、客户端、告警等。

  • by 0xEkho
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 0xEkho/RUCKUS-vSZ-MCP

使用说明

Ruckus虚拟智能区——MCP服务器🔌

模型上下文协议服务器 用于Ruckus虚拟智能区（vSZ）无线控制器管理。 暴露 52工具 跨12个模块，直接从LLM查询和管理AP、WLAN、区域、客户端、警报等。

🚀 快速开始

先决条件

安装

git clone https://github.com/0xEkho/Ruckus-vSZ-MCP.git
cd Ruckus-vSZ-MCP
cp .env.example .env    # Set VSZ_USERNAME & VSZ_PASSWORD
uv sync

跑

uv run ruckus-vsz-mcp

使用MCP检查员进行测试

npx @modelcontextprotocol/inspector uv run ruckus-vsz-mcp

Docker（SSE/可流式传输http）

cp .env.example .env    # Set VSZ_USERNAME, VSZ_PASSWORD, MCP_TRANSPORT=sse
docker compose up -d
docker compose logs -f

服务器监听端口 8081 默认情况下（可通过配置 MCP_PORT).

� 架构和连接模型

┌─────────────┐   STDIO    ┌──────────────────┐   HTTPS/8443   ┌────────────┐
│  LLM Client │ ◄────────► │  MCP Server      │ ◄────────────► │  vSZ #1    │
│  (Claude…)  │            │  ruckus-vsz-mcp  │                └────────────┘
└─────────────┘            │                  │   HTTPS/8443   ┌────────────┐
                           │  ┌─── .env ────┐ │ ◄────────────► │  vSZ #2    │
                           │  │ VSZ_USERNAME │ │                └────────────┘
                           │  │ VSZ_PASSWORD │ │
                           │  └─────────────┘ │
                           └──────────────────┘
参数 来源 范围
host 工具参数 每次调用--从系统提示启用多控制器
VSZ_USERNAME .env 文件 在所有控制器之间共享
VSZ_PASSWORD .env 文件 在所有控制器之间共享
  • API基本URL : https://{host}:8443/wsg/api/public/v11_1
  • 认证 : serviceTicket 每次工具调用时通过以下方式自动获取 POST /v11_1/serviceTicket
  • 运输 ：STDIO（默认）
  • 安全套接层 ：默认情况下禁用验证（vSZ使用自签名证书）--可通过以下方式配置 VSZ_VERIFY_SSL

🔧 MCP客户端配置

克劳德桌面版

编辑 claude_desktop_config.json:

  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗 : %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "ruckus-vsz": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/Ruckus-vSZ-MCP", "run", "ruckus-vsz-mcp"]
    }
  }
}

VS代码（GitHub副本）

在 .vscode/mcp.json :

{
  "servers": {
    "ruckus-vsz": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/Ruckus-vSZ-MCP", "run", "ruckus-vsz-mcp"]
    }
  }
}

⚠️ 替换 /absolute/path/to/Ruckus-vSZ-MCP 在您的计算机上拥有此项目的绝对路径。

Docker/远程（SSE）

如果服务器在Docker或远程机器上运行，请使用SSE URL：

{
  "mcpServers": {
    "ruckus-vsz": {
      "url": "http://localhost:8081/sse"
    }
  }
}

系统提示示例

将vSZ主机添加到模型的系统提示符中，以便LLM知道要针对哪个控制器：

You have access to a Ruckus vSZ MCP server.
Available controllers:
- Production: host = "vsz-prod.example.com"
- Lab: host = "10.0.1.100"

Credentials are pre-configured in the server's .env file.
Always specify the host parameter when calling vsz_* tools.

🛠 可用工具（52）

系统-- system.py （5个工具）

工具 签名 描述
vsz_get_system_info (host) 获取vSZ系统信息（版本、型号、正常运行时间）
vsz_get_system_summary (host) 获取包含AP/客户端计数的系统摘要
vsz_get_system_inventory (host) 获取每个区域的AP和客户端统计信息
vsz_get_cluster_state (host) 获取群集节点状态和角色
vsz_get_controller_list (host) 列出群集中的所有控制器

区域-- zones.py （6个工具）

工具 签名 描述
vsz_list_zones (host) 列出所有区域
vsz_get_zone (host, zone_id) 获取区域详细信息
vsz_create_zone (host, name, ...) 创建新区域
vsz_update_zone (host, zone_id, ...) 更新区域配置
vsz_delete_zone (host, zone_id) 删除区域
vsz_list_zone_ap_groups (host, zone_id) 列出区域中的AP组

接入点-- aps.py （9个工具）

工具 签名 描述
vsz_list_aps (host) 列出所有接入点
vsz_get_ap (host, ap_mac) 获取AP配置详细信息
vsz_get_ap_operational (host, ap_mac) 获取AP运行信息（正常运行时间、客户端、状态）
vsz_update_ap (host, ap_mac, ...) 更新AP配置
vsz_delete_ap (host, ap_mac) 从管理中删除AP
vsz_reboot_ap (host, ap_mac) 重新启动接入点
vsz_list_ap_lldp (host, ap_mac) 获取AP LLDP邻居（通过/操作/邻居端点）
vsz_get_ap_radio (host, ap_mac) 从AP配置端点（2.4G/5G/6G）提取AP无线电配置
vsz_query_aps (host, ...) 使用筛选器查询AP

WLAN-- wlans.py （6个工具）

工具 签名 描述
vsz_list_wlans (host, zone_id) 列出区域中的WLAN
vsz_get_wlan (host, zone_id, wlan_id) 获取WLAN配置详细信息
vsz_create_wlan (host, zone_id, name, ssid, ...) 创建新的WLAN
vsz_update_wlan (host, zone_id, wlan_id, ...) 更新WLAN配置
vsz_delete_wlan (host, zone_id, wlan_id) 删除WLAN
vsz_enable_disable_wlan (host, zone_id, wlan_id, enabled) 启用或禁用WLAN

客户-- clients.py （4个工具）

工具 签名 描述
vsz_list_clients (host) 列出已连接的无线客户端
vsz_get_client (host, client_mac) 通过MAC获取客户端详细信息
vsz_disconnect_client (host, client_mac, ap_mac) 断开无线客户端的连接（需要AP MAC）
vsz_query_clients (host, ...) 使用筛选器查询客户端

警报-- alarms.py （4个工具）

工具 签名 描述
vsz_list_alarms (host) 列出活动警报
vsz_get_alarm (host, alarm_id) 获取报警详细信息（获取列表和匹配ID的过滤器）
vsz_acknowledge_alarm (host, alarm_id) 确认报警（PUT ack端点）
vsz_clear_alarm (host, alarm_id) 清除警报（PUT清除端点）

域名-- domains.py （3个工具）

工具 签名 描述
vsz_list_domains (host) 列出所有管理域
vsz_get_domain (host, domain_id) 获取域详细信息
vsz_create_domain (host, name, ...) 创建新域

认证/AAA-- aaa.py （3个工具）

工具 签名 描述
vsz_list_auth_servers (host) 列出身份验证（RADIUS）服务器
vsz_get_auth_server (host, server_id) 获取身份验证服务器详细信息
vsz_test_aaa (host, server_type, server_ip, server_port, shared_secret, ...) 测试AAA服务器连接

DHCP和网络-- dhcp.py （4个工具）

工具 签名 描述
vsz_list_dhcp_pools (host, zone_id) 列出区域中的DHCP池
vsz_get_dhcp_pool (host, zone_id, pool_id) 获取DHCP池详细信息
vsz_list_vlan_pools (host) 列出VLAN池配置文件（POST查询端点）
vsz_get_vlan_pool (host, pool_id) 获取VLAN池详细信息

监控与查询-- monitoring.py （3个工具）

工具 签名 描述
vsz_query (host, query_type, ...) 带过滤器的通用查询（ap、客户端、wlan、dpsk、roguesInfoList）
vsz_get_ap_statistics (host, ap_mac) 获取AP流量统计数据
vsz_get_wlan_statistics (host, wlan_name=None) 通过查询API获取WLAN统计信息（可选名称过滤器）

阻止客户端-- block_clients.py （3个工具）

工具 签名 描述
vsz_list_blocked_clients (host) 列出被阻止（列入黑名单）的客户端（POST查询端点）
vsz_block_client (host, mac, ...) 通过MAC地址阻止客户端
vsz_unblock_client (host, client_id) 解锁客户端

流氓AP-- rogue.py （2个工具）

工具 签名 描述
vsz_list_rogue_aps (host, ...) 列出检测到的恶意访问点
vsz_mark_rogue (host, rogue_mac, ...) 标记/分类流氓AP（流氓、已知、恶意、忽略）

📁 项目结构

Ruckus-vSZ-MCP/
├── src/
│   └── mcp_server/
│       ├── __init__.py
│       ├── server.py              # FastMCP entry point (STDIO transport)
│       ├── api/
│       │   ├── __init__.py
│       │   └── client.py          # Async httpx vSZ API client (auth from .env)
│       ├── tools/                 # 52 MCP tools — one module per vSZ API domain
│       │   ├── __init__.py        # register_all_tools() — aggregates 12 modules
│       │   ├── system.py          # System info, cluster, inventory (5)
│       │   ├── zones.py           # Zone CRUD, AP groups (6)
│       │   ├── aps.py             # AP management, radio, LLDP, query (9)
│       │   ├── wlans.py           # WLAN CRUD, enable/disable (6)
│       │   ├── clients.py         # Client listing, disconnect, query (4)
│       │   ├── alarms.py          # Alarm list, details, ack, clear (4)
│       │   ├── domains.py         # Domain management (3)
│       │   ├── aaa.py             # AAA server listing, test (3)
│       │   ├── dhcp.py            # DHCP/VLAN pool management (4)
│       │   ├── monitoring.py      # Generic query, statistics (3)
│       │   ├── block_clients.py   # Client blacklist management (3)
│       │   └── rogue.py           # Rogue AP detection (2)
│       ├── resources/
│       │   └── example.py
│       └── prompts/
│           └── example.py
├── tests/
│   ├── test_server.py
│   ├── test_tools.py
│   ├── test_resources.py
│   └── test_prompts.py
├── .env.example                   # Environment template (credentials, settings)
├── pyproject.toml
├── AGENTS.md
└── README.md

🧪 测试

uv run pytest                                       # Run all 130 tests
uv run pytest -v                                    # Verbose output
uv run pytest --cov=mcp_server                      # With coverage
uv run pytest --cov=mcp_server --cov-report=html    # HTML coverage report
uv run pytest tests/test_tools.py -v                # Single test file

🔐 安全须知

  • 凭证 存储在 .env (VSZ_USERNAME, VSZ_PASSWORD)--从未硬编码
  • SSL验证 默认情况下禁用（vSZ使用自签名证书）--通过启用 VSZ_VERIFY_SSL=true
  • 服务票 24小时后过期-每次工具调用时都是新获取的
  • host 是唯一暴露给LLM的连接参数——凭据仍然是服务器端的

📜 MCP规则（不可协商）

  1. ⛔ 从不 print() 没有 file=sys.stderr --STDIO传输需要干净的stdout

    import sys
logging.basicConfig(stream=sys.stderr)

  2. ⛔ 切勿从MCP工具中引发异常 --返回错误字符串

    try:
    result = await api_get(host, "/v11_1/aps")
except Exception as e:
    return f"Error: {e}"

  3. ✅ 键入所有参数的提示 --FastMCP自动生成JSON模式

    async def vsz_list_aps(host: str) -> str:

  4. ✅ 每个工具上的文档字符串 --自动生成MCP描述

    """List all access points managed by the vSZ controller.

Args:
    host: vSZ controller IP or hostname.
"""

  5. ✅ 证书在 .env — host 是连接的唯一工具参数

  6. ✅ 使用MCP检查员进行测试 : npx @modelcontextprotocol/inspector uv run ruckus-vsz-mcp

🔧 发展

添加新的vSZ工具

  1. 在中创建模块 src/mcp_server/tools/ （例如。， firmware.py)
  2. 实施 register_tools(mcp) 随着 @mcp.tool() 装饰功能
  3. 导入并注册 src/mcp_server/tools/__init__.py
  4. 在中添加测试 tests/
  5. 更新此自述文件

例子：

# src/mcp_server/tools/firmware.py
import json
import logging

from mcp.server.fastmcp import FastMCP
from mcp_server.api.client import API_VERSION, api_get

logger = logging.getLogger(__name__)
V = API_VERSION


def register_tools(mcp: FastMCP) -> None:
    """Register firmware management tools."""

    @mcp.tool()
    async def vsz_list_firmware(host: str) -> str:
        """List available firmware versions on the vSZ controller.

        Args:
            host: vSZ controller IP or hostname.
        """
        result = await api_get(host, f"/{V}/firmware")
        if isinstance(result, str):
            return result
        return json.dumps(result, indent=2)

🤖 副驾驶代理

该项目包括4名专业的Copilot代理商(.github/agents/)用于自动化开发工作流程。

代理 域
mcp-developer 源代码： src/mcp_server/ （工具、资源、提示）
mcp-tester 测试： tests/ --从不修改 src/
mcp-scaffolder 配置： pyproject.toml, .gitignore, .env.example
mcp-documenter 文件： README.md，文档字符串， AGENTS.md

.github/copilot-instructions.md 在每次提示时强制自动委托给正确的代理。

🔗 资源

📝 许可证

麻省理工学院

相关 MCP