金大哥 - hyperfabric

article

README

🚀 Hyperfabric MCP Server

Hyperfabric MCP Server 是一个 MCP（模型上下文协议）服务器，它使大语言模型（LLMs）能够与 Hyperfabric API 进行交互。该服务器将 79 个 Hyperfabric OpenAPI 端点全部作为工具公开，用于全面的基础设施管理和自动化。

✨ 主要特性

🔧 动态工具生成：自动解析 Hyperfabric OpenAPI 规范并创建 MCP 工具。
🛡️ 安全认证：以适当的安全措施处理 Hyperfabric API 令牌认证。
📊 完整的 API 覆盖：公开所有 79 个可用的 Hyperfabric 端点，用于基础设施管理。
✨ 简洁的工具名称：工具以直观的名称显示，如 fabricsGetAllFabrics，便于查找。

📦 安装指南

前提条件

安装 Node.js 18 及以上版本。
安装带有 GitHub Copilot 的 VSCode 或 Claude Desktop。
拥有 Hyperfabric API 凭证（API 令牌）。
具备 Hyperfabric OpenAPI 规范文件。

1. 构建服务器

npm install
npm run build

2. 配置大语言模型客户端

对于带有 GitHub Copilot 的 VSCode

打开 VSCode 设置：Cmd+Shift+P → "Preferences: Open User Settings (JSON)"。
将以下配置添加到 settings.json 中：

{
  "github.copilot.chat.mcp.servers": {
    "hyperfabric": {
      "command": "node",
      "args": ["/path/to/hyperfabric-mcp-server/dist/main.js"],
      "env": {
        "HYPERFABRIC_API_TOKEN": "your-api-token",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重新加载 VS Code：Cmd+Shift+P → "Developer: Reload Window"。

对于 Claude Desktop

找到你的 Claude Desktop 配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
将以下配置添加到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "hyperfabric": {
      "command": "node",
      "args": ["/path/to/hyperfabric-mcp-server/dist/main.js"],
      "env": {
        "HYPERFABRIC_API_TOKEN": "your-api-token",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重启 Claude Desktop 应用程序。

Hyperfabric MCP 配置

Hyperfabric MCP 设置

💻 使用示例

可用工具和功能

MCP 服务器根据完整的 Nexus Hyperfabric REST API v1.1.0 规范自动生成 79 个工具：

🔑 认证与用户管理（9 个工具）

Bearer 令牌管理：安全的 API 认证
- authGetBearerTokens - 列出用户的所有 bearer 令牌。
- authCreateBearerTokens - 创建新的 bearer 令牌。
- authGetBearerToken - 获取特定 bearer 令牌的详细信息。
- authDeleteBearerToken - 删除特定的 bearer 令牌。
用户管理：用户账户操作
- authGetUsers - 列出组织中的所有用户。
- authGetUser - 获取特定用户的详细信息。
- authSetUsers - 创建或更新用户。
- authUpdateUser - 更新现有用户。
- authDeleteUser - 删除用户账户。

🖥️ 设备管理（3 个工具）

设备操作：物理设备管理和绑定
- devicesGetDevices - 列出所有设备（已绑定和未绑定）。
- devicesBindDevice - 将设备绑定到 fabric 节点。
- devicesUnbindDevice - 从 fabric 节点解绑设备。

🏗️ 架构管理（16 个工具）

架构配置：核心架构操作
- fabricsGetAllFabrics - 列出组织中的所有架构。
- fabricsAddFabrics - 创建新的架构。
- fabricsGetFabric - 获取特定架构的详细信息。
- fabricsUpdateFabric - 更新架构配置。
- fabricsDeleteFabric - 删除架构。
连接管理：架构网络连接
- fabricsGetFabricConnections - 列出架构中的所有连接。
- fabricsAddFabricConnections - 添加新的连接。
- fabricsGetFabricConnection - 获取特定连接的详细信息。
- fabricsSetFabricConnections - 替换所有连接。
- fabricsDeleteFabricConnections - 删除所有连接。
- fabricsDeleteFabricConnection - 删除特定连接。
配置管理：候选配置和部署
- fabricsGetFabricCandidates - 列出候选配置。
- fabricsGetFabricCandidate - 获取特定候选配置。
- fabricsCommitFabricCandidate - 将候选配置部署到运行配置中。
- fabricsRevertFabricCandidate - 丢弃候选配置。
- fabricsReviewFabricCandidate - 为候选配置添加注释。

🌐 网络配置（3 个工具）

生成树协议：全局 STP 设置
- networksGetFabricStp - 获取架构的 STP 配置。
- networksUpdateFabricStp - 更新 STP 设置。
- networksResetFabricStp - 将 STP 重置为默认值。

📦 节点管理（25 个工具）

节点操作：架构节点配置
- nodesGetFabricNodes - 列出架构中的所有节点。
- nodesAddFabricNodes - 向架构中添加新节点。
- nodesGetNamedFabricNode - 获取特定节点的详细信息。
- nodesUpdateFabricNode - 更新节点配置。
- nodesDeleteFabricNode - 从架构中移除节点。
端口管理：节点端口配置
- nodesGetPorts - 列出节点的所有端口。
- nodesGetPort - 获取特定端口的详细信息。
- nodesUpdatePort - 更新端口配置。
- nodesSetPorts - 替换所有端口配置。
- nodesResetPort - 将端口重置为默认值。
管理端口：带外管理接口
- nodesGetManagementPorts - 列出管理端口。
- nodesAddManagementPorts - 添加管理端口。
- nodesGetManagementPort - 获取特定管理端口。
- nodesUpdateManagementPort - 更新管理端口配置。
环回接口：用于路由的虚拟接口
- nodesGetNodeLoopbacks - 列出环回接口。
- nodesAddNodeLoopbacks - 创建环回接口。
- nodesGetNodeLoopback - 获取特定环回接口的详细信息。
- nodesUpdateNodeLoopback - 更新环回接口配置。
- nodesDeleteNodeLoopback - 删除环回接口。
子接口：VLAN 和子接口配置
- nodesGetNodeSubInterfaces - 列子接口。
- nodesAddNodeSubInterfaces - 创建子接口。
- nodesGetNodeSubInterface - 获取特定子接口。
- nodesUpdateNodeSubInterface - 更新子接口配置。
- nodesDeleteNodeSubInterface - 删除子接口。

⚡ 端口通道管理（5 个工具）

链路聚合：端口通道操作
- portchannelsGetAllPortChannels - 列出所有端口通道。
- portchannelsAddPortChannels - 创建端口通道。
- portchannelsGetPortChannel - 获取特定端口通道。
- portchannelsUpdatePortChannel - 更新端口通道配置。
- portchannelsDeletePortChannel - 删除端口通道。

🏷️ VNI 管理（9 个工具）

虚拟网络标识符：VXLAN 网络分段
- vnisGetFabricVnis - 列出架构中的所有 VNI。
- vnisAddFabricVnis - 创建新的 VNI。
- vnisGetFabricVni - 获取特定 VNI 的详细信息。
- vnisUpdateFabricVni - 更新 VNI 配置。
- vnisDeleteFabricVni - 删除 VNI。
VNI 成员关系：成员接口管理
- vnisGetFabricVniMembers - 列出 VNI 成员。
- vnisAddFabricVniMembers - 向 VNI 添加成员。
- vnisGetFabricVniMember - 获取特定成员的详细信息。
- vnisDeleteFabricVniMember - 从 VNI 中移除成员。

🔀 VRF 管理（9 个工具）

虚拟路由和转发：三层网络隔离
- vrfsGetFabricVrfs - 列出架构中的所有 VRF。
- vrfsAddFabricVrfs - 创建新的 VRF。
- vrfsGetFabricVrf - 获取特定 VRF 的详细信息。
- vrfsUpdateFabricVrf - 更新 VRF 配置。
- vrfsDeleteFabricVrf - 删除 VRF。
静态路由：VRF 内的静态路由管理
- vrfsGetFabricStaticRoutes - 列出 VRF 中的静态路由。
- vrfsAddFabricStaticRoutes - 添加静态路由。
- vrfsGetFabricStaticRoute - 获取特定路由的详细信息。
- vrfsUpdateFabricStaticRoute - 更新静态路由。
- vrfsDeleteFabricStaticRoute - 删除静态路由。

📚 详细文档

环境变量

| 属性 | 详情 | 默认值 | 是否必需 | |------|------|--------|----------| | HYPERFABRIC_API_TOKEN | 你的 Hyperfabric API 令牌 | - | ✅ | | LOG_LEVEL | 日志记录级别（debug、info、warn、error） | info | ❌ | | OPENAPI_SPEC_PATH | OpenAPI 规范文件的路径 | hf_spec_modified.json | ❌ |

开发设置

项目结构

hyperfabric-mcp-server/
├── src/main.ts                                                    # 主服务器实现
├── dist/                                                          # 编译后的 JavaScript
├── .vscode/                                                       # VS Code 配置
├── package.json                                                   # 依赖项和脚本
├── tsconfig.json                                                  # TypeScript 配置
├── hf_spec_modified.json                                          # 完整的 Nexus Hyperfabric REST API v1.1.0 规范
├── cisco_nexus_hyperfabric_rest_api_1_1_0_rev_2025_10_29_838_c_8.yaml # 原始 YAML 规范文件
└── README.md                                                      # 本文档

故障排除

常见问题

缺少 API 令牌

# 检查环境文件
cat .env | grep HYPERFABRIC_API_TOKEN

缺少 OpenAPI 规范

# 验证规范文件是否存在
ls -la hf_spec_modified.json

编译错误

# 检查编译情况
npm run build

hyperfabric_mcp