内容
# 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%，所有工具注册、参数、描述均有测试兜底。
## 快速开始
### 1. 安装依赖
项目使用 Python ≥ 3.12，推荐使用 `uv` 或 `pip`：
```bash
# 用 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` 指定。
最小配置（环境变量）：
```bash
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` 并修改。
所有配置项：
| 环境变量 | YAML 键 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `BOC_BASE_URL` | `base_url` | —（必填） | 博云平台根地址，不要带尾斜杠 |
| `BOC_USERNAME` | `username` | —（必填） | 登录用户名 |
| `BOC_PASSWORD` | `password` | —（必填） | 登录密码 |
| `BOC_SYSTEM_ID` | `system_id` | `"1"` | 业务系统 ID，默认 1 |
| `BOC_VERIFY_SSL` | `verify_ssl` | `true` | 是否校验 HTTPS 证书 |
| `BOC_REQUEST_TIMEOUT` | `request_timeout` | `30` | 单次 HTTP 请求超时（秒） |
| `BOC_MAX_RETRIES` | `max_retries` | `3` | 网络错误重试次数 |
| `BOC_LOG_LEVEL` | `log_level` | `"INFO"` | 日志级别（DEBUG/INFO/WARNING/ERROR） |
| `BOC_CONFIG_FILE` | — | — | 指定 YAML 配置文件路径 |
| `BOC_MCP__HOST` | `mcp.host` | `"0.0.0.0"` | MCP HTTP 监听地址 |
| `BOC_MCP__PORT` | `mcp.port` | `8000` | MCP HTTP 监听端口 |
### 3. 启动服务
```bash
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 配置文件）：
```json
{
"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 模式，可使用命令方式：
```json
{
"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 标准错误码。
## 开发
```bash
# 运行单元测试（默认）
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
```bash
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
```
## 许可证
内部使用，遵循团队规范。
