afc-mcp

用于 Aruba Fabric Composer (AFC) 的 MCP 服务器，聚焦资产清单、网络状态以及 VMware vCenter/vSphere 可见性。只读。

包含内容

• server.py：FastMCP 入口，暴露 MCP 工具（传输方式：streamable-http）。

• afc_client.py：AFC API 客户端，包含鉴权令牌处理以及映射为只读的端点。

• Dockerfile：MCP 服务器的容器镜像。

• docker-compose.yml：本地运行环境（主机端口 8010 → 容器 8000）。

• .env.example：环境变量模板。

Related MCP server: Cisco RIS MCP Server

快速开始

1. 创建环境变量文件：

cp .env.example .env

2. 至少填写以下内容：

• AFC_BASE_URL（主机根路径，不能包含 /api，例如 https://afc.example.local）

• AFC_USERNAME

• AFC_PASSWORD

• AFC_VERIFY_SSL（可选，默认 false）

• AFC_TIMEOUT（可选，默认 30）

3. 构建并运行：

docker compose up --build -d

4. 查看日志：

docker compose logs -f

端点

服务器通过 streamable-HTTP 提供 MCP 服务：

URL:  http://<docker-host>:8010/mcp

默认情况下该端点是开放的。你可以启用 Bearer token 鉴权，这样只有持有有效令牌的客户端才能调用这些工具（见下文）。

鉴权（Bearer token）

鉴权为可选功能，默认关闭（向后兼容）。启用后，每个 MCP 请求都必须携带 Authorization: Bearer <token> 请求头；未携带有效令牌的请求会被拒绝并返回 401。

令牌是命名的（每个客户端一个），并存储在 secrets/.tokens 中（该文件被 Git 忽略，并以读写方式挂载进容器）。

1. 创建第一个令牌（在主机上或容器内运行）：

# on the host (stdlib only, no dependencies needed)
cd afc-mcp
python afc_token_manager.py generate --name "vscode-dev" --description "Laptop VSCode"

# ...or inside the running container
docker compose exec afc-mcp python afc_token_manager.py generate --name "vscode-dev"

该命令会一次性打印明文令牌——请立即复制。

2. 启用鉴权并（重新）启动服务器：

# in .env or the shell environment
AFC_AUTH_ENABLED=true

docker compose up -d --build

安全网：如果 AFC_AUTH_ENABLED=true 但还不存在任何令牌，服务器会以 LOCKED 模式启动，并拒绝所有请求（返回 503），直到创建令牌并重启容器为止。这是为了防止意外暴露开放端点。

使用 CLI 管理令牌：

python afc_token_manager.py list                 # masked preview
python afc_token_manager.py show --name vscode-dev  # reveal a value
python afc_token_manager.py revoke --name vscode-dev

撤销或添加令牌后，需要重启容器才生效。

注意：MCP_HOST 和 MCP_PORT 只控制服务器在容器内部的监听位置（0.0.0.0:8000，映射到主机 8010）。它们与鉴权无关——它们决定的是服务器在何处监听，而不是谁可以调用它。

与 VS Code 集成

VS Code（配合 GitHub Copilot / Agent 模式）会从 mcp.json 文件中发现 MCP 服务器。

1. 在你的工作区中创建 .vscode/mcp.json（或添加到用户级 mcp.json）：

{
  "servers": {
    "afc-mcp": {
      "type": "http",
      "url": "http://localhost:8010/mcp"
    }
  }
}

如果容器运行在别处，请将 localhost 替换为 Docker 主机地址。

如果已启用鉴权，请将 Bearer token 作为请求头添加：

{
  "servers": {
    "afc-mcp": {
      "type": "http",
      "url": "http://localhost:8010/mcp",
      "headers": { "Authorization": "Bearer afc_xxxxxxxx" }
    }
  }
}

2. 打开命令面板 → MCP: List Servers，选择 afc-mcp 并启动它。

3. 在 Chat 视图（Agent 模式）中，AFC 工具会出现在工具选择器下。

与 Claude Desktop 集成

Claude Desktop 默认连接本地（stdio）服务器。要连接这个 streamable-HTTP 服务器，可以使用 mcp-remote 作为桥接。

编辑 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "afc-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8010/mcp"]
    }
  }
}

重启 Claude Desktop 后，afc-mcp 会出现在工具菜单中。

另外，较新的 Claude Desktop 构建版本支持直接通过 Settings → Connectors → Add custom connector 添加远程 MCP 服务器，使用同一个 URL。

可用的 MCP 工具

服务器与系统

• get_server_status —— MCP 服务器可达性/健康状态。

• get_system_info —— AFC 系统信息。

交换机与 Fabric

• list_switches、get_switch —— 交换机资产清单和单台交换机详情（端口、软件、标签）。

• list_fabrics、get_fabric —— Fabric 资产清单和成员。

路由与 overlay

• list_vrfs、get_vrf —— VRF 资产清单和详情。

• get_vrf_routes —— VRF 的 IP 路由表（RIB），支持下一跳查询。VRF 和交换机均可按名称或 UUID 传入；如果指定 destination（主机 IP 或 CIDR），则执行最长前缀匹配，并返回命中的路由和下一跳。

• get_vrf_arp —— 在交换机上学习到的 VRF ARP 表（IP-to-MAC 绑定）。支持按名称或 UUID 传入 VRF 和 switch；传入 switch 可将作用域限定到单个交换机。每个条目都会显示 IP/MAC、接口、物理端口、所属交换机以及邻居可达性状态（reachable、stale、incomplete 等）。

• get_vrf_ip_interfaces —— VRF 的三层（IP）接口。支持按名称或 UUID 传入 VRF 和 switch；可按 if_type（routed、vlan、loopback、evpn）过滤。当 include_status（默认开启）为真时，除了配置信息外，还会返回运行状态（管理 up/down、MAC、IP MTU、双工模式、IPv4 地址）。

• get_vrf_static_routes —— VRF 中配置的 IP 静态路由（目的前缀、下一跳或丢弃路由/黑洞、下一跳接口、distance、tag、type 以及生效交换机）。支持按名称或 UUID 传入 VRF 和 switch。

• get_vrf_bgp_status、get_vrf_bgp_summary —— 每个 VRF 的 BGP 状态和汇总信息。

• get_vrf_ospf_neighbors、get_vrf_ospf_summary —— 每个 VRF 的 OSPF 邻居和汇总信息。

• list_evpn、list_evpn_routes —— EVPN 实例和路由。

• get_vrf_virtual_environment —— 绑定到某个 VRF 的虚拟环境。

站点与概览

• list_afc_sites、get_afc_site_inventory —— AFC（远端）站点站点及资产清单。

• get_network_overview —— 聚合后的网络状态快照。

健康

• list_health_alerts —— 当前 AFC 健康告警。

• run_health_check —— 汇总健康检查（告警、交换机/Fabric 健康、BGP/OSPF 邻居，以及可选的高可用和许可证状态）。

集成与 VMware vCenter/vSphere

• list_integrations —— 所有集成包、各自的远程服务器及连接状态。

• list_vmware_integrations —— 仅限 vSphere：每个已配置的 vCenter 返回一条记录，包含服务器地址、连接状态和故障消息。

• get_vmware_inventory —— VMware 主机，带有位置（vCenter、数据中心、集群、域）和状态（物理 NIC 状态、VM 运行状态），另外还有 vSwitch、Port Group 和 VM。可选按 ESXi 主机名过滤。

• list_vmware_vms —— 扁平化 VM 清单，带有电源状态和部署位置（ESXi 主机、集群、数据中心、vCenter），以及 IP 和标签。可选过滤条件：power_state、host_name。

• get_vm_attachment —— 追踪 VM 的端到端网络连接信息（vNIC → Port Group → vSwitch → 主机 uplink → 物理交换机/端口）。

备注

• AFC_BASE_URL 必须是主机根路径，不能包含 /api；客户端会自动补上 /api 前缀。

• API 鉴权使用 POST /api/auth token 接口，请求头为 X-Auth-Username 和 X-Auth-Password；该 token 会被复用，并在返回 401 时自动刷新。

• vSphere 集成暂不提供每主机电源/健康字段：主机状态由物理 NIC 状态和 VM 电源数量推导得出；vcenter 是 vSphere 实例的 UUID。