内容
# F5 分布式云（XC）MCP 服务器
MCP 服务器让 AI 助手可以访问整个 F5 分布式云 API。涵盖 18 类别下的 1764 个端点。与 **Claude Code**、**ChatGPT** 和任何兼容 MCP 的客户端配合使用。
## 工作原理
该服务器不是注册数千个单独的工具，而是公开了 18 个工具，让 AI 可以发现、探索和调用任何 F5 XC API 端点。对于负载均衡器和源池等常见资源，AI 可以完全跳过发现过程，而是使用预建的模板。对于多步骤状态突变，专用的补丁、差异和便利工具处理 GET、剥离和 PUT 往返过程，这样调用者就不需要这样做。
| 工具 | 用途 |
|------|---------|
| `xc_discover_apis` | 按关键词、类别或 HTTP 方法搜索 API 操作 |
| `xc_get_operation_details` | 获取操作的请求正文模板或完整模式 |
| `xc_resolve_schema_ref` | 将 OpenAPI 规范文件中的 JSON 模式 `$ref` 扩展到可配置的深度 |
| `xc_call_api` | 执行任何 API 调用，可选地过滤响应 |
| `xc_create_cert` | 生成具有 blindfold 加密私钥的自签名证书 |
| `xc_patch_resource` | 对资源应用 JSON-Patch 操作，处理 GET、剥离和 PUT 往返过程 |
| `xc_diff_resource` | 显示 PUT 将更改的内容为 JSON-Patch 差异，而不应用任何内容 |
| `xc_lb_wait_ready` | 轮询 HTTP 负载均衡器，直到其证书状态变为有效或超时 |
| `xc_lb_set_request_headers` | 添加或删除 HTTP 负载均衡器的请求头，处理 GET、剥离和 PUT 往返过程 |
| `xc_pool_attach_healthcheck` | 将命名健康检查附加到源池（幂等） |
| `xc_pool_detach_healthcheck` | 从源池分离命名健康检查 |
| `xc_dns_zone_status` | DNS 区域诊断汇总：部署状态、名称服务器和可选的数据平面探测 |
| `xc_query_access_logs` | 查询访问日志，支持解析、自动分页和可选的按组聚合 |
| `xc_query_lb_metrics` | HTTP 负载均衡器的时间桶请求计数和响应代码类别分解 |
| `xc_list_namespaces` | 列出命名空间，可选地过滤前缀 |
| `xc_list_resources` | 列出资源，支持字段投影和项目限制，以及可选的 `verify` 标志，删除 404 的名称 |
| `xc_search_resources` | 在多个命名空间中按名称查找资源，支持子字符串或通配符匹配 |
| `xc_list_tenants` | 显示已配置的租户、版本和更新可用性 |
该服务器还公开了 [MCP 资源](#mcp-resources) 以浏览 API 类别和资源类型，以及 [MCP 提示](#mcp-prompts) 以用于审计命名空间或部署负载均衡器等常见工作流程。
### 降低令牌使用量
API 密集型 MCP 工具的最大挑战是上下文膨胀。AI 看到的每个响应都会消耗令牌。该服务器在多个级别解决了这个问题：
- **模板代替模式。** 当您请求 HTTP 负载均衡器、源池、WAF 或证书的创建模式时，服务器返回一个紧凑的工作示例（~50 行），而不是完整的 OpenAPI 模式（~630 行）。这样可以减少 85% 的令牌。如果您需要真正的模式，请传递 `include_full_schema: true`。
- **服务器端证书生成。** `xc_create_cert` 生成证书，对私钥进行盲加密，并创建 XC 对象，而不会有任何 PEM 内容进入对话。
- **响应过滤。** `xc_call_api` 上的 `response_filter` 在 AI 接收到大型 API 响应之前，从中提取特定的字段。对于返回 50KB+ 的配额端点非常有用。
- **智能默认值。** 服务器在创建 HTTPS 负载均衡器时自动设置 `port: 443` 和 `non_default_loadbalancer`，这样 AI 就不需要查找这些要求。
- **紧凑输出。** 所有 JSON 都序列化为没有空格的格式。工具描述故意简洁。发现输出为每个操作一行。
## 先决条件
- **F5 分布式云** 账户
- **API 令牌**（在 XC 控制台 > 管理 > 个人管理 > 凭证 > “添加凭证” > 选择“API 令牌”创建），或 **API 证书** P12 文件（在同一菜单中，选择“API 证书”），如果您更喜欢使用 mTLS
- 您的 **租户 URL**，例如 `https://your-tenant.console.ves.volterra.io`（在您登录到 XC 控制台时在浏览器中可见）
- **Docker**（推荐）或 **Node.js 20+**
## 传输模式
| 模式 | 通过 | 使用者 | 工作原理 |
|------|---------|---------|--------------|
| **stdio**（默认） | `MCP_TRANSPORT=stdio` 或未设置 | Claude Code | 客户端将服务器作为子进程启动，通过 stdin/stdout 进行通信 |
| **http** | `MCP_TRANSPORT=http` | ChatGPT、Bifrost、远程客户端 | 服务器监听 HTTP（默认端口 3000）。客户端连接到 **`/mcp`**。指向 `/` 返回 404。 |
---
## 设置：Claude Code
Claude Code 使用 stdio 模式。它启动服务器作为子进程。无需端口，无需后台进程。
### 选项 A：Docker（推荐）
```bash
# 1. 使用 GitHub PAT（具有 read:packages 作用域）进行身份验证（一次性）
echo "YOUR_GITHUB_PAT" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin
# 2. 拉取镜像
docker pull ghcr.io/mikej81/xc-mcp:latest
# 3. 注册到 Claude Code
claude mcp add-json f5-xc --scope user '{"type":"stdio","command":"docker","args":["run","--rm","-i","-e","XC_API_TOKEN","-e","XC_TENANT_URL","ghcr.io/mikej81/xc-mcp:latest"],"env":{"XC_API_TOKEN":"YOUR_API_TOKEN_HERE","XC_TENANT_URL":"https://your-tenant.console.ves.volterra.io"}}'
# 4. 验证：启动 Claude Code 并输入 /mcp
```
用实际值替换 `YOUR_API_TOKEN_HERE` 和租户 URL。`--scope user` 使服务器在所有 Claude Code 会话中都可用。
### 选项 A（替代）：在本地构建 Docker 镜像
```bash
git clone https://github.com/Mikej81/xc-mcp.git
cd xc-mcp
docker build -t f5-xc-mcp .
claude mcp add-json f5-xc --scope user '{"type":"stdio","command":"docker","args":["run","--rm","-i","-e","XC_API_TOKEN","-e","XC_TENANT_URL","f5-xc-mcp"],"env":{"XC_API_TOKEN":"YOUR_API_TOKEN_HERE","XC_TENANT_URL":"https://your-tenant.console.ves.volterra.io"}}'
```
### 选项 B：Node.js
```bash
npm install && npm run build
claude mcp add-json f5-xc --scope user '{"type":"stdio","command":"node","args":["/absolute/path/to/xc-mcp/dist/src/index.js"],"env":{"XC_API_TOKEN":"YOUR_API_TOKEN_HERE","XC_TENANT_URL":"https://your-tenant.console.ves.volterra.io"}}'
```
### 选项 C：项目范围配置
在项目根目录中添加一个 `.mcp.json`，以便整个团队获得相同的设置：
```json
{
"mcpServers": {
"f5-xc": {
"type": "stdio",
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "XC_API_TOKEN", "-e", "XC_TENANT_URL", "ghcr.io/mikej81/xc-mcp:latest"],
"env": {
"XC_API_TOKEN": "YOUR_API_TOKEN_HERE",
"XC_TENANT_URL": "https://your-tenant.console.ves.volterra.io"
}
}
}
}
```
### 管理服务器
```bash
claude mcp list # 查看所有已注册的服务器
claude mcp remove f5-xc # 删除此服务器
/mcp # 在 Claude Code 中查看状态
```
---
## 设置：ChatGPT
ChatGPT 通过 HTTP 连接。您需要将服务器运行在 ChatGPT 可以访问的位置。
### 启动服务器
**Docker：**
```bash
docker run --rm -p 3000:3000 \
-e MCP_TRANSPORT=http \
-e MCP_HTTP_PORT=3000 \
-e XC_API_TOKEN=YOUR_API_TOKEN_HERE \
-e XC_TENANT_URL=https://your-tenant.console.ves.volterra.io \
ghcr.io/mikej81/xc-mcp:latest
```
**Node.js：**
```bash
MCP_TRANSPORT=http XC_API_TOKEN=your-token XC_TENANT_URL=https://your-tenant.console.ves.volterra.io node dist/src/index.js
```
### 公开访问
ChatGPT 需要一个公开的 HTTPS URL。对于开发，使用隧道：
```bash
ngrok http 3000
# 或
cloudflared tunnel --url http://localhost:3000
```
### 在 ChatGPT 中连接
1. **设置** > **连接器** > **高级设置** > 启用 **开发者模式**
2. **设置** > **连接器** > **创建**
3. 输入您的隧道 URL + `/mcp` 作为连接器 URL
4. 保存并开始聊天
### Docker Compose
```yaml
services:
f5-xc-mcp:
image: ghcr.io/mikej81/xc-mcp:latest
ports:
- "3000:3000"
environment:
MCP_TRANSPORT: http
MCP_HTTP_PORT: 3000
XC_API_TOKEN: ${XC_API_TOKEN}
XC_TENANT_URL: ${XC_TENANT_URL}
restart: unless-stopped
```
```bash
echo 'XC_API_TOKEN=your-token' >> .env
echo 'XC_TENANT_URL=https://your-tenant.console.ves.volterra.io' >> .env
docker compose up -d
```
---
## 多租户
使用命名环境变量配置多个租户：
```bash
XC_TENANT_PROD_URL=https://prod.console.ves.volterra.io
XC_TENANT_PROD_TOKEN=your-prod-api-token
XC_TENANT_DEV_URL=https://dev.console.ves.volterra.io
XC_TENANT_DEV_TOKEN=your-dev-api-token
```
命名约定为 `XC_TENANT_<NAME>_URL` 和 `XC_TENANT_<NAME>_TOKEN`。当仅配置一个租户时，`tenant` 参数是可选的。当配置多个租户时，您需要为每个调用指定使用哪个租户。
对于大多数操作都针对一个租户的多租户部署，设置 `XC_DEFAULT_TENANT=prod`（或其他配置的名称），这样调用者可以为该租户省略 `tenant` 参数。这与现有的 `XC_DEFAULT_NAMESPACE` 行为类似。
```bash
claude mcp add-json f5-xc --scope user '{"type":"stdio","command":"docker","args":["run","--rm","-i","-e","XC_TENANT_PROD_URL","-e","XC_TENANT_PROD_TOKEN","-e","XC_TENANT_DEV_URL","-e","XC_TENANT_DEV_TOKEN","ghcr.io/mikej81/xc-mcp:latest"],"env":{"XC_TENANT_PROD_URL":"https://prod.console.ves.volterra.io","XC_TENANT_PROD_TOKEN":"abc123","XC_TENANT_DEV_URL":"https://dev.console.ves.volterra.io","XC_TENANT_DEV_TOKEN":"def456"}}'
```
## 默认命名空间
大多数 XC 资源都位于命名空间中。设置一个默认值，这样您就不需要每次都指定它：
```bash
# 单租户
XC_DEFAULT_NAMESPACE=my-namespace
# 多租户（按租户）
XC_TENANT_PROD_DEFAULT_NAMESPACE=production
XC_TENANT_DEV_DEFAULT_NAMESPACE=dev-sandbox
```
显式命名空间始终具有优先级。如果两者都未设置，服务器会要求用户选择一个。
## HTTP 端点和安全性
HTTP 传输服务单个端点：`/mcp`。所有 MCP 流量都通过此路径：`POST` 用于客户端到服务器的消息，`GET` 用于 SSE 流式传输通道，`DELETE` 用于会话拆除。指向裸主机（`/`）的客户端返回 404。在配置 Bifrost、ChatGPT 连接器或其他 MCP HTTP 客户端时，连接器 URL 必须以 `/mcp` 结尾（例如：`https://xc-mcp.example.com/mcp`）。
当在公开的部署中部署 HTTP 传输（例如，在 F5 XC 公共负载均衡器后面）时，请同时设置 `MCP_AUTH_HEADER_NAME` 和 `MCP_AUTH_HEADER_VALUE`。如果没有它们，可以访问 `/mcp` 的任何内容都可以使用服务器。在本地开发中可以这样做，但在开放的互联网上绝不能这样做。
```bash
# 示例：在每个请求上需要 X-API-Key
MCP_AUTH_HEADER_NAME=X-API-Key
MCP_AUTH_HEADER_VALUE=<long-random-secret>
```
检查在正文解析之前运行，因此失败的请求永远不会创建会话。身份验证失败事件以 `warn` 级别记录，包含对等 IP 和预期的头部名称（绝不记录提供的值）。
为您的客户端（Bifrost、ChatGPT 连接器等）配置以在每个请求到 `/mcp` 时发送匹配的头部。
### 客户端兼容性（MCP 任务 RFC）
MCP SDK 按照任务 RFC 的规定为每个工具标记 `execution.taskSupport: "forbidden"`。一些当前客户端（Bifrost、某些 OpenWebUI 版本）会误读该字段并跳过该工具。服务器会检测未在 `initialize` 期间宣传 `capabilities.tasks` 的客户端，并仅为这些会话从 `tools/list` 响应中剥离该字段。任务 RFC 感知的客户端仍然会收到完整的描述符。不需要进行任何配置。
---
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `XC_API_TOKEN` | 是* | -- | API 令牌（单租户模式） |
| `XC_API_P12_PATH` | 是* | -- | P12（PKCS#12）证书路径，用于 mTLS 身份验证（单租户模式）。`XC_API_TOKEN` 的替代方案。 |
| `XC_API_P12_PASSWORD` | 是* | -- | P12 文件的密码。`XC_API_P12_PATH` 需要此项。 |
| `XC_TENANT_URL` | 是* | -- | 租户 URL（单租户模式） |
| `XC_TENANT_<NAME>_URL` | 是* | -- | 命名租户 URL（多租户模式） |
| `XC_TENANT_<NAME>_TOKEN` | 是* | -- | 命名租户令牌（多租户模式） |
| `XC_TENANT_<NAME>_P12_PATH` | 是* | -- | 命名租户 P12 路径。`_<TOKEN>` 的替代方案。 |
| `XC_TENANT_<NAME>_P12_PASSWORD` | 是* | -- | `_P12_PATH` 的密码。当设置 `_P12_PATH` 时需要此项。 |
| `XC_DEFAULT_NAMESPACE` | 否 | -- | 默认命名空间（单租户模式） |
| `XC_TENANT_<NAME>_DEFAULT_NAMESPACE` | 否 | -- | 默认命名空间（多租户模式） |
| `XC_DEFAULT_TENANT` | 否 | -- | 当省略 `tenant` 且配置了多个租户时使用的租户名称。必须与 `XC_TENANT_<NAME>_URL` 名称之一匹配（不区分大小写）。 |
| `MCP_TRANSPORT` | 否 | `stdio` | 传输模式：`stdio` 或 `http` |
| `MCP_HTTP_PORT` | 否 | `3000` | HTTP 端口（仅当 `MCP_TRANSPORT=http` 时） |
| `MCP_AUTH_HEADER_NAME` | 否* | -- | 每个 `/mcp` HTTP 请求所需的身份验证头名称（例如 `X-API-Key`）。对于任何公开部署，建议使用但强烈建议使用。 |
| `MCP_AUTH_HEADER_VALUE` | 否* | -- | 预期身份验证头的值。进行恒定时间比较。注入秘密存储；绝不烘焙到镜像中。 |
| `MCP_LOG_LEVEL` | 否 | `info` | 日志级别：`debug` \| `info` \| `warn` \| `error`。在 `debug` 级别，每个访问日志行都包含解析的 JSON-RPC 请求正文（上限为 4 KB 字符）。绝不会记录响应正文。 |
*每个租户，选择一种身份验证方法：令牌（`*_TOKEN`）或 P12 证书（`*_P12_PATH` 加 `*_P12_PASSWORD`）。同时设置两者会阻止服务器启动。`MCP_AUTH_HEADER_NAME` 和 `MCP_AUTH_HEADER_VALUE` 的规则相同：两者都设置或两者都不设置。
### P12（mTLS）身份验证
API 令牌是默认的。如果您的环境需要基于证书的身份验证，请使用 `XC_API_P12_PATH` 指向 P12 文件及其密码，服务器将为每个 API 调用使用 mTLS 进行身份验证。P12 在启动时加载，因此错误的路径或错误的密码会在服务器接收任何请求之前快速失败。在 mTLS 下，不会发送 `Authorization` 头。证书是身份验证。
在 Docker 中运行？将 P12 绑定到容器中并传入容器路径：
```bash
docker run --rm -i \
-v /host/path/cert.p12:/secrets/cert.p12:ro \
-e XC_API_P12_PATH=/secrets/cert.p12 \
-e XC_API_P12_PASSWORD=your-p12-password \
-e XC_TENANT_URL=https://your-tenant.console.ves.volterra.io \
ghcr.io/mikej81/xc-mcp:latest
```
---
## MCP 资源
服务器公开了 MCP 客户端可以浏览的只读资源：
| 资源 URI | 描述 |
|-------------|-------------|
| `xc://api/categories` | 所有 18 个 API 类别及其操作计数 |
| `xc://api/resource-types` | 8 种具有内置创建模板的资源类型 |
| `xc://tenants/{name}` | 特定租户的配置详细信息 |
## MCP 提示
用于常见工作流程的预建提示模板：
| 提示 | 描述 |
|--------|-------------|
| `audit-namespace` | 审计命名空间中的所有资源，查找孤儿对象 |
| `deploy-https-lb` | 从几个参数部署具有证书、源池和 WAF 的负载均衡器 |
| `compare-tenants` | 比较两个租户之间的资源 |
| `inventory` | 命名空间的完整资源计数表 |
---
## 示例交互
连接后，只需用纯语言询问：
**库存和检查：**
- *"列出我的 XC 租户中的所有命名空间"*
- *"显示默认命名空间中的所有 HTTP 负载均衡器"*
- *"获取名为 prod-web 的负载均衡器的完整配置"*
**审计：**
- *"哪些源池没有被任何负载均衡器使用？"*
- *"在我的租户中显示孤儿对象"*
**创建资源：**
- *"为应用.example.com 创建具有 WAF 和源地址 10.0.0.1:8080 的 HTTPS 负载均衡器"*
- *"为 api.example.com 生成自签名证书"*
**多租户：**
- *"比较生产和开发环境之间的负载均衡器"*
## API 类别
服务器索引了 1764 个操作，跨越这些类别：
| 类别 | 描述 |
|----------|-------------|
| AI/ML | AI 助手和 ML 数据端点 |
| API 安全 | API 定义、发现、组、端点 |
| 计费 | 使用情况和计费 |
| Bot 防护 | 机器人防御和客户端防御 |
| 证书 | 证书和 CA 列表管理 |
| 云站点 | AWS VPC/TGW、Azure VNET、GCP VPC、AppStack 站点 |
| DDoS 防护 | DDoS 缓解和快速 ACL |
| DNS | DNS 区域、域名、负载均衡器 |
| IAM | 用户、角色、API 凭证、租户 |
| 负载均衡 | HTTP/TCP 负载均衡器、源池、健康检查 |
| 监控 | 警报、日志、审计 |
| 网络 | 虚拟网络、网络策略、BGP、隧道 |
| 操作 | 存储对象、秘密、Terraform、内省 |
| 安全 | 应用程序防火墙、服务策略、速率限制器 |
| 支持 | 支持票 |
## 开发
```bash
npm install # 安装依赖
npm run download-specs # 从 F5 下载 268 个 OpenAPI 规范
npm run build:index # 将规范解析为可搜索的索引
npm run build:ts # 编译 TypeScript
npm run build # 以上所有步骤
npm test # 运行 317 个单元测试
npm run test:watch # 在监视模式下运行测试
```
### 实物租户烟雾测试
`scripts/smoke-test.ts` 在真正的 XC 租户上测试了四个 0.2.0 工具（`xc_query_access_logs`、`xc_lb_wait_ready`、`xc_diff_resource`、`xc_patch_resource`）。读取与服务器相同的环境变量。
```bash
# 对现有 HTTP 负载均衡器进行只读检查
XC_API_TOKEN=... XC_TENANT_URL=... \
npx tsx scripts/smoke-test.ts <namespace> <lb_name>
# 包含补丁路径（添加临时标签，验证它，删除它）
XC_API_TOKEN=... XC_TENANT_URL=... \
npx tsx scripts/smoke-test.ts <namespace> <lb_name> --allow-mutations
# 多租户
npx tsx scripts/smoke-test.ts <namespace> <lb_name> --tenant prod
```
## 架构
在构建时，解析 268 个 OpenAPI 规范文件以创建具有 O(1) 操作查找的可搜索索引。在运行时，按需从原始规范文件解析模式，具有可配置的深度和可选的摘要。常见资源类型返回预建的模板而不是完整的模式。
所有 API 调用都通过一个共享的 HTTP 客户端，该客户端处理身份验证头、请求超时（30 秒）和响应截断（`xc_call_api` 为 50KB，不限制列表工具执行自己的提取）。非 2xx 响应带有 `error_category` 字段 (`auth_failure`、`permission_denied`、`not_found`、`timeout`、`config_conflict`、`rate_limited`、`validation_error`、`backend_unavailable`、`server_error`），这样调用者可以在不解析正文的情况下分支到类别。私有密钥始终使用租户的 RSA 公钥进行盲加密后传输。
服务器作为 stdio 子进程运行（适用于 Claude Code）或带有会话管理和 30 分钟空闲清理的 HTTP 服务器（适用于 ChatGPT）。Docker 镜像以非 root 用户身份运行，带有健康检查。
启动时，服务器检查 GitHub 的新版本并记录可用更新的通知。版本也在 `xc_list_tenants` 输出中显示。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器