F5xc API MCP

F5分布式云API MCP服务器

](https://www.npmjs.com/package/@robinmordasiewicz/f5xc-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
}

配额阈值

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

错误消息示例

当达到配额限制时：

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+）通过增强的元数据区分了现场需求：

现场需求类型

1. 用户必填字段 (x-f5xc-required-for.create: true)

- 必须在创建时由用户提供 - 验证返回 错误 如果丢失 - 例子： metadata.name, http_health_check.path

1. 服务器默认字段 (x-f5xc-server-default: true)

- 创建时可选 - 如果省略，服务器将应用默认值 - 验证返回 警告 带有默认值信息 - 例子： healthcheck.jitter_percent 默认为 0

1. 推荐值 (x-f5xc-recommended-value) - *v2.0.32+*

- 与F5 XC web UI默认值匹配的建议值 - 提供指导，但不强制执行特定值 - 例子： spec.timeout 建议值为 3

1. 架构必填字段 (x-ves-required: true)

- API处理请求时必须具有非零值 - 可以是用户提供的，也可以是服务器默认的

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

服务器应用默认值

推荐值（Web UI默认值）

示例：最小健康检查配置

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

字段模式之一（互斥）

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

必填字段

源池配置必须包括：

• 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租户凭据 ~/.config/f5xc/profiles/.

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

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

交互示例：

"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"
}

凭证优先级

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

1. 环境变量 - F5XC_API_URL, F5XC_API_TOKEN等等。
2. 活动配置文件 -选择人 F5XC_PROFILE 或从 ~/.config/f5xc/active_profile
3. 文档模式 -无凭据（只读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个）

示例工具

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

文档结构

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

两级导航（小域\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格式：

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错误故障排除

安全最佳实践

1. 更喜欢 F5XC_CA_BUNDLE 超过 F5XC_TLS_INSECURE：使用自定义CA包可以维护

在信任组织的证书时进行证书验证。

1. 联系F5支持：对于临时环境，请联系F5支持部门请求官方

临时环境CA证书。这是最安全的长期解决方案。

1. 切勿使用 F5XC_TLS_INSECURE=true 生产中：此设置禁用所有证书

验证，只应用于开发和测试。

1. 定期轮换凭据：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

文档

完整文档可在以下网址获得：

贡献

欢迎投稿！请阅读我们的投稿指南并提交pull请求。

许可证

MIT许可证-请参阅 许可证 了解详情。

支持

-