boc-mcp

博云 BeyondContainer 容器云平台的 MCP (Model Context Protocol) Server，让大语言模型可以通过统一的工具接口查询容器云平台的集群、节点、分区、工作负载、镜像版本、监控、安全扫描等资源。

特性

• 全能力查询覆盖：共 58 个工具，覆盖集群、节点、分区、应用/服务/任务、Pod、容器、Service、Secret、网络、服务树、监控、镜像版本、安全扫描 11 个领域。

• Streamable HTTP 传输：默认监听 0.0.0.0:8000，支持任意 MCP 客户端（Claude Desktop、Codex CLI、Cursor 等）通过 HTTP 接入。

• 自动登录 + Token 缓存：启动后自动完成博云三步登录流程（取 clientId → 换取 code → 换 token），Token 缓存在内存中；遇到 401 或平台返回 token 失效消息时自动重新登录并重试一次。

• HTTP 请求适配器：BocHttpClient 封装 aiohttp，统一注入 token/refreshToken/systemId Header、错误映射、超时、重试；通过 BocApiClient Protocol 解耦，单元测试使用 Fake 客户端零网络开销。

• Pydantic 模型 + 蛇形/驼峰兼容：所有领域模型自动驼峰别名，可直接反序列化博云接口返回。

• 结构化日志：JSON 生产模式，开发模式彩色输出，自动脱敏密码/Token。

• 健康检查：/healthz（存活）和 /healthz/ready（就绪）端点，就绪检查会验证 Token 是否可用。

• TDD 严格保证：测试覆盖率阈值 80%，所有工具注册、参数、描述均有测试兜底。

Related MCP server: k8scortex-mcp

快速开始

1. 安装依赖

项目使用 Python ≥ 3.12，推荐使用 uv 或 pip：

# 用 uv（推荐）
uv venv && uv pip install -e ".[dev]"

# 或用 pip
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate # Linux/macOS
pip install -e ".[dev]"

2. 配置

支持两种配置方式，环境变量优先级高于 YAML 文件：

• 环境变量（推荐生产使用）：BOC_BASE_URL、BOC_USERNAME、BOC_PASSWORD 等；

• YAML 配置文件：自动查找 ./config.yaml、~/.boc-mcp/config.yaml，或通过 BOC_CONFIG_FILE 指定。

最小配置（环境变量）：

export BOC_BASE_URL="https://your-boc-platform.com"
export BOC_USERNAME="admin"
export BOC_PASSWORD="your-password"
# 可选
export BOC_SYSTEM_ID="1"
export BOC_VERIFY_SSL="true"
export BOC_MCP__PORT="8000"

或使用 YAML：复制 config/config.example.yaml 为 config.yaml 并修改。

所有配置项：

3. 启动服务

python -m boc_mcp
# 或开发模式（彩色日志）
$env:BOC_DEV=1; python -m boc_mcp   # PowerShell
# BOC_DEV=1 python -m boc_mcp       # bash

服务启动后会：

1. 加载配置 → 2. 初始化日志 → 3. 登录博云平台获取 Token → 4. 监听 http://0.0.0.0:8000/mcp。

健康检查：GET http://localhost:8000/healthz（存活）、GET http://localhost:8000/healthz/ready（就绪，含 Token 检查）。

4. 接入 MCP 客户端

Claude Desktop / Codex CLI 配置示例（添加到各自的 MCP 配置文件）：

{
  "mcpServers": {
    "boc-mcp": {
      "url": "http://localhost:8000/mcp",
      "env": {
        "BOC_BASE_URL": "https://your-boc-platform.com",
        "BOC_USERNAME": "admin",
        "BOC_PASSWORD": "your-password"
      }
    }
  }
}

若需要 stdio 模式，可使用命令方式：

{
  "mcpServers": {
    "boc-mcp": {
      "command": "python",
      "args": ["-m", "boc_mcp"],
      "env": {
        "BOC_BASE_URL": "https://your-boc-platform.com",
        "BOC_USERNAME": "admin",
        "BOC_PASSWORD": "your-password"
      }
    }
  }
}

工具列表（58 个，全部只读）

所有工具以 boc_ 开头。列表类工具统一支持 page/page_size（最大 100）分页参数。

认证（auth）

• boc_auth_status — 查询登录状态、当前用户、Token 过期时间

• boc_auth_refresh — 强制重新登录博云平台

应用（application）

• boc_app_get — 按应用 ID 查询应用详情

• boc_app_list — 分页查询应用列表，可按集群/名称过滤

集群（cluster）

• boc_cluster_list — 集群列表（分页，关键字过滤）

• boc_cluster_all — 所有集群（不分页，简表）

• boc_cluster_base_info — 集群基本信息（类型/名称/版本过滤）

• boc_cluster_monitor — 指定集群监控信息

• boc_cluster_state — 指定集群运行状态

• boc_cluster_nodes — 集群下节点列表

• boc_cluster_partitions — 集群下分区列表

• boc_cluster_partition_resource — 指定 hostId 分区 CPU/内存资源使用

• boc_cluster_by_env — 指定租户下集群列表

• boc_cluster_available_partitions — 当前租户可用分区

服务树（service_tree）

• boc_service_tree — 服务树节点查询（支持父类型/父 ID/节点类型筛选）

安全扫描（scan）

• boc_scan_list_strategies — 安全扫描策略列表

• boc_scan_get_report — 扫描报告详情

• boc_scan_list_reports — 扫描报告列表

配置/密钥（config_secret）

• boc_secret_list — 指定集群/命名空间下 Secret 列表

网络（network）

• boc_network_list_by_name — 按名称/IP 查询网络分区

• boc_network_available — 可用（未分配）网络列表

• boc_network_by_env — 按租户查询网络列表

分区（partition）

• boc_partition_list — 分页查询分区列表

• boc_partition_get_default — 集群默认分区

• boc_partition_get_meta — 按条件查询分区元数据

• boc_partition_list_default — 默认分区列表（不分页）

• boc_partition_list_nodes — 分区节点列表

• boc_partition_list_all_hosts — 所有主机节点列表

• boc_partition_all_info — 主机全量信息（集群/租户/IP/名称过滤）

• boc_partition_detail — 分区详情

• boc_partition_list_available — 当前租户可用分区

监控（monitor）

• boc_monitor_get_project_status — 单个应用实时监控状态

• boc_monitor_batch_project — 批量项目监控数据

• boc_monitor_batch_project_status — 批量项目状态监控

• boc_monitor_get_app — 单个服务监控数据

• boc_monitor_batch_app — 批量应用监控数据

• boc_monitor_get_pod — Pod 监控数据

• boc_monitor_batch_container — 批量容器监控数据

• boc_monitor_batch_pod — 批量 Pod 监控数据

版本/镜像（version）

• boc_version_list — 版本列表

• boc_version_get_id_by_name — 按名称查版本 ID

• boc_version_list_image_groups — 版本镜像组列表

• boc_version_list_dispatched_clusters — 版本已发布集群列表

• boc_version_list_undispatched_clusters — 版本未发布集群列表

• boc_version_get_image_group — 镜像组信息

• boc_version_get_yaml — 指定 K8s 资源 YAML

工作负载（workload）

• boc_workload_project_list — 应用（Project）列表

• boc_workload_app_list — 应用+服务列表

• boc_workload_application_list — 服务/任务（Application）列表

• boc_workload_service_network — 指定服务下网络信息

• boc_workload_container_list — 容器列表

• boc_workload_pod_list — 实例（Pod）列表

• boc_workload_kubectl_pods — kubectl 可访问的 Pod 列表

• boc_workload_check_internal_service — 检查命名空间下内部服务是否存在

• boc_workload_get_internal_load — 内部负载详情

• boc_workload_list_internal_loads — 指定服务下内部负载列表

• boc_workload_internal_service_list — 内部负载列表（分页）

• boc_workload_internal_service_detail — 内部负载通用查询

架构

┌───────────── MCP Client (Claude/Codex/Cursor) ─────────────┐
                    │  Streamable HTTP (/mcp)
┌───────────────────▼────────────────────────────────────────┐
│  FastMCP (tool layer)                                      │
│   └─ @mcp.tool / @wrap_tool_errors                         │
├────────────────────────────────────────────────────────────┤
│  Service layer (11 domain services)                        │
│   ├─ auth / application / cluster / workload               │
│   ├─ partition / network / config_secret / service_tree    │
│   ├─ monitor / version / scan                              │
│   └─ Pydantic models + _parse_list() 分页统一解析            │
├────────────────────────────────────────────────────────────┤
│  Client layer                                              │
│   ├─ BocApiClient (Protocol)                               │
│   ├─ BocHttpClient (aiohttp 真实实现，注入 header/重试)      │
│   ├─ TokenManager (三步登录 + 内存缓存 + asyncio.Lock)      │
│   └─ paginate() 通用分页迭代器                              │
├────────────────────────────────────────────────────────────┤
│  Cross-cutting                                             │
│   ├─ middleware.wrap_tool_errors (BocMcpError → MCP 错误)   │
│   ├─ logging_setup (JSON/开发模式 + 敏感字段脱敏)            │
│   └─ health (liveness/readiness)                           │
└────────────────────────────────────────────────────────────┘

关键设计：

• 认证流程：博云三步登录 — GET /upmstreeapi/bocPortal/getMenus 提取 clientId → POST /upmstreeapi/login 换取 code → GET /upmstreeapi/accessToken 获取 token/refreshToken/expiredTime，之后每次请求在 Header 携带 token、refreshToken、systemId。

• Token 失效处理：业务请求返回 401 或匹配平台 token 失效消息时，调用 token_mgr.invalidate() 清空缓存并重走登录（clientId 已缓存），原请求自动重试一次。

• 两种响应信封：博云接口同时存在 {state,code,data,message,entity} 和 {success,currPageNum,pageSize,totalCount,pageCount,rows} 两种结构，BocHttpClient 与各 Service 的 _parse_list() 统一解析。

• 错误分层：BocMcpError 有明确子类（认证、网络、业务、配置），wrap_tool_errors 中间件将其转为 MCP JSON-RPC 标准错误码。

开发

# 运行单元测试（默认）
python -m pytest

# 运行全部测试含覆盖率阈值 80%
python -m pytest --cov=boc_mcp --cov-fail-under=80

# 运行 E2E 测试（需要启动服务）
python -m pytest -m e2e

# 代码检查
ruff check src tests
ruff format --check src tests
mypy src/boc_mcp

目录结构：

src/boc_mcp/
├── __main__.py           # python -m boc_mcp 入口
├── server.py             # create_app / run，MCP 装配
├── config.py             # 配置加载（env + yaml）
├── logging_setup.py      # 日志 + 敏感字段脱敏
├── middleware.py         # 错误转 MCP 错误
├── health.py             # /healthz, /healthz/ready
├── auth/
│   ├── models.py         # TokenSet
│   └── token_manager.py  # 三步登录 + 缓存 + 失效重登
├── client/
│   ├── boc_client.py     # BocApiClient Protocol + BocHttpClient
│   ├── errors.py         # BocMcpError 体系
│   └── pagination.py     # 通用分页 async generator
├── models/
│   └── common.py         # ListResult[T], ActionResult
└── services/
    ├── base.py           # BaseService (_get/_post/_list ...)
    ├── auth/ application/ cluster/ config_secret/
    ├── monitor/ network/ partition/ scan/
    ├── service_tree/ version/ workload/
    │   ├── models.py     # Pydantic 领域模型
    │   ├── service.py    # 业务逻辑
    │   └── tools.py      # @mcp.tool 注册

文档

• docs/usage-guide.md：安装、配置、启动、客户端接入、常见查询场景、排错指南

• docs/api-reference.md：全部 58 个工具的接口文档（参数、类型、必填、返回值）

• docs/test-cases.md：自动化测试索引 + 连接真实平台的手工测试用例 + CI 说明

• docs/api-inventory.md：接口清单（博云 API 路径与工具映射）

Kubernetes 部署

部署清单位于 \deploy/k8s/\，使用 kustomize 一键部署。详见 \deploy/k8s/README.md\。

\ash

1. 构建并推送镜像

docker build -t registry.your-company.com/boc-mcp/boc-mcp:0.1.0 . docker push registry.your-company.com/boc-mcp/boc-mcp:0.1.0

2. 修改 deploy/k8s/01-config.yaml 中的 BOC_BASE_URL 和账号密码

3. 一键部署

kubectl apply -k deploy/k8s ## Docker

docker build -t boc-mcp:0.1.0 .
docker run -d -p 8000:8000 \
  -e BOC_BASE_URL=https://your-boc-platform.com \
  -e BOC_USERNAME=admin \
  -e BOC_PASSWORD=your-password \
  --name boc-mcp boc-mcp:0.1.0

许可证

内部使用，遵循团队规范。