HPE网络MCP服务器
> 非官方/社区项目。 这个存储库是一个独立的、由社区驱动的项目。它不隶属于惠普企业、Aruba Networks或瞻博网络,也不受其认可、赞助或支持。“HPE”、“阿鲁巴”、“阿鲁巴岛中央”、“Aruba ClearPass”、“HPE GreenLake”、“Juniper”和“Juniper-Mist”是其各自所有者的商标,在这里仅用于描述此软件与之互操作的内容。请将有关这些产品的支持和许可问题直接发送给相应的供应商。
统一的 模型上下文协议(MCP) 服务器带来 朱尼珀薄雾, 阿鲁巴中央, HPE GreenLake, 阿鲁巴ClearPass, Juniper Apstra,以及 Axis Atmos云 将它们组合成一个可部署的单一服务。一个集装箱。一个端点。所有HPE网络工具。
为什么?
如今,使用人工智能助手管理HPE网络基础设施意味着要处理多个单独的MCP服务器——每个服务器都有自己的设置、凭据和怪癖。该项目将它们整合为一个:
| 类别 | 薄雾 | 中环 | 绿湖 | ClearPass | Apstra | Axis | AOS8 |
|---|---|---|---|---|---|---|---|
| 站点健康和性能指标 | ✅ | ✅ | — | — | — | — | ✅ |
| WLAN/SSID | ✅ | ✅ | — | — | — | — | ✅ |
| 设备清单 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 设备详细信息(AP/交换机/GW) | ✅ | ✅ | — | — | — | — | ✅ |
| 设备统计和利用率 | ✅ | ✅ | — | — | — | ✅ | ✅ |
| 客户端连接 | ✅ | ✅ | — | — | — | — | ✅ |
| 事件 | ✅ | ✅ | — | ✅ | — | — | ✅ |
| 警报/警报 | ✅ | ✅ | — | ✅ | ✅ | — | ✅ |
| 审计日志 | ✅ | ✅ | ✅ | ✅ | — | — | ✅ |
| 应用程序可见性 | — | ✅ | — | — | — | ✅ | — |
| 故障排除(Ping/Traceroute/Bounce) | ✅ | ✅ | — | — | — | — | ✅ |
| 会话控制/客户端断开连接 | ✅ | ✅ | — | ✅ | — | — | ✅ |
| 配置管理 | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| 配置写入(CRUD) | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
| 无线电资源管理 | ✅ | — | — | — | — | — | ✅ |
| 流氓AP检测 | ✅ | — | — | — | — | — | ✅ |
| 固件管理 | ✅ | ✅ | — | — | — | — | ✅ |
| 订阅/许可 | — | — | ✅ | ✅ | — | — | ✅ |
| 用户管理 | — | — | ✅ | ✅ | — | ✅ | — |
| 工作区 | — | — | ✅ | — | — | — | — |
| 范围和配置层次结构 | ✅ | ✅ | — | — | — | ✅ | ✅ |
| 来宾管理 | — | — | — | ✅ | — | — | — |
| NAC/政策管理 | ✅ | ✅ | — | ✅ | — | — | — |
| 端点分析 | ✅ | — | — | ✅ | — | — | — |
| 证书 | — | — | — | ✅ | — | — | — |
| 数据中心蓝图/模板 | — | — | — | — | ✅ | — | — |
| 虚拟网络/EVPN/路由区 | — | — | — | — | ✅ | — | — |
| 连接模板/策略应用 | — | — | — | — | ✅ | — | — |
| 结构部署/差异状态 | — | — | — | — | ✅ | — | — |
| BGP/协议会话监控 | — | — | — | — | ✅ | — | — |
| SASE云连接器/隧道 | — | — | — | — | — | ✅ | — |
| URL/Web类别筛选 | — | — | — | — | — | ✅ | — |
| SSL检查排除 | — | — | — | — | — | ✅ | — |
| 分阶段写入+提交工作流 | — | — | — | — | ✅ | ✅ | — |
| 引导提示 | ✅ | ✅ | — | — | — | — | ✅ |
| 动态工具发现 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 基础工具 | 1037+2个提示 | 613+12个提示 | 10 | 140 | 19 | 25 | 47+9个提示 |
| 暴露的元工具(动态模式) | 3 | 3 | 3 | 3 | 3 | 3 | 3 |
| 交叉平台的 | 3个工具+3个提示 | 3个工具+3个提示 | — | 1个工具 | — | — | — |
> 默认刀具表面(v3.0.0.0+):船舶 MCP_TOOL_MODE=code 默认情况下。代码模式仅公开 execute +5发现工具(tags, search, get_schema, skills_list, skills_load);所有1891个底层工具都可以通过以下方式访问 await call_tool(name, params) 在沙盒Python中 execute() 块。最小的初始令牌成本(~最小上下文);最适合驾驶小型/本地LLM的管弦乐队。集 MCP_TOOL_MODE=dynamic 要使用v2.x默认行为,每个平台都公开了3个元工具(_list_tools, _get_tool_schema, _invoke_tool)加上4个跨平台静态工具和2个技能工具(24个总表面,约3700个令牌)。这 static 在v3.0.0.0中删除了该模式。每个工具的响应都被包裹在一个统一的信封里 {ok, status, data, message, tool, platform}v2.3.0.0版本介绍 技能 --markdown定义的多步骤程序可通过以下方式发现 skills_list / skills_load;参见 docs/TOOLS.md#技能v2.4.0.0添加了 AOS8 (47个工具+9个提示)--请参阅 说明.md AOS8特定操作员指南。看 docs/MIGRATING_TO_V2.md.
阿鲁巴中央导游提示
中央模块包括12个引导提示——多步骤工作流模板,使用可用工具引导人工智能完成常见的网络操作任务。这些提示以正确的顺序编排多个工具调用,因此您可以简单地调用提示并让AI处理其余部分。
- 网络健康概述 --评估网络中所有站点的健康状况,标记得分低或警报计数高的站点,以便进行更深入的调查。
- 网站故障排除 --深入了解特定站点:检查健康指标,按严重程度查看活动警报,列出所有设备,并建议下一步行动。
- 客户端连接检查 --按MAC地址调查客户端:找到客户端,检查连接设备的运行状况,查看站点级警报,并确定可能的根本原因。
- 调查设备事件 --提取特定设备的最近事件,以建立发生的事情的时间表,突出显示重复出现的问题,并建议后续行动。
- 现场事件摘要 --总结一个时间窗口内站点的所有事件,按类别和类型分组,以发现模式和异常。
- 客户调查失败 --查找站点上所有失败的客户端连接,检查它们连接到的设备的运行状况,并确定常见的故障模式。
- 站点客户端概述 --按连接类型、状态、VLAN和WLAN对站点上的所有客户端进行细分,以了解连接情况。
- 设备类型运行状况 --检查站点上特定类型(AP、交换机或网关)的所有设备的运行状况,包括警报和最近的事件活动。
- 关键警报审查 --查看整个网络中所有活动的关键警报,按站点和类别分组,并建议立即采取行动。
- 比较站点运行状况 --对多个站点的健康评分、设备计数、客户端计数和警报细分进行并排比较。
- 范围配置概述 --在作用域级别查看已提交的配置资源,按角色和类别分组。
- 范围有效配置 --查看范围内的有效(继承+提交)配置,显示每个级别的贡献。
AOS8引导提示
AOS8模块包括9个针对常见Mobility Conductor操作员工作流程的引导提示。看 说明.md 获取完整的参数参考和工作流程描述。
- 分类客户 (
aos8_triage_client)--通过MAC查找客户端,检查AP健康状况,查看身份验证/关联事件,确定可能的根本原因。 - AP分类 (
aos8_triage_ap)--深入了解AP:无线电状态、客户端、警报、ARM历史、事件时间线。 - 健康检查 (
aos8_health_check)--网络范围的健康状况:控制器、AP计数、客户端、警报、固件漂移。 - 审计变更 (
aos8_audit_change)——最近的审计跟踪审查显示高风险变化。 - 射频分析 (
aos8_rf_analysis)--信道分布、同信道簇、ARM振荡、干扰源/流氓。 - WLAN回顾 (
aos8_wlan_review)——SSID/VAP/AP组/角色清单和一致性检查。 - 客户洪水 (
aos8_client_flood)--范围内的客户端数量高/连接调查失败。 - 比较MD配置 (
aos8_compare_md_config)--两个MD或AP组之间并排有效的配置差异。 - 变更前检查 (
aos8_pre_change_check)--维护前检查表:警报、控制器统计数据、审计跟踪、待处理更改、write_memory提醒。
跨平台工具
跨多个平台并返回预聚合结果的工具——每个工具都会替换几个单独的工具调用,因此AI会得到一个简洁的答案,而不是遍历原始响应。
- 现场健康检查 (
site_health_check)--一次调用会返回每个启用平台上站点的统一运行状况报告:Mist站点统计数据和警报、中央站点运行状况和活动警报,以及(配置ClearPass时)站点网络访问设备的会话和身份验证失败计数。用一份紧凑的报告取代约8-12个单独的工具调用,包括总体状态、顶部警报和具体的下一步建议。至少启用Mist或Central时注册;ClearPass是附加的。 - 现场射频检查 (
site_rf_check)--每个AP和Mist AND Central并行返回一个呼叫,每个频带的无线电状态:站点上每个AP的当前信道、带宽、TX功率、信道利用率和噪声基底。聚合每个频段(2.4/5/6 GHz)的信道分布,标记共信道集群和高利用率,并提供预渲染的ASCII RF仪表板,这样即使不绘制图表的客户端也能获得可视化报告。什么时候site_name如果省略,该工具将返回一个包含每个平台AP计数的可选站点列表——选择一个并回电。至少启用Mist或Central时注册。 - 管理WLAN配置文件 (
manage_wlan_profile)--所有WLAN操作的主要入口点。自动检查Mist和Central的SSID,并返回正确的同步工作流。检测跨平台场景,无需依赖人工智能来遵循指示。需要Mist和Central。
跨平台WLAN同步提示
- 同步WLAN雾→ 中央 --解析Mist模板变量,映射字段,创建中央WLAN配置文件,分配到匹配的范围。
- 同步WLAN中央→ Mist --解析中心别名、服务器组和命名VLAN,使用模板变量创建Mist WLAN。
- 双向同步WLAN --比较两个平台上的WLAN,显示字段级别差异,并在任一方向上同步。
快速开始
先决条件
- 码头工人 和 Docker Compose
1.获得项目```bash
git clone https://github.com/nowireless4u/hpe-networking-mcp.git
cd hpe-networking-mcp
> **无需构建。** 这 `docker-compose.yml` 默认情况下,从GitHub容器注册表中提取预构建映像。若要从源代码构建,请编辑 `docker-compose.yml` 和交换 `image:` 为了 `build: .`.
### 2.配置机密
回购随附 `.example` 仅限模板文件-- **没有真正的秘密文件**。您可以通过复制示例并用您的值编辑它们来自己创建真实的文件。
**重要提示:** `docker-compose.yml` 声明每个平台的秘密,并在启动时绑定将每个秘密挂载到容器中。如果磁盘上不存在列出的机密文件,容器将立即失败,并发出 `invalid mount config` 错误-- **在应用程序运行之前。** 这意味着您需要从两条路径中选择一条:
- **路径A(大多数用户):** 填充每个 `.example` → compose文件中列出的每个平台的实名对,甚至是您当前不使用的平台(将虚拟内容放在未使用的平台中——应用程序将在运行时禁用该平台,见下文)。
- **路径B(如果您只使用某些平台,建议使用):** 创建一个 `docker-compose.override.yml` 这将删除未使用的平台的秘密引用,因此compose停止尝试绑定它们。看 **禁用不使用的平台** 在......下面
对于您实际希望启用的平台,复制模板并使用实际值进行编辑:```bash
# Mist (required for this example; do the same for every platform you're using)
cp secrets/mist_api_token.example secrets/mist_api_token
cp secrets/mist_host.example secrets/mist_host
# Edit each file with your real credentials
# Aruba Central
cp secrets/central_base_url.example secrets/central_base_url
cp secrets/central_client_id.example secrets/central_client_id
cp secrets/central_client_secret.example secrets/central_client_secret
# HPE GreenLake
cp secrets/greenlake_api_base_url.example secrets/greenlake_api_base_url
cp secrets/greenlake_client_id.example secrets/greenlake_client_id
cp secrets/greenlake_client_secret.example secrets/greenlake_client_secret
cp secrets/greenlake_workspace_id.example secrets/greenlake_workspace_id
# ClearPass
cp secrets/clearpass_server.example secrets/clearpass_server
cp secrets/clearpass_client_id.example secrets/clearpass_client_id
cp secrets/clearpass_client_secret.example secrets/clearpass_client_secret
cp secrets/clearpass_verify_ssl.example secrets/clearpass_verify_ssl
# Juniper Apstra
cp secrets/apstra_server.example secrets/apstra_server
cp secrets/apstra_port.example secrets/apstra_port
cp secrets/apstra_username.example secrets/apstra_username
cp secrets/apstra_password.example secrets/apstra_password
cp secrets/apstra_verify_ssl.example secrets/apstra_verify_ssl
# Axis Atmos Cloud
cp secrets/axis_api_token.example secrets/axis_api_token
> Axis令牌注释:在Axis管理门户中生成令牌 设置→ 管理员API→ 新API代币。选择读取或读取+写入范围和过期时间。MCP服务器对JWT进行解码 exp 在启动时声明,并在令牌剩余时间少于30天时记录警告;这 health 工具还可以曲面a token_expires_in_days 在那个窗口内倒计时。没有刷新-在令牌失效之前在门户中重新生成令牌。
每个文件都包含一个值(例如,您的API令牌)。 不要留下占位符内容 (比如 apstra.example.com 或 replace-with-real-password)在您未使用的平台的文件中,服务器将在启动时尝试使用这些假值进行身份验证,并用失败的登录错误填充您的日志。如果你没有使用平台,请使用下面的路径B(覆盖文件)或将机密文件留空——该应用程序将空文件视为“未配置”并禁用平台。
3.禁用不使用的平台(推荐)
创建 docker-compose.override.yml 旁边 docker-compose.yml.Compose在启动时自动合并它,并提交 docker-compose.yml 保持不变。仓库中提供了一个可复制的模板:```bash
cp docker-compose.override.yml.example docker-compose.override.yml
edit to match the platforms you actually use
该模板显示了仅使用Mist的部署 `!reset` 删除其他平台的秘密引用的指令——包括服务级别 `secrets:` 列表 **和** 顶级 `secrets:` 块,您需要执行这两个部分,以便Compose停止尝试绑定挂载未使用的文件。调整 `secrets: !reset - ` 在...之下 `services:` 保留您需要的任何平台,以及 `!reset` 只有你真正删除的顶级条目。该模板还提供了每个平台的写入工具标志、日志级别和工具模式覆盖的示例。
`docker-compose.override.yml` 已在 `.gitignore`,所以你的每次部署定制永远不会在git中结束。在仅使用薄雾覆盖的情况下,您只需要 `secrets/mist_api_token` 和 `secrets/mist_host` 在磁盘上——其他所有秘密文件都可能不存在。
> **需要编写版本:** `!reset` 需要Docker Compose v2.24或更高版本。如果您使用的是较旧的Compose,请升级(推荐)或跳过覆盖文件并编辑 `docker-compose.yml` 直接评论出未使用的平台的服务级别和顶级机密条目。
### 4.启动```bash
docker compose up -d
5.验证```bash
docker compose logs
寻找以下线条 `Mist: 1037 underlying tools registered (code mode)`, `ClearPass: 140 underlying tools registered (code mode)`, `Axis: 25 underlying tools registered (code mode)`, `AOS8: 47 underlying tools (code mode)`, `Tool mode: code`,以及 `Uvicorn running on http://0.0.0.0:8000`。您的MCP服务器正在运行 `http://localhost:8000/mcp`。在默认代码模式下(自v3.0.0.0起),仅 `execute` +5发现工具(`tags`, `search`, `get_schema`, `skills_list`, `skills_load`)暴露在顶层;所有1891个底层工具都可以通过以下方式访问 `await call_tool(name, params)` 在沙盒Python中 `execute()` 块。集 `MCP_TOOL_MODE=dynamic` 改用v2.x元工具界面。薄雾记录2个引导提示;中央登记册12;AOS8注册9。
### Docker镜像
预构建的镜像可以在GitHub容器注册表上找到:```
ghcr.io/nowireless4u/hpe-networking-mcp:latest
ghcr.io/nowireless4u/hpe-networking-mcp:0.6.0
您也可以直接拉动它:```bash
docker pull ghcr.io/nowireless4u/hpe-networking-mcp:latest
______________________________________________________________________
## 平台自动禁用
您不需要所有七个平台的凭据。服务器在启动时检测哪些平台具有有效的秘密内容,并仅启用这些内容。如果平台所需的任何机密文件被禁用 **空或缺席** 从 `SECRETS_DIR` (容器内)——在Docker Compose下,这意味着磁盘上的文件是空的,或者你使用了 `docker-compose.override.yml` 完全放弃该平台的秘密(参见 禁用不使用的平台).
- **已配置所有七个平台** → 所有可用工具(雾+中央+绿湖+ClearPass+Apstra+轴+AOS8)
- **仅配置Mist** → Only `mist_*` 可用工具;其他平台已禁用
- **仅配置了AOS8** → Only `aos8_*` 可用工具;其他平台已禁用
- **仅配置了ClearPass** → Only `clearpass_*` 可用工具;其他平台已禁用
- **没有有效凭据** → 服务器拒绝启动,并显示明确的错误消息
稍后通过填充平台的机密文件(或删除覆盖文件)来添加平台 `!reset` 行)并重新启动容器。服务器记录启动时启用的平台:```
Mist: credentials loaded (token: abcd...wxyz, host: api.mist.com)
Central: disabled (missing secrets: central_client_id, central_client_secret)
GreenLake: disabled (missing secrets: greenlake_client_id)
AOS8: disabled (missing secrets: aos8_host)
Enabled platforms: mist
Tool mode: code
> 请注意: 自动禁用触发器打开 空白或缺失的秘密内容,而不是占位符/示例值。如果你复制 apstra_server.example → apstra_server 并将内容保留为 apstra.example.com,服务器认为Apstra已配置,并尝试对假主机进行身份验证——您的日志中充满了登录错误。要么清空这些文件,要么通过以下方式删除平台 docker-compose.override.yml,或填写实际值。
连接您的AI客户端
克劳德桌面版
Claude Desktop本身不支持流式HTTP,因此它需要一个名为的stdio到HTTP桥 supergateway此桥在Claude Desktop的stdio协议和MCP服务器的HTTP端点之间进行转换。
先决条件: Node.js 必须安装在您的计算机上。证实 npx --version 在你的终端。
第一步: 在文本编辑器中打开Claude Desktop配置文件:
| OS | 文件位置 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| 视窗 | %APPDATA%\Claude\claude_desktop_config.json |
> 提示: 您还可以从Claude Desktop中打开此文件:转到 设置 (齿轮图标)> 开发者 > 编辑配置.
第二步: 如果文件为空或不存在,请按原样粘贴整个块:```json
{
"mcpServers": {
"hpe-networking": {
"command": "npx",
"args": ["-y", "supergateway", "--streamableHttp", "http://localhost:8000/mcp"]
}
}
}
如果你 **已经有其他MCP服务器** 已配置,添加 `"hpe-networking"` 进入现有 `"mcpServers"` 对象。做 **不** 创建第二个 `"mcpServers"` 钥匙。例如,如果您已经有一个名为 `"my-other-server"`:```json
{
"mcpServers": {
"my-other-server": {
"command": "some-command",
"args": ["some-args"]
},
"hpe-networking": {
"command": "npx",
"args": ["-y", "supergateway", "--streamableHttp", "http://localhost:8000/mcp"]
}
}
}
> 常见错误:
>
> - 服务器条目之间缺少逗号(添加 , 交割后 } 之前的服务器)
> - 重复 "mcpServers" 密钥(只允许一个——将您的服务器合并到其中)
> - 最后一个条目后的尾随逗号(JSON不允许尾随逗号)
> - 编辑错误的文件或创建新文件,而不是编辑现有文件
步骤3: 保存文件并 完全重新启动克劳德桌面 (退出并重新打开,而不仅仅是关闭窗口)。MCP服务器在启动时被发现——只有重新启动后,更改才会生效。
步骤4: 验证服务器是否已连接。在Claude Desktop中,在聊天输入区域中查找MCP服务器图标(锤子)。点击它——你应该看到 hpe-networking 列出了它的工具。
克劳德代码
不需要配置文件--运行以下命令:```bash
claude mcp add hpe-networking --transport http http://localhost:8000/mcp
### VS代码/GitHub副本
添加到您的 `.vscode/mcp.json` (如果文件不存在,则创建该文件)或VS Code MCP设置:```json
{
"servers": {
"hpe-networking": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp"
}
}
}
PII标记化(v2.3.1.0+)
工具响应在到达AI之前被遍历:
- MAC规范化(始终打开,无切换) --工具响应中的每个MAC地址都被重写为规范
aa:bb:cc:dd:ee:ff形式(小写,冒号分隔)。Mist的API在端点之间以四种不同的格式返回MAC;一致的格式意味着AI可以关联aa:bb:cc:dd:ee:ff在审计过程中。 - PII代币化(通过以下方式选择加入
ENABLE_PII_TOKENIZATION=true) --敏感字段(PSK、RADIUS机密、证书)和客户标识值(主机名、FQDN、电子邮件、用户名、硬件序列号)被替换为会话稳定[[KIND:uuid]]到达AI之前的令牌。AI可以将令牌传递回写入工具,入站端在API调用之前替换明文。存储仅在内存中;键映射由以下键设置Mcp-Session-Id永远不要碰磁盘。
故意不标记:
- mac地址 --无线电范围内的任何人都可以观察到(BSSID广播、客户端探测请求)。仅正常化。
- SSID / ESSID --在信标帧中广播(在v2.3.1.1中进行了改进)。
- 平台UUID 喜欢
org_id,site_id,device_id,template_id-Mist的API中已经不透明的随机标识符;用另一个UUID替换一个UUID不会增加隐私(在v2.3.1.1中进行了改进)。 - 地理数据 —
address,city,state,zip,latitude,longitude,room,building--通常可以在公司网站上找到(在v2.3.1.1中进行了改进)。 - 所有IP地址 (v2.3.1.2)--内部RFC1918、公共WAN、CIDR范围。网络上的任何人都知道内部子网拓扑,CIDR/路由分析是一项核心审计任务。
无论字段名如何,始终进行标记(v2.3.1.2):
- 电子邮件地址 --即使字段已命名,也会被捕获
name,username或其他任何东西。在此之前,Mist使用用户电子邮件作为PSK显示名称的MPSK模式是一个漏洞。 - AWS签名的URL凭据 --任何包含以下内容的字符串
X-Amz-Security-Token,X-Amz-Credential,或X-Amz-Signature被视为临时AWS凭证,并整体标记为APITOKEN.捕捉portal_template_urlMist的S3支持的专属门户预览泄露。
中心覆盖范围(v2.3.1.3): 规则集现在还涵盖了中央响应形状-- user_name, updated_by, created_by (审计日志字段)标记为 USER;连字符键如 wpa-passphrase 和 shared-secret 将相同的秘密规则与它们的snakecase等效规则相匹配。中央组织结构(device_group_name, scope_name)以明文形式传递。
往返适用于所有类型。 相同的明文→ 会话中的相同令牌。无线局域网同步,AOS 8→ AOS 10迁移和大规模PSK旋转都是有效的,因为标记化是可往返的。
标记化参考
秘密 --当字段名匹配时无条件标记(不区分大小写;连字符和空格标准化为下划线):
| 类别 | 字段名称 | 令牌形式 |
|---|---|---|
| WPA2/WPA3密钥 | psk, passphrase, wpa_passphrase, wpa2_passphrase, wpa3_psk, ppsk |
[[PSK:uuid]] |
| SAE/个人升级版 | sae_password, sae_pwd |
[[PSK:uuid]] |
| VRRP群集密钥 | vrrp_passphrase |
[[PSK:uuid]] |
| RADIUS共享密钥 | shared_secret, radius_secret, radsec_secret, coa_secret (v3.1.0.4/#321);结构对 rad_key.key, coa_servers[].secret |
[[RAD:uuid]] |
| EAP/内部密码 | eap_password, inner_password |
[[RAD:uuid]] |
| TACACS+ | 结构对 tacacs_key.key |
[[TACACS:uuid]] |
| CoA/RFC-3576端点标识符 | coa_servers[].ip, rfc_3576_server_list[].name;AOS 8单服务器详细信息表单包装密钥 "RFC 3576 Server " 就地重写(v3.1.0.4/#319) |
[[COA:uuid]] |
| SNMP 团体 | community, community_string |
[[SNMP:uuid]] |
| SNMP v3密码 | auth_password, priv_password, snmp_v3_auth_pass, snmp_v3_priv_pass |
[[SNMP:uuid]] |
| 管理员/启用密码 | admin_password, manager_password, support_user_password, enable_password, enable_secret, cli_password |
[[PASSWORD:uuid]] |
| IPSec/VPN PSK | pre_shared_key, ipsec_psk, vpn_psk |
[[VPNPSK:uuid]] |
| API令牌/OAuth | api_token, apitoken, api_key, apikey, client_secret |
[[APITOKEN:uuid]] |
| OAuth承载/刷新 | bearer_token, access_token, refresh_token |
[[APITOKEN:uuid]] |
| Webhook的秘密 | webhook_secret, webhook_token |
[[APITOKEN:uuid]] |
| AWS签名URL(值形状) | 任何包含以下内容的字符串 X-Amz-Security-Token, X-Amz-Credential,或 X-Amz-Signature |
[[APITOKEN:uuid]] |
| 证书 | cert, certificate, client_cert, server_cert, ca_cert, chain, pkcs12, p12_data, pem |
[[CERT:uuid]] |
| 免费文本PEM证书 | PEM块(-----BEGIN ... -----END)发现于 description / notes / comment |
[[CERT:uuid]] |
| 私钥 | private_key, privkey, kerberos_keytab, keytab |
[[KEY:uuid]] |
| 自由文本中的私钥PEM | PEM关键块 description / notes / comment |
[[KEY:uuid]] |
| 通用(形状已检查) | password, pwd → 密码; secret → RAD; token, key → APITOKEN。仅当值通过长度≥8+字符类多样性检查时(抑制 {"key": "ssid"}). |
各不相同 |
来源掩盖秘密 --当源平台本身屏蔽该值时(v3.1.0.4/#276):
| 源值 | 重写为 | 注释 |
|---|---|---|
******** (任何字段--AOS 8屏蔽RADIUS/TACACS/RFC-3576服务器端共享密钥) |
REPLACE_ME |
字面指令, 不是令牌一个明确的“操作员必须设置此”标记用于迁移输出-- ******** 读作“编辑/隐藏”, REPLACE_ME 读起来像一条指令。行走是幂等的 REPLACE_ME 即使在精确匹配的秘密字段中,也永远不会被标记。 |
标识符 --当字段名匹配时进行标记:
| 类别 | 字段名称 | 令牌形式 |
|---|---|---|
| 主机名/FQDN | hostname, host_name, fqdn |
[[HOSTNAME:uuid]] |
| 设备名称 | device_name, ap_name, controller_name, switch_name |
[[HOSTNAME:uuid]] |
AAA服务器 host 开拓 |
host (AOS 8 RADIUS/TACACS/LDAP服务器IP或FQDN) |
[[HOSTNAME:uuid]] |
裸露的 name (启发式) |
name 当父字典有≥2个设备形状兄弟时的字段: mac, model, serial, device_type, hw_rev, firmware, version, release_type |
[[HOSTNAME:uuid]] |
| 保护用户名 | username, user, user_name, login |
[[USER:uuid]] |
| 人名 | first_name, last_name, full_name, display_name |
[[USER:uuid]] |
| 审计日志参与者 | updated_by, created_by |
[[USER:uuid]] |
| 电子邮件 | email 场;在任何字符串字段中也通过值形状正则表达式进行匹配 |
[[EMAIL:uuid]] |
| 电话 | phone, phone_number, mobile |
[[PHONE:uuid]] |
| 硬件系列 | serial, serial_number, sn |
[[SERIAL:uuid]] |
| 手机IMEI | imei |
[[IMEI:uuid]] |
| 蜂窝IMSI | imsi |
[[IMSI:uuid]] |
| 蜂窝ICCID | iccid |
[[ICCID:uuid]] |
明文 --故意不标记:
| 字段族 | 为什么选择明文 |
|---|---|
| mac地址 | 在无线电范围内可观测(BSSID、探测请求)。标准化为规范 aa:bb:cc:dd:ee:ff 不管 ENABLE_PII_TOKENIZATION. |
| IP地址(通用) | 网络拓扑结构是众所周知的;CIDR/路由分析是核心审计工具。剥离:CoA端点IP和RADIUS/TACACS服务器 host IP(AOS 8 AAA服务器详细信息)被标记。 |
| SSID / ESSID | 信标帧中的广播 |
| 平台UUID | org_id, site_id, device_id, template_id, scope_id --已经不透明的随机ID |
| 地理数据 | address, city, state, zip, latitude, longitude, room, building --通常在公司网站上公开 |
| 组织标签 | org_name, site_name, vlan_name, subnet_name, scope_name, device_group_name --建筑标签,而不是人 |
| 源代码掩码占位符 | 例如AOS 8 ******** --将面具标记化会产生危险的幻觉;往返仅恢复占位符,并静默中断下游写入 |
中的每个标记化/去标记化事件都会触发审计日志记录 docker compose logs --种类、令牌ID、值哈希(SHA-256截断),但从不包括明文。
> 限制: 仅此版本的Mist规则集;中央/绿湖/克利尔帕斯/阿普斯特拉/安讯士紧随其后。用户粘贴到AI提示中的任何内容都不在我们的威胁模型范围内——这一转变已经具有了对话上下文中的字面意义。密钥映射在服务器重启时死亡;保存的对旧令牌的聊天引用变得无法解析。
网络安全
MCP HTTP传输附带了两层开箱即用的防御:
- 仅环回端口发布 —
docker-compose.yml发表127.0.0.1:8000:8000,因此只有主机上的进程才能到达MCP端点。没有局域网主机可以连接,即使它知道IP。(在容器内,应用程序仍然绑定0.0.0.0--那是集装箱的 拥有 网络命名空间,是Docker的端口转发器转发到的;请勿更改。) Origin标题满列表 --MCP Streamable HTTP规范要求防御浏览器驱动的DNS重新绑定。服务器拒绝任何请求Origin设置为外部值ALLOWED_ORIGINS(默认值:localhost和127.0.0.1).非浏览器客户端(超级网关、curl、原生MCP客户端)不发送Origin并通过。
如果将服务器置于已经验证源的身份验证反向代理之后,请设置 ALLOWED_ORIGINS=* 绕过进程检查。请参阅 配置 详情请参阅表格。
> 不支持多主机/远程访问配置。 服务器上没有内置身份验证 /mcp --任何能够访问该端口的人都可以完全管理每个连接的平台。如果您需要远程访问,请在反向代理(nginx+mTLS/OIDC、Cloudflare access、Tailscale Funnel等)处终止,并且永远不要直接暴露已发布的端口。
秘密
此项目使用 Docker编写秘密 用于凭证管理——最安全的Docker原生方法:
- 每个凭证都是 单独文件 在
secrets/目录 - 文件已装载 只读 在
/run/secrets/集装箱内 - 秘密是 从不 烘焙到Docker镜像中,在
docker inspect,或作为环境变量存储 - 真正的秘密文件是 git被忽略 --只有
.example模板已提交
运作原理```
secrets/
├── mist_api_token.example # Template (committed to git)
├── mist_api_token # Your real secret (git-ignored)
├── mist_host.example
├── mist_host
└── ...
Docker Compose读取这些文件并将其挂载到 `/run/secrets/` 在容器内。服务器在启动时读取每个文件。
### 平台凭据
#### 朱尼珀薄雾
|机密文件|说明|如何获取|
|-------------|-------------|---------------|
| `mist_api_token` |Mist API代币| Mist Dashboard>组织>设置>API代币|
| `mist_host` |喷雾API主机| `api.mist.com` (全球), `api.eu.mist.com` (欧盟), `api.gc1.mist.com` (政府云)|
#### 阿鲁巴中央
|机密文件|说明|如何获取|
|-------------|-------------|---------------|
| `central_base_url` |中央API网关URL|HPE GreenLake平台>阿鲁巴中央>API网关|
| `central_client_id` |OAuth2客户端ID | HPE GreenLake平台>API客户端|
| `central_client_secret` |OAuth2客户端机密| HPE GreenLake平台>API客户端|
#### HPE GreenLake
|机密文件|说明|如何获取|
|-------------|-------------|---------------|
| `greenlake_api_base_url` |GreenLake API基础URL |通常 `https://global.api.greenlake.hpe.com` |
| `greenlake_client_id` |OAuth2客户端ID | HPE GreenLake平台>API客户端|
| `greenlake_client_secret` |OAuth2客户端机密| HPE GreenLake平台>API客户端|
| `greenlake_workspace_id` |GreenLake工作空间ID | HPE GreenLake平台>工作空间|
#### 阿鲁巴ClearPass
|机密文件|说明|如何获取|
|-------------|-------------|---------------|
| `clearpass_server` |clearpass API URL| `https://your-clearpass-server/api` --CPPM服务器主机名 `/api` 路径|
| `clearpass_client_id` |OAuth2客户端ID | ClearPass管理>API客户端>创建API客户端|
| `clearpass_client_secret` |OAuth2客户端机密| ClearPass管理>API客户端>客户端机密|
| `clearpass_verify_ssl` |SSL验证(可选)| `true` (默认)或 `false` 用于自签名证书|
#### Aruba OS 8/移动指挥
|机密文件|必填|默认|用途|
|---|---|---|---|
| `aos8_host` |是|--|导体或独立控制器主机名/IP|
| `aos8_username` |是|-|neneneba API用户名,具有足够的角色|
| `aos8_password` |是|-|neneneba API密码|
| `aos8_port` |没有| `4343` |HTTPS端口(Mobility Conductor API端口)|
| `aos8_verify_ssl` |没有| `true` |设置为 `false` 对于自签名证书(记录为警告)|
集 `ENABLE_AOS8_WRITE_TOOLS=true` 公开12个AOS8编写工具(由启发中间件控制;默认 `false`).
______________________________________________________________________
## 建筑```
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ MCP Client (Claude, VS Code, etc.) │
└───────────────────────────────────────┬─────────────────────────────────────────────────┘
│ Streamable HTTP
▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ HPE Networking MCP Server (:8000) — MCP_TOOL_MODE=code (default since v3.0.0.0) │
│ │
│ Exposed to the AI (6 tools in code mode): │
│ • execute (sandboxed Python; await call_tool(name, params) inside) │
│ • 5 discovery tools: tags, search, get_schema, skills_list, skills_load │
│ Set MCP_TOOL_MODE=dynamic to use the v2.x meta-tool surface (24 tools). │
│ │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Mist │ │Central │ │GreenLk │ │ClrPass │ │ Apstra │ │ Axis │ │ AOS8 │ │
│ │ mist_* │ │centrl_*│ │grnlake │ │clrpass │ │apstra_*│ │ axis_* │ │ aos8_* │ │
│ │ 1037 │ │613tools│ │10 tools│ │140 tool│ │19 tools│ │25 tools│ │47 tools│ │
│ │+2 prmt │ │+12prmt │ │ │ │ │ │ │ │ │ │+9 prmt │ │
│ │
│ All 1891 underlying tools reachable via call_tool() in code mode or via │
│ per-platform meta-tools (_list_tools / get_schema / invoke) in dynamic mode. │
│ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ │
│ │ │ │ │ │ │ │ │
└─────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼─────────────────┘
▼ ▼ ▼ ▼ ▼ ▼ ▼
Mist Cloud Aruba GreenLake ClearPass Apstra Axis Mobility
API Central API CPPM API Fabric API Atmos Conductor
API Cloud API
关键设计决策:
- FastMCP Python 3.12框架+
- 流式HTTP 运输(现代MCP标准)
- 默认代码工具模式(自v3.0.0.0起) --只有
execute+5个发现工具暴露;所有1891个底层工具均可通过以下方式访问await call_tool(name, params)在沙箱里。最小的初始代币成本;最适合驾驶小型/本地LLM的管弦乐队。集MCP_TOOL_MODE=dynamic对于v2.x元工具表面(24个工具,约3700个令牌)。 - 工具名称间距 —
mist_*,central_*,greenlake_*,clearpass_*,apstra_*,axis_*前缀可防止冲突 - 平台隔离 -每个模块管理自己的API客户端和身份验证;一个失败的平台不会影响其他平台
- 非根容器 --运行为
mcpuser(uid 1000)
写入操作和安全
安全控制支持写入/修改工具(例如,在Mist中创建WLAN、修改配置):
- 默认情况下已禁用 --启用每个平台
ENABLE_MIST_WRITE_TOOLS=true,ENABLE_CENTRAL_WRITE_TOOLS=true,ENABLE_CLEARPASS_WRITE_TOOLS=true,ENABLE_APSTRA_WRITE_TOOLS=true,ENABLE_AXIS_WRITE_TOOLS=true,或ENABLE_AOS8_WRITE_TOOLS=true - 需要激励 --执行前编写工具提示以供用户确认
- 基于注解 --所有工具都带有MCP注释(
readOnlyHint,destructiveHint等等)
| 环境变量 | 默认值 | 效果 |
|---|---|---|
ENABLE_MIST_WRITE_TOOLS |
false |
启用Mist写入/突变工具 |
ENABLE_CENTRAL_WRITE_TOOLS |
false |
启用中央写入/变异工具 |
ENABLE_CLEARPASS_WRITE_TOOLS |
false |
启用ClearPass写入/突变工具 |
ENABLE_APSTRA_WRITE_TOOLS |
false |
启用Apstra写入/变异工具 |
ENABLE_AXIS_WRITE_TOOLS |
false |
启用Axis Atmos Cloud写入/转换工具(每个写入阶段--调用 axis_commit_changes 申请) |
ENABLE_AOS8_WRITE_TOOLS |
false |
启用AOS8写入工具(12个工具;每次写入都会返回 requires_write_memory_for --呼叫 aos8_write_memory 明确) |
DISABLE_ELICITATION |
false |
跳过用户对写入工具的确认(谨慎使用) |
可靠性
服务器透明地重试短暂的API故障,这样AI就不必对脆弱的上游服务进行推理。
- 读取工具上的5xx错误 --采用指数回退自动重试(1s、2s、4s——共3次尝试)
- 429个速率限制响应 --在读取和写入时都重试了(总是安全的——服务器要求我们减速)。荣誉
Retry-After响应标头(如果存在),上限为60秒 - 写入工具(5xx) --从不自动重试幂等性安全。错误出现在AI面前,AI可以决定是否重新发布
- 4xx错误(429除外) --从未重试;立即浮出水面
重试逻辑以两种模式检测瞬态故障:响应字典(Mist/Central/ClearPass返回 {"status_code": 503, ...})和httpx异常(GreenLake/Apstra/Axis升高 httpx.HTTPStatusError).读/写分类是通过底层工具的标签进行的——任何标记的东西 *_write 或 *_write_delete 被视为书写。
| 环境变量 | 默认值 | 效果 |
|---|---|---|
RETRY_MAX_ATTEMPTS |
3 |
包括第一次呼叫在内的最大尝试次数。设为 1 完全禁用重试 |
RETRY_INITIAL_DELAY |
1.0 |
初始回退延迟(秒)(每次尝试加倍,最多可达 RETRY_MAX_DELAY) |
RETRY_MAX_DELAY |
60.0 |
单次睡眠的上限——也是上限 Retry-After 标题值 |
配置
| 环境变量 | 默认值 | 描述 |
|---|---|---|
MCP_PORT |
8000 |
MCP服务器监听的端口 |
MCP_HOST |
0.0.0.0 |
绑定地址 在容器的命名空间内 --离开 0.0.0.0 因此Docker的端口转发器可以访问该应用程序。限制谁可以通过访问主机端口 ports: 在作曲中,不是这个。 |
ALLOWED_ORIGINS |
http://localhost:,http://127.0.0.1: |
逗号分隔的满列表 Origin 请求标头(根据MCP规范的DNS重新绑定防御)。浏览器总是发送 Origin;非浏览器客户端(supergateway、curl)不会通过。设为 * 禁用检查(仅在身份验证代理后使用)。 |
SECRETS_DIR |
/run/secrets |
包含Docker机密文件的目录 |
LOG_LEVEL |
info |
日志记录级别(debug, info, warning, error) |
ENABLE_MIST_WRITE_TOOLS |
false |
启用Mist写入/突变工具 |
ENABLE_CENTRAL_WRITE_TOOLS |
false |
启用中央写入/变异工具 |
ENABLE_CLEARPASS_WRITE_TOOLS |
false |
启用ClearPass写入/突变工具 |
ENABLE_APSTRA_WRITE_TOOLS |
false |
启用Apstra写入/变异工具 |
ENABLE_AXIS_WRITE_TOOLS |
false |
启用Axis写入/变异工具(分阶段;使用提交 axis_commit_changes) |
ENABLE_AOS8_WRITE_TOOLS |
false |
启用AOS8写入工具(调用 aos8_write_memory 每次更改后保持不变) |
DISABLE_ELICITATION |
false |
禁用写入确认提示 |
MCP_TOOL_MODE |
code |
工具暴露: code (自v3.0.0.0以来默认为6个顶级工具: execute +5发现;所有1891个底层工具均可通过以下方式访问 call_tool() 沙盒内)或 dynamic (24个工具——4个跨平台+每个平台21个元工具+2个技能工具;底层工具隐藏,直到通过调用 _invoke_tool).这 static 在v3.0.0.0中删除了该值 |
RETRY_MAX_ATTEMPTS |
3 |
瞬时失败时的最大重试次数(5xx次读取,429次读取+写入)。设为 1 禁用重试 |
RETRY_INITIAL_DELAY |
1.0 |
初始重试回退秒数(指数:1s、2s、4s) |
RETRY_MAX_DELAY |
60.0 |
单次重试睡眠的上限(也为上限 Retry-After 标题值) |
ENABLE_PII_TOKENIZATION |
false |
在工具响应到达AI之前,对工具响应中的敏感字段(PSK、RADIUS机密、主机名、电子邮件等)进行令牌化。往返:AI将令牌传递回写入工具,中间件替换明文。无论此切换如何,MAC规范化始终处于打开状态。看 PII标记化 上面。 |
PII_MAX_TOKENS_PER_SESSION |
10000 |
每个会话密钥映射大小的软上限。Cap hit会记录一个警告,并以明文形式执行,而不是错误地发出呼叫。 |
发展
所有的开发都发生在Docker容器中。
从源代码构建
编辑 docker-compose.yml --发表评论 image: 并取消注释 build::```yaml
services:
hpe-networking-mcp:
image: ghcr.io/nowireless4u/hpe-networking-mcp:latest
build: .
然后重建:```bash
docker compose up -d --build
运行测试```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm \
hpe-networking-mcp uv run pytest tests/ -v
### 完整CI检查
在推动尽早发现问题之前运行此命令:```bash
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm \
hpe-networking-mcp sh -c \
"uv run ruff check . && uv run ruff format --check . && \
uv run mypy src/ --ignore-missing-imports && uv run pytest tests/ -q"
看 贡献.md 完整的开发工作流程。
项目结构```
hpe-networking-mcp/
├── src/hpe_networking_mcp/
│ ├── main.py # CLI entry point
│ ├── server.py # FastMCP server setup and lifespan
│ ├── config.py # Docker secrets loading and validation
│ ├── INSTRUCTIONS.md # LLM instructions for all platforms
│ ├── middleware/ # null-strip, validation-catch, sandbox-error-catch, elicitation, retry
│ ├── skills/ # Markdown-defined multi-step procedures + skills engine
│ └── platforms/
│ ├── _common/ # Shared tool registry + meta-tool factory (dynamic mode)
│ ├── health.py # Cross-platform health probe tool
│ ├── mist/ # 1037 Mist tools (spec-driven) + 2 prompts + API client
│ ├── central/ # 88 Central tools + 12 prompts + API client
│ ├── greenlake/ # 10 GreenLake tools + OAuth2 client
│ ├── clearpass/ # 140 ClearPass tools + pyclearpass SDK client
│ ├── apstra/ # 19 Apstra tools + async httpx client
│ ├── axis/ # 25 Axis Atmos Cloud tools + httpx client (JWT bearer)
│ ├── aos8/ # 47 AOS8 tools + 9 prompts + UIDARUBA session client
│ ├── manage_wlan.py # Cross-platform WLAN management tool
│ ├── sync_prompts.py # Cross-platform WLAN sync prompts
│ ├── site_health_check.py # Cross-platform site health aggregator
…(正文过长,页面只展示前面部分,完整内容见仓库)
```