Hpe Networking MCP

HPE网络MCP服务器

 

非官方/社区项目。 这个存储库是一个独立的、由社区驱动的项目。它不隶属于惠普企业、Aruba Networks或瞻博网络，也不受其认可、赞助或支持。“HPE”、“阿鲁巴”、“阿鲁巴岛中央”、“Aruba ClearPass”、“HPE GreenLake”、“Juniper”和“Juniper-Mist”是其各自所有者的商标，在这里仅用于描述此软件与之互操作的内容。请将有关这些产品的支持和许可问题直接发送给相应的供应商。

统一的 模型上下文协议（MCP） 服务器带来 朱尼珀薄雾, 阿鲁巴中央, HPE GreenLake, 阿鲁巴ClearPass, Juniper Apstra，以及 Axis Atmos云 将它们组合成一个可部署的单一服务。一个集装箱。一个端点。所有HPE网络工具。

______________________________________________________________________

为什么？

如今，使用人工智能助手管理HPE网络基础设施意味着要处理多个单独的MCP服务器——每个服务器都有自己的设置、凭据和怪癖。该项目将它们整合为一个：

默认刀具表面（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，显示字段级别差异，并在任一方向上同步。

______________________________________________________________________

快速开始

先决条件

• 码头工人 和

1.获得项目

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停止尝试绑定它们。看 禁用不使用的平台 在......下面

对于您实际希望启用的平台，复制模板并使用实际值进行编辑：

# 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 保持不变。仓库中提供了一个可复制的模板：

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.启动

docker compose up -d

5.验证

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

您也可以直接拉动它：

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端点之间进行转换。

先决条件： 必须安装在您的计算机上。证实 npx --version 在你的终端。

第一步： 在文本编辑器中打开Claude Desktop配置文件：

提示： 您还可以从Claude Desktop中打开此文件：转到 设置 （齿轮图标）> 开发者 > 编辑配置.

第二步： 如果文件为空或不存在，请按原样粘贴整个块：

{
  "mcpServers": {
    "hpe-networking": {
      "command": "npx",
      "args": ["-y", "supergateway", "--streamableHttp", "http://localhost:8000/mcp"]
    }
  }
}

如果你 已经有其他MCP服务器 已配置，添加 "hpe-networking" 进入现有 "mcpServers" 对象。做 不 创建第二个 "mcpServers" 钥匙。例如，如果您已经有一个名为 "my-other-server":

{
  "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 列出了它的工具。

克劳德代码

不需要配置文件--运行以下命令：

claude mcp add hpe-networking --transport http http://localhost:8000/mcp

VS代码/GitHub副本

添加到您的 .vscode/mcp.json （如果文件不存在，则创建该文件）或VS Code MCP设置：

{
  "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_url Mist的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旋转都是有效的，因为标记化是可往返的。

标记化参考

秘密 --当字段名匹配时无条件标记（不区分大小写；连字符和空格标准化为下划线）：

来源掩盖秘密 --当源平台本身屏蔽该值时（v3.1.0.4/#276）：

标识符 --当字段名匹配时进行标记：

明文 --故意不标记：

中的每个标记化/去标记化事件都会触发审计日志记录 docker compose logs --种类、令牌ID、值哈希（SHA-256截断），但从不包括明文。

限制： 仅此版本的Mist规则集；中央/绿湖/克利尔帕斯/阿普斯特拉/安讯士紧随其后。用户粘贴到AI提示中的任何内容都不在我们的威胁模型范围内——这一转变已经具有了对话上下文中的字面意义。密钥映射在服务器重启时死亡；保存的对旧令牌的聊天引用变得无法解析。

网络安全

MCP HTTP传输附带了两层开箱即用的防御：

1. 仅环回端口发布 — docker-compose.yml 发表 127.0.0.1:8000:8000，因此只有主机上的进程才能到达MCP端点。没有局域网主机可以连接，即使它知道IP。（在容器内，应用程序仍然绑定 0.0.0.0 --那是集装箱的 *拥有* 网络命名空间，是Docker的端口转发器转发到的；请勿更改。）
2. 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/ 在容器内。服务器在启动时读取每个文件。

平台凭据

朱尼珀薄雾

阿鲁巴中央

HPE GreenLake

阿鲁巴ClearPass

Aruba OS 8/移动指挥

集 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等等）

______________________________________________________________________

可靠性

服务器透明地重试短暂的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 被视为书写。

______________________________________________________________________

配置

______________________________________________________________________

发展

所有的开发都发生在Docker容器中。

从源代码构建

编辑 docker-compose.yml --发表评论 image: 并取消注释 build::

services:
  hpe-networking-mcp:
    # image: ghcr.io/nowireless4u/hpe-networking-mcp:latest
    build: .

然后重建：

docker compose up -d --build

运行测试

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm \
  hpe-networking-mcp uv run pytest tests/ -v

完整CI检查

在推动尽早发现问题之前运行此命令：

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
│       └── site_rf_check.py     # Cross-platform Wi-Fi RF dashboard
├── tests/                       # Unit and integration tests (1158+ unit tests)
├── docs/                        # PRD, PRP, tool reference
├── secrets/                     # Secret files (only .example committed)
├── .github/workflows/           # CI, security, Docker publish
├── Dockerfile                   # Multi-stage build, non-root user
├── docker-compose.yml           # Production (pulls GHCR image)
└── docker-compose.dev.yml       # Development (mounts tests)

______________________________________________________________________

故障排除

查看日志

当事情不起作用时，总是从这里开始：

docker compose logs                        # All logs
docker compose logs --tail 50              # Last 50 lines
docker compose logs -f                     # Follow live

启动时平台已禁用

如果平台显示为禁用，则从容器的角度来看，相关的秘密文件要么不存在，要么为空：

Mist: disabled (mist_api_token secret not found)
Central: disabled (missing secrets: central_client_id, central_client_secret)

修复： 在中填充丢失的机密文件 secrets/ 具有实际值（没有额外的空格或换行符——每个文件应该只包含一个值）。如果你 *预期的* 要禁用该平台，请忽略该消息——服务器将继续使用具有凭据的平台运行。

集装箱立即出口 invalid mount config for type "bind"

Error response from daemon: invalid mount config for type "bind":
bind source path does not exist: .../secrets/apstra_verify_ssl

这意味着 docker-compose.yml 引用了磁盘上不存在的秘密文件，Docker绑定挂载失败 *之前* 应用程序已启动。两个修复：

• 如果您希望启用该平台： 跑 cp secrets/.example secrets/ 并用您的实际值填充文件。
• 如果你不想要这个平台： 通过删除平台的秘密引用 docker-compose.override.yml （参见 禁用不使用的平台).

做 不 使用剩余的占位符内容创建一个空文件 .example 模板——应用程序将启动，但无法对假值进行身份验证，如中所述 平台自动禁用.

身份验证失败

薄雾 — Permission Denied 或 401 Unauthorized:

• 在Mist Dashboard中验证您的API令牌是否有效
• 检查一下 mist_host 匹配您的地区(api.mist.com, api.eu.mist.com, api.gc1.mist.com)

中央 — Login Failed 或令牌错误：

• 验证 central_base_url 匹配您的中央实例（例如。， https://us5.api.central.arubanetworks.com)
• 确保OAuth2客户端ID和密钥正确且未过期
• 检查API客户端在HPE GreenLake平台中是否具有正确的作用域

绿湖 — Access token acquisition failed:

• 验证 greenlake_api_base_url （通常 https://global.api.greenlake.hpe.com)
• 检查客户端凭据是否有效以及工作区ID是否正确
• 令牌刷新会自动发生——如果失败，请检查日志以了解详细信息

ClearPass — ClearPass: failed to initialize:

• 验证 clearpass_server CPPM主机名是否正确 /api 路径（例如。， https://clearpass.example.com/api)
• 确保已使用在ClearPass Admin中创建OAuth2 API客户端 client_credentials 授权类型
• 对于自签名证书，设置 clearpass_verify_ssl 到 false
• 检查日志中的特定错误： docker compose logs | grep ClearPass

阿普斯特拉 — Apstra: failed to initialize 或登录错误：

• 验证 apstra_server 只是主机名（没有方案，没有端口），例如。， apstra.example.com
• 集 apstra_port 只有当你的Apstra服务器监听其他地方时 443
• 确保 apstra_username 和 apstra_password 属于可以访问的Apstra帐户 /api/user/login
• 对于自签名的Apstra证书，设置 apstra_verify_ssl 到 false （默认为 true)
• 检查日志中的特定错误： docker compose logs | grep Apstra

8000端口连接被拒绝

docker compose ps                          # Check container is running
docker compose restart                     # Restart the container

如果端口8000已被其他服务使用，请在中更改端口 docker-compose.yml （保持 127.0.0.1: 前缀）：

ports:
  - "127.0.0.1:8080:8000"    # Map to port 8080 instead, loopback-only

如果更改主机端口，也会更新 ALLOWED_ORIGINS 因此它匹配（例如。 ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080)--默认曲目 MCP_PORT （这是 *容器* 端口，8000），而不是主机端口。

AI客户端中未显示工具

1. 检查服务器是否正在运行： docker compose logs | grep "registered"
2. 验证端点是否可访问： curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/mcp （期待 406 --这对于普通GET来说是正常的）
3. 重新启动AI客户端 添加或更改MCP服务器配置后，会在会话开始时发现工具

Claude Desktop：“MCP服务器配置无效”

Claude Desktop本身不支持流式HTTP，它需要一个stdio桥。使用 supergateway:

{
  "mcpServers": {
    "hpe-networking": {
      "command": "npx",
      "args": ["-y", "supergateway", "--streamableHttp", "http://localhost:8000/mcp"]
    }
  }
}

如果工具在约4分钟后超时，请检查：

• Docker容器运行良好： docker compose ps
• Node.js已安装： npx --version
• 容器在睡眠后没有失去连接： docker compose restart

刀具表面看起来不对（6个刀具vs.1891）

从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() 块。启用了所有7个平台的正确配置的服务器将进行广告 6工具 AI客户端。

检查日志中的模式：

docker compose logs | grep "Tool mode"
# "Tool mode: code"      → default since v3.0.0.0 (6 exposed tools, 1891 underlying via call_tool)
# "Tool mode: dynamic"   → opt-in to v2.x meta-tool surface (24 exposed: 21 per-platform + 4 cross-platform + 2 skills)

使用v2.x元工具发现界面（每个平台都公开 _list_tools, _get_tool_schema, _invoke_tool)，set MCP_TOOL_MODE=dynamic 在 docker-compose.yml 在...之下 environment:

- MCP_TOOL_MODE=dynamic   # 24 exposed; per-platform meta-tools + cross-platform + skills
- MCP_TOOL_MODE=code      # 6 exposed; sandboxed call_tool() reaches all 1891 (default since v3.0.0.0)

这 static 在v3.0.0.0中删除了模式（前面可见的每个底层工具）——在1891个工具/约64K令牌的情况下，它不再实用。设置 MCP_TOOL_MODE=static 现在在启动时引发一个错误，并显示迁移消息。

看 docs/MIGRATING_TO_V2.md 对于v1.x→ v2.x元工具历史。

写入工具不可见

默认情况下，写入工具处于禁用状态。在中为每个平台启用它们 docker-compose.yml:

- ENABLE_MIST_WRITE_TOOLS=true
- ENABLE_CENTRAL_WRITE_TOOLS=true
- ENABLE_CLEARPASS_WRITE_TOOLS=true

然后重新启动： docker compose restart

容器崩溃或重新启动

检查退出代码和日志：

docker compose ps -a                       # Check exit code
docker compose logs --tail 100             # Check recent logs

常见原因：

• 没有有效凭据 --如果可以初始化零个平台，则服务器退出
• 端口冲突 --另一个服务正在使用端口8000
• 内存不足 --增加Docker的内存分配

______________________________________________________________________

贡献

欢迎投稿！这 main 分支受到保护——所有更改都通过带有CI检查的拉取请求进行。看 贡献.md 完整的开发工作流程。

有关每个工具及其参数的完整列表，请参阅 docs/TOOLS.md.

______________________________________________________________________

许可证

麻省理工学院