Ruckus虚拟智能区——MCP服务器🔌
> 模型上下文协议服务器 用于Ruckus虚拟智能区(vSZ)无线控制器管理。
> 暴露 52工具 跨12个模块,直接从LLM查询和管理AP、WLAN、区域、客户端、警报等。
🚀 快速开始
先决条件
- Python≥3.10 (建议:3.12)
- 紫外线 包管理器
- 访问Ruckus vSZ控制器(API端口8443)
安装```bash
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
### 跑```bash
uv run ruckus-vsz-mcp
使用MCP检查员进行测试```bash
npx @modelcontextprotocol/inspector uv run ruckus-vsz-mcp
### Docker(SSE/可流式传输http)```bash
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````json
{
"mcpServers": {
"ruckus-vsz": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/Ruckus-vSZ-MCP", "run", "ruckus-vsz-mcp"]
}
}
}
VS代码(GitHub副本)
在 .vscode/mcp.json :```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:```json
{
"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
🧪 测试```bash
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```python
import sys
logging.basicConfig(stream=sys.stderr)
- ⛔ 切勿从MCP工具中引发异常 --返回错误字符串```python
try:
result = await api_get(host, "/v11_1/aps")
except Exception as e:
return f"Error: {e}"
1. ✅ **键入所有参数的提示** --FastMCP自动生成JSON模式```python
async def vsz_list_aps(host: str) -> str:
- ✅ 每个工具上的文档字符串 --自动生成MCP描述```python
"""List all access points managed by the vSZ controller.
Args:
host: vSZ controller IP or hostname.
"""
1. ✅ **证书在 `.env`** — `host` 是连接的唯一工具参数
1. ✅ **使用MCP检查员进行测试** : `npx @modelcontextprotocol/inspector uv run ruckus-vsz-mcp`
______________________________________________________________________
## 🔧 发展
### 添加新的vSZ工具
1. 在中创建模块 `src/mcp_server/tools/` (例如。, `firmware.py`)
1. 实施 `register_tools(mcp)` 随着 `@mcp.tool()` 装饰功能
1. 导入并注册 `src/mcp_server/tools/__init__.py`
1. 在中添加测试 `tests/`
1. 更新此自述文件
**例子:**```python
# 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文件
- MCP Python SDK
- MCP检查员
- Ruckus vSZ API参考
- uv——文件
📝 许可证
麻省理工学院
