RUCKUS Vsz MCP

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

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

______________________________________________________________________

🚀 快速开始

先决条件

• Python≥3.10 （建议：3.12）
• 紫外线 包管理器
• 访问Ruckus vSZ控制器（API端口8443）

安装

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 │ │
                           │  └─────────────┘ │
                           └──────────────────┘

• 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个工具）

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

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

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

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

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

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

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

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

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

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

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

______________________________________________________________________

📁 项目结构

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)

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

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

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

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

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

   """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)
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/)用于自动化开发工作流程。

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

______________________________________________________________________

🔗 资源

• MCP文件
• MCP Python SDK
• MCP检查员
• Ruckus vSZ API参考
• uv——文件

______________________________________________________________________

📝 许可证

麻省理工学院