Name: 分布式云API服务器
Author: robinmordasiewicz

使用说明

F5分布式云API MCP服务器

一个MCP（模型上下文协议）服务器，向AI助手公开F5分布式云API。通过Claude、VS Code和其他MCP兼容工具。

特性

1500+API工具 -全面覆盖23个丰富域的F5XC API操作
基于域的文档 -按域组织的工具具有智能2级和三级分层导航
双模式操作 -在无身份验证（文档模式）和有身份验证（执行模式）的情况下工作
CURL示例 -API文档，包含针对已验证和未验证模式的curl命令
多种身份验证方法 -API令牌和P12证书（mTLS）支持
URL规范化 -自动处理各种F5XC URL格式
预富集规格 -使用优化的OpenAPI 3.0.3规范和域元数据
服务器应用默认值 -区分用户必填字段和服务器默认字段（v2.0.28+）
配额意识 -飞行前配额验证可防止资源创建失败（v2.1.0+）

配额意识

MCP服务器在执行创建之前会自动检查资源配额的可用性操作，防止因配额限制而导致的失败。

特性

飞行前验证 -在API调用之前检查配额
自动拦截 -阻止在配额为100%时创建
警报系统 -当配额使用率达到80-99%时发出警告
缓存 -5分钟缓存可减少API调用
每个命名空间跟踪 -按命名空间检查配额限制
可配置阈值 -自定义警告和阻止级别

配额MCP工具

三个MCP工具提供配额使用情况的可见性：

f5xc-api-get-quota-status

// Get quota status for a specific resource type
{
  "namespace": "production",
  "resourceType": "healthcheck"
}

// Output:
// Quota Status for healthcheck
// Namespace: production
// Current Usage: 95/100 (95%)
// Remaining: 5
// Status: ⚠️ Approaching limit

f5xc-api-list-namespace-quotas

// List all quota limits for a namespace
{
  "namespace": "production",
  "showOnlyLimited": false
}

// Output: Table of all resource quotas with usage

f5xc-api-clear-quota-cache

// Clear quota cache to force fresh API queries
{
  "namespace": "production"  // optional
}

配额阈值

基于配额使用的资源创建行为：

区域	使用	行为
🟢 绿色	0-79%	允许创建，无警告
🟡 黄色	80-99%	允许创建，记录警告
🔴 红色	100%+	创建被阻止有错误

错误消息示例

当达到配额限制时：

ERROR: Resource quota limit reached

Resource Type: healthcheck
Namespace: production
Current Usage: 100/100 (100%)
Status: ❌ At limit - cannot create additional resources

Action Required:
1. Delete unused healthcheck resources in the 'production' namespace
2. Request quota increase from F5 XC support
3. Use a different namespace with available quota

配置

通过环境变量控制配额检查行为：

# Enable/disable quota checking (default: true)
export F5XC_QUOTA_CHECK_ENABLED=true

# Cache TTL in seconds (default: 300 = 5 minutes)
export F5XC_QUOTA_CACHE_TTL=300

# Threshold percentages (defaults: 79, 99, 100)
export F5XC_QUOTA_GREEN_THRESHOLD=79
export F5XC_QUOTA_YELLOW_THRESHOLD=99
export F5XC_QUOTA_RED_THRESHOLD=100

服务器应用默认值

F5 XC API规范（v2.0.28+）通过增强的元数据区分了现场需求：

现场需求类型

用户必填字段 (x-f5xc-required-for.create: true)
- 必须在创建时由用户提供
- 验证返回错误如果丢失
- 例子： metadata.name, http_health_check.path
服务器默认字段 (x-f5xc-server-default: true)
- 创建时可选
- 如果省略，服务器将应用默认值
- 验证返回警告带有默认值信息
- 例子： healthcheck.jitter_percent 默认为 0
推荐值 (x-f5xc-recommended-value) - v2.0.32+
- 与F5 XC web UI默认值匹配的建议值
- 提供指导，但不强制执行特定值
- 例子： spec.timeout 建议值为 3
架构必填字段 (x-ves-required: true)
- API处理请求时必须具有非零值
- 可以是用户提供的，也可以是服务器默认的

健康检查配置（v2.0.32+）

服务器应用默认值

字段	默认值
`spec.jitter_percent`	`0`
`spec.http_health_check.use_http2`	`false`
`spec.http_health_check.headers`	`{}`
`spec.http_health_check.expected_status_codes`	`[]` （接受200-299）
`spec.http_health_check.request_headers_to_remove`	`[]`

示例：最小健康检查配置

{
  "metadata": {
    "name": "example-hc",
    "namespace": "default"
  },
  "spec": {
    "timeout": 3,
    "interval": 15,
    "unhealthy_threshold": 1,
    "healthy_threshold": 3,
    "http_health_check": {
      "use_origin_server_name": {},
      "path": "/health"
    }
  }
}

服务器自动应用：

spec.jitter_percent → 0
spec.http_health_check.use_http2 → false
spec.http_health_check.headers → {}
spec.http_health_check.expected_status_codes → []

源池配置（v2.0.3+）

服务器应用默认值

字段	服务器默认值	UI默认值	注释
`spec.loadbalancer_algorithm`	`ROUND_ROBIN`	`LB_OVERRIDE`	⚠️ 不一致！
`spec.endpoint_selection`	`DISTRIBUTED`	-	分布式选择
TLS到源(`spec.no_tls`)	禁用	-	默认情况下没有TLS
连接超时	2000毫秒	-	2秒超时
HTTP空闲超时	300000毫秒	-	5分钟超时
断路器	默认启用	-	自动启用
异常检测	已禁用	-	必须明确启用
HTTP协议	自动协商	-	`auto_http_config`
代理协议	已禁用	-	必须明确启用

⚠️ 关键UI与服务器差异： web控制台预先选择 LB_OVERRIDE 为了负载均衡器算法，但服务器应用 ROUND_ROBIN 当该字段被省略时。这会在UI创建的配置和API创建的配置之间产生行为不匹配。

字段模式之一（互斥）

源池使用互斥字段组，其中只应指定一个选项：

字段组	选项	目的
港口	`port`	`automatic_port`
TLS	`no_tls`	`use_tls`
断路器	`default_circuit_breaker`	`disable_circuit_breaker`
HTTP协议	`auto_http_config`	`http1_config`
健康检查端口	`same_as_endpoint_port`	`health_check_port`

必填字段

源池配置必须包括：

metadata.name -唯一标识符
metadata.namespace -目标命名空间
至少一个 spec.origin_servers 进入
显式端口（1-65535范围，通过 port, automatic_port，或 lb_port)

示例：最小源池配置

{
  "metadata": {
    "name": "example-origin-pool",
    "namespace": "default"
  },
  "spec": {
    "origin_servers": [
      {
        "public_ip": {
          "ip": "192.0.2.1"
        }
      }
    ],
    "port": 443,
    "use_tls": {
      "use_host_header_as_sni": {}
    }
  }
}

服务器自动应用：

spec.loadbalancer_algorithm → ROUND_ROBIN
spec.endpoint_selection → DISTRIBUTED
连接超时→ 2000 ms
HTTP空闲超时→ 300000 ms
断路器→ 默认启用
HTTP协议→ 自动协商

验证行为

验证参数时：

缺少用户必填字段 → ❌ 错误：“缺少必填字段：metadata.name”
缺少服务器默认字段 → ⚠️ 警告：“字段'jitter_percent'将默认为0”
推荐值 → 📋 信息：返回 recommendedValues 用于指导

快速开始

使用npx（推荐）

npx @robinmordasiewicz/f5xc-api-mcp

使用npm

npm install -g @robinmordasiewicz/f5xc-api-mcp
f5xc-api-mcp

使用Docker

docker run -i --rm ghcr.io/robinmordasiewicz/f5xc-api-mcp

配置

克劳德桌面版

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "f5xc-api": {
      "command": "npx",
      "args": ["@robinmordasiewicz/f5xc-api-mcp"],
      "env": {
        "F5XC_API_URL": "https://your-tenant.console.ves.volterra.io",
        "F5XC_API_TOKEN": "your-api-token"
      }
    }
  }
}

克劳德代码CLI

claude mcp add f5xc-api -- npx @robinmordasiewicz/f5xc-api-mcp

VS代码（带Cline/Continue）

添加到MCP设置中：

{
  "mcpServers": {
    "f5xc-api": {
      "command": "npx",
      "args": ["@robinmordasiewicz/f5xc-api-mcp"]
    }
  }
}

开源代码

增添 opencode.json （项目根或 ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "f5xc-api": {
      "type": "local",
      "command": ["npx", "@robinmordasiewicz/f5xc-api-mcp"],
      "environment": {
        "F5XC_API_URL": "https://your-tenant.console.ves.volterra.io",
        "F5XC_API_TOKEN": "your-api-token"
      }
    }
  }
}

注： OpenCode使用不同的模式： "mcp" 密钥（不是 "mcpServers")，基于阵列 "command", "environment" （不是 "env")，并要求 "type": "local".

环境变量

变量	必填	描述
`F5XC_API_URL`	用于执行	租户URL（自动规范化）
`F5XC_API_TOKEN`	对于来自XC控制台的令牌身份验证	API令牌
`F5XC_P12_BUNDLE`	用于证书认证	P12证书包的路径
`F5XC_P12_PASSWORD`	用于证书认证	P12证书的密码
`F5XC_PROFILE`	否	要使用的配置文件名称（默认：配置中的活动配置文件）
`F5XC_TLS_INSECURE`	否	禁用SSL验证（仅限暂存，设置为 `true`)
`F5XC_CA_BUNDLE`	否	自定义CA证书包的路径
`F5XC_QUOTA_CHECK_ENABLED`	否	启用配额验证（默认值： `true`)
`F5XC_QUOTA_CACHE_TTL`	否	配额缓存TTL（秒）（默认值： `300`)
`F5XC_QUOTA_GREEN_THRESHOLD`	否	绿色区域百分比（默认值： `79`)
`F5XC_QUOTA_YELLOW_THRESHOLD`	否	黄色区域百分比（默认值： `99`)
`F5XC_QUOTA_RED_THRESHOLD`	否	红色区域百分比（默认值： `100`)
`LOG_LEVEL`	否	记录详细信息（调试、信息、警告、错误）

基于配置文件的配置

使用存储在中的命名配置文件管理多个F5XC租户凭据 ~/.config/f5xc/profiles/.

通过MCP工具进行配置文件管理

使用 f5xc-api-configure-auth MCP工具通过您的AI助手：

动作	描述
`status`	检查当前身份验证状态和活动配置文件
`configure`	将新凭据保存到命名配置文件
`list-profiles`	列出所有可用配置文件
`set-active`	切换活动配置文件

交互示例：

"Check my F5XC authentication status"
→ Uses f5xc-api-configure-auth with action: status

"Configure a new F5XC profile called production"
→ Uses f5xc-api-configure-auth with action: configure

"Switch to the staging profile"
→ Uses f5xc-api-configure-auth with action: set-active

使用配置文件

# Use active profile (from ~/.config/f5xc/active_profile)
f5xc-api-mcp

# Use specific profile via environment variable
F5XC_PROFILE=staging f5xc-api-mcp

# Override profile credentials with environment variables
F5XC_PROFILE=production F5XC_API_TOKEN=temporary-token f5xc-api-mcp

配置目录结构

配置文件存储在 ~/.config/f5xc/ （XDG基本目录兼容）：

~/.config/f5xc/
├── active_profile       # Contains the name of the active profile
└── profiles/
    ├── production.json  # Individual profile files
    └── staging.json

配置文件格式 (~/.config/f5xc/profiles/production.json):

{
  "name": "production",
  "tenant_url": "https://mytenant.console.ves.volterra.io",
  "api_token": "your-api-token",
  "created_at": "2025-12-21T10:00:00Z",
  "last_used_at": "2025-12-21T15:30:00Z"
}

凭证优先级

凭据按以下顺序加载（从高到低优先级）：

环境变量 - F5XC_API_URL, F5XC_API_TOKEN等等。
活动配置文件 -选择人 F5XC_PROFILE 或从 ~/.config/f5xc/active_profile
文档模式 -无凭据（只读API文档）

环境变量始终覆盖配置文件设置，启用临时覆盖。

向后兼容

使用环境变量的现有设置继续工作不变：

export F5XC_API_URL=https://mytenant.console.ves.volterra.io
export F5XC_API_TOKEN=your-api-token
f5xc-api-mcp

无需更改-配置文件是可选的。

双模式操作

文档模式（无身份验证）

当没有提供凭据时，服务器会提供：

OpenAPI规范文档
API操作说明
参数描述和验证
CURL命令示例
JSON请求模板

此模式是探索API和了解可用操作的理想模式。

执行模式（带身份验证）

提供凭据后，服务器还会：

对租户执行实际的API调用
列出并检索资源
创建、更新和删除配置
返回实时资源状态

可用工具

工具遵循命名模式： f5xc-api-{domain}-{resource}-{operation}

域名（共23个）

域	路径计数	结构	描述
AI智能	11	2级	AI助手，BFDP
API安全	45	2级	API发现、保护、定义
BIG-IP集成	28	2级	BIG-IP虚拟服务器、iRules、APM
账单	19	2级	发票、付款方式、订阅
CDN	31	2级	CDN负载均衡器、缓存规则
DNS	42	2级	DNS区域、DNS负载平衡器、DNS池
基础设施	134	3级	AWS/Azure/GCP VPC站点、客户边缘站点
基础设施保护	72	2级	DDoS保护、防火墙规则
集成	26	2级	第三方应用程序、票务系统
身份	137	3级	身份验证、用户、角色、RBAC
负载平衡	89	2级	HTTP/TCP/UDP负载平衡器、源池、转发代理
监控和可观察性	235	3级	警报、日志、综合监控器、指标
NGINX集成	34	2级	NGINX一个实例、服务器、服务发现
网络	220	3级	网络连接器、防火墙、接口、策略
操作	22	2级	调试、DHCP、ping、跟踪路由
区域边缘配置	18	2级	区域边缘设置、策略
安全	210	3级	服务策略、WAF、恶意用户缓解
服务网格	31	2级	虚拟K8s、工作负载、K8s集群
形状安全（机器人防御）	124	3级	机器人防御，客户端防御
系统配置	23	2级	命名空间、证书、凭据
租户管理	28	2级	多租户管理，配置文件
VPN	20	2级	VPN隧道、IKE配置文件
工作流和自动化	15	2级	工作流模板、自动化

示例工具

f5xc-api-virtual-http-loadbalancer-create
f5xc-api-virtual-origin-pool-list
f5xc-api-cemanagement-network-interface-get
f5xc-api-server-info

文档结构

文档站点是根据丰富的OpenAPI规范自动生成的并通过智能分层导航按域组织：

两级导航（小域<50条路径）

小域名使用简单的2级结构：域名→ 资源

docs/tools/
├── vpn/
│   ├── ipsec-gateway.md
│   └── vpn-connection.md
├── cdn/
│   ├── cdn-loadbalancer.md
│   └── cdn-pool.md

例子： VPN工具

三级导航（大域≥50条路径）

大型域使用3级结构：域→ 类别（按OpenAPI标签）→ 资源

docs/tools/
├── observability/
│   ├── alerts-events/
│   │   ├── alert-policy.md
│   │   └── event-manager.md
│   ├── logging/
│   │   ├── access-log.md
│   │   └── audit-log.md
│   └── metrics-statistics/
│       └── metric-collector.md

使用3级导航的大型域（>50条路径）：

监测和观测（235条路径）
网络（220条路径）
安全（210条路径）
基础设施（134条路径）
身份（137条路径）
形状安全（124条路径）

自动生成

文档由构建系统自动生成：

# Generate/regenerate documentation
npm run generate-docs

# Build documentation site
mkdocs build

# Preview site locally
mkdocs serve

发电机自动：

将域标题从snake_case转换为显示格式（例如。， load_balancer → “负载平衡”）
更新 mkdocs.yml 无需手动更改的导航
创建带有API操作详细信息和示例的降价文件
基于OpenAPI操作标签对大型域进行细分
保持一致的目录结构和命名约定

工作流提示

服务器包括来自上游丰富规范的指导性工作流程提示：

deploy_http_loadbalancer -使用后端源池创建完全配置的HTTP负载平衡器
deploy_https_loadbalancer -使用SSL/TLS终止创建HTTPS负载平衡器
enable_waf_protection -将web应用程序防火墙添加到现有负载平衡器
configure_origin_pool -使用运行状况检查设置后端服务器池
configure_dns_zone -设置具有记录的权威DNS区域
enable_cdn_distribution -配置CDN进行内容交付
register_site -注册并配置CE站点

资源URI

通过URI方案访问F5XC资源：

f5xc://{tenant}/{namespace}/{resource-type}/{name}

示例：

f5xc://mytenant/production/http_loadbalancer/my-app
f5xc://mytenant/system/namespace/default

URL规范化

服务器会自动规范各种URL格式：

用户输入	标准化
`tenant.volterra.us`	`tenant.console.ves.volterra.io/api`
`tenant.console.ves.volterra.io`	`tenant.console.ves.volterra.io/api`
`https://tenant.volterra.us/`	`https://tenant.console.ves.volterra.io/api`

SSL/TLS配置

暂存环境证书颁发

F5 XC暂存环境使用以下URL tenant.staging.console.ves.volterra.io，但是SSL 证书仅涵盖 *.console.ves.volterra.io。这会导致SSL验证失败，因为通配符只匹配单个子域级别，而不是两个级别(tenant.staging).

错误示例：

Hostname/IP does not match certificate's altnames:
Host: tenant.staging.console.ves.volterra.io
Cert covers: DNS:*.console.ves.volterra.io, DNS:console.ves.volterra.io

解决方案

选项1：自定义CA捆绑包（推荐）

如果您的组织使用自定义CA：

export F5XC_CA_BUNDLE=/path/to/your/ca-bundle.crt

选项2：禁用验证（仅限开发）

警告：切勿在生产中使用！

export F5XC_TLS_INSECURE=true

SSL错误故障排除

错误	原因	解决方案
`Hostname/IP does not match certificate's altnames`	暂存URL不匹配	使用 `F5XC_TLS_INSECURE=true` 或自定义CA
`self signed certificate`	自定义CA不受信任	设置 `F5XC_CA_BUNDLE`
`certificate has expired`	证书已过期	请联系F5 XC管理员
`unable to verify the first certificate`	缺少中间体CA	将中间体添加到CA包中

安全最佳实践

更喜欢 F5XC_CA_BUNDLE 超过 F5XC_TLS_INSECURE：使用自定义CA包可以维护在信任组织的证书时进行证书验证。
联系F5支持：对于临时环境，请联系F5支持部门请求官方临时环境CA证书。这是最安全的长期解决方案。
切勿使用 F5XC_TLS_INSECURE=true 生产中：此设置禁用所有证书验证，只应用于开发和测试。
定期轮换凭据：API令牌和证书应根据您组织的安全策略。

发展

先决条件

Node.js 24+
npm 9+

设置

git clone https://github.com/robinmordasiewicz/f5xc-api-mcp.git
cd f5xc-api-mcp
npm install
npm run build

测试

npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

代码检查

npm run lint          # Check linting
npm run lint:fix      # Fix linting issues
npm run format        # Format code

文档

完整文档可在以下网址获得： https://robinmordasiewicz.github.io/f5xc-api-mcp

字段	推荐
`spec.timeout`	`3` 秒数
`spec.interval`	`15` 秒数
`spec.unhealthy_threshold`	`1` 失败
`spec.healthy_threshold`	`3` 成功
`spec.jitter_percent`	`30`%（生产）

使用说明

F5分布式云API MCP服务器

特性

配额意识

特性

配额MCP工具

配额阈值

错误消息示例

配置

服务器应用默认值

现场需求类型

健康检查配置（v2.0.32+）

服务器应用默认值

推荐值（Web UI默认值）

示例：最小健康检查配置

源池配置（v2.0.3+）

服务器应用默认值

字段模式之一（互斥）

必填字段

示例：最小源池配置

验证行为

快速开始

使用npx（推荐）

使用npm

使用Docker

配置

克劳德桌面版

克劳德代码CLI

VS代码（带Cline/Continue）

开源代码

环境变量

基于配置文件的配置

通过MCP工具进行配置文件管理

使用配置文件

配置目录结构

凭证优先级

向后兼容

双模式操作

文档模式（无身份验证）

执行模式（带身份验证）

可用工具

域名（共23个）

示例工具

文档结构

两级导航（小域<50条路径）

三级导航（大域≥50条路径）

自动生成

工作流提示

资源URI

URL规范化

SSL/TLS配置

暂存环境证书颁发

解决方案

选项1：自定义CA捆绑包（推荐）

选项2：禁用验证（仅限开发）

SSL错误故障排除

安全最佳实践

发展

先决条件

设置

测试

代码检查

文档

贡献

许可证

支持

相关 MCP

网页搜索MCP服务器

Zotero文献库搜索与阅读MCP服务

Prometheus 指标查询 MCP 服务器

SSH远程命令执行MCP服务器

电话服务 MCP 服务器

Meilisearch MCP 搜索服务器