aruba-central-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP server for Aruba Central (GreenLake New Central API, plus optional Classic Central for firmware). Exposes AP, switch, wireless client and firmware status to AI assistants via STDIO transport. Read-only.

Commands

python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest -v               # run all tests
.venv/bin/pytest -v tests/test_client.py  # client tests only
.venv/bin/pytest -v tests/test_server.py  # server tests only
python3 -m py_compile aruba_central_mcp/client.py  # syntax check

Architecture

• aruba_central_mcp/client.py — ArubaClient: OAuth2 Client Credentials + httpx + automatic pagination
• aruba_central_mcp/server.py — MCPServer server with 18 tools (19 with Classic Central configured): AP tools (list_aps, list_radios, list_bssids, list_wlans, list_swarms, get_ap_status, get_ap_throughput, get_top_aps), Client tools (list_clients, find_client_by_mac, get_clients_trend, get_top_clients_by_usage, get_client_mobility_trail), Infrastructure (list_switches, get_site_summary), Firmware (firmware_status, opt-in firmware_versions), plus health_check (server version + backend auth probe) and daily_brief (site-level AP online/offline health summary; buckets APs by siteName, threshold-gated)
• aruba_central_mcp/classic.py — ClassicClient: Classic Central API gateway, GET-only. The refresh token rotates on every refresh, so the pair lives in ARUBA_CLASSIC_TOKEN_FILE; a refresh takes an fcntl lock on <file>.lock, re-reads the file (another process may have refreshed), refuses to refresh when the directory is not writable, and writes the new pair durably (temp + fsync + rename + directory fsync, 0600); a failed write keeps the pair in memory and is reported as persist_error. The refresh sends secrets as query parameters, so the client sets httpx/httpcore to WARNING and adds a redacting filter; its own logger writes to stderr and does not propagate. Tokens never reach a log line or an error message
• Firmware tools: firmware_status (New Central /network-services/v1/firmware-details + /network-monitoring/v1/aps; with Classic configured, a swarm_id -> group map built from /configuration/v2/groups + /firmware/v1/swarms?group= + compliance per group, cached 300 s per group in-process (partial reads kept, unread groups first next time), joined to New Central by clusterId == swarm_id -- New Central has no group for AOS-8 APs; the whole call runs under one 48 s deadline passed into every HTTP request) and firmware_versions (Classic only; registered by _register_optional_tools() only when all ARUBA_CLASSIC_* are set, listed in scripts/smoke_probes.OPT_IN_TOOLS). API facts and gaps: docs/firmware-api-notes.md
• aruba_central_mcp/__main__.py — console-script entry point (aruba-central-mcp, per pyproject.toml); --check verifies env vars + OAuth2 auth and exits; its KeyboardInterrupt handler calls os._exit(0) deliberately to bypass normal interpreter shutdown, because MCPServer's stdio reader daemon thread can crash with _enter_buffered_busy on Python 3.14
• Environment variables for configuration: ARUBA_CENTRAL_BASE_URL, ARUBA_CENTRAL_CLIENT_ID, ARUBA_CENTRAL_CLIENT_SECRET; optional ARUBA_CLASSIC_BASE_URL, ARUBA_CLASSIC_CLIENT_ID, ARUBA_CLASSIC_CLIENT_SECRET, ARUBA_CLASSIC_TOKEN_FILE