Content
# boc-mcp
BeyondContainer MCP (Model Context Protocol) Server, enabling large language models to query container cloud platform resources through a unified tool interface.
## Features
- **Full Capability Query Coverage**: 58 tools covering 11 domains: cluster, node, partition, application/service/task, pod, container, service, secret, network, service tree, monitoring, and security scanning.
- **Streamable HTTP Transmission**: Listens on `0.0.0.0:8000` by default, supporting any MCP client (Claude Desktop, Codex CLI, Cursor, etc.) to access via HTTP.
- **Automatic Login + Token Cache**: Automatically completes the three-step login process (obtain clientId → exchange code → exchange token) after startup, with token cached in memory; automatically re-logins and retries once when encountering 401 or platform token invalidation messages.
- **HTTP Request Adapter**: `BocHttpClient` encapsulates aiohttp, uniformly injecting `token`/`refreshToken`/`systemId` headers, error mapping, timeout, and retries; decoupled through `BocApiClient` protocol, with fake clients used for unit testing with zero network overhead.
- **Pydantic Model + Snake/Camel Compatibility**: All domain models automatically have camel case aliases, directly deserializable from BeyondContainer interface returns.
- **Structured Logging**: JSON production mode, color output in development mode, with automatic desensitization of passwords/tokens.
- **Health Check**: `/healthz` (liveness) and `/healthz/ready` (readiness) endpoints, with readiness check verifying token availability.
- **TDD Strict Guarantee**: Test coverage threshold of 80%, with all tool registrations, parameters, and descriptions covered by tests.
## Quick Start
### 1. Install Dependencies
The project uses Python ≥ 3.12, recommended to use `uv` or `pip`:
```bash
# Using uv (recommended)
uv venv && uv pip install -e ".[dev]"
# Or using pip
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
pip install -e ".[dev]"
```
### 2. Configuration
Supports two configuration methods, **environment variable priority higher than YAML file**:
- Environment variables (recommended for production use): `BOC_BASE_URL`, `BOC_USERNAME`, `BOC_PASSWORD`, etc.;
- YAML configuration file: automatically searches for `./config.yaml`, `~/.boc-mcp/config.yaml`, or specifies through `BOC_CONFIG_FILE`.
Minimum configuration (environment variables):
```bash
export BOC_BASE_URL="https://your-boc-platform.com"
export BOC_USERNAME="admin"
export BOC_PASSWORD="your-password"
# Optional
export BOC_SYSTEM_ID="1"
export BOC_VERIFY_SSL="true"
export BOC_MCP__PORT="8000"
```
Or use YAML: copy `config/config.example.yaml` to `config.yaml` and modify.
All configuration items:
| Environment Variable | YAML Key | Default Value | Description |
| --- | --- | --- | --- |
| `BOC_BASE_URL` | `base_url` | — (required) | BeyondContainer platform root address, do not bring trailing slash |
| `BOC_USERNAME` | `username` | — (required) | Login username |
| `BOC_PASSWORD` | `password` | — (required) | Login password |
| `BOC_SYSTEM_ID` | `system_id` | `"1"` | Business system ID, default 1 |
| `BOC_VERIFY_SSL` | `verify_ssl` | `true` | Whether to verify HTTPS certificate |
| `BOC_REQUEST_TIMEOUT` | `request_timeout` | `30` | Single HTTP request timeout (seconds) |
| `BOC_MAX_RETRIES` | `max_retries` | `3` | Network error retry times |
| `BOC_LOG_LEVEL` | `log_level` | `"INFO"` | Log level (DEBUG/INFO/WARNING/ERROR) |
| `BOC_CONFIG_FILE` | — | — | Specify YAML configuration file path |
| `BOC_MCP__HOST` | `mcp.host` | `"0.0.0.0"` | MCP HTTP listening address |
| `BOC_MCP__PORT` | `mcp.port` | `8000` | MCP HTTP listening port |
### 3. Start Service
```bash
python -m boc_mcp
# Or development mode (colored log)
$env:BOC_DEV=1; python -m boc_mcp # PowerShell
# BOC_DEV=1 python -m boc_mcp # bash
```
After service startup:
1. Load configuration → 2. Initialize log → 3. Login to BeyondContainer platform to obtain token → 4. Listen `http://0.0.0.0:8000/mcp`.
Health check: `GET http://localhost:8000/healthz` (liveness), `GET http://localhost:8000/healthz/ready` (readiness with token check).
### 4. Access MCP Client
**Claude Desktop / Codex CLI** configuration example (add to respective MCP configuration file):
```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"
}
}
}
}
```
If stdio mode is needed, use command mode:
```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"
}
}
}
}
```
## Tool List (58, all read-only)
All tools start with `boc_`. List tools uniformly support `page`/`page_size` (maximum 100) pagination parameters.
### Authentication (auth)
- `boc_auth_status` — Query login status, current user, token expiration time
- `boc_auth_refresh` — Force re-login to BeyondContainer platform
### Application (application)
- `boc_app_get` — Query application details by application ID
- `boc_app_list` — Paginate query application list, filter by cluster/name
### Cluster (cluster)
- `boc_cluster_list` — Cluster list (paginated, keyword filtering)
- `boc_cluster_all` — All clusters (not paginated, brief table)
- `boc_cluster_base_info` — Cluster basic information (type/name/version filtering)
- `boc_cluster_monitor` — Specified cluster monitoring information
- `boc_cluster_state` — Specified cluster running state
- `boc_cluster_nodes` — Node list under cluster
- `boc_cluster_partitions` — Partition list under cluster
- `boc_cluster_partition_resource` — Specified hostId partition CPU/memory resource usage
- `boc_cluster_by_env` — Cluster list under specified tenant
- `boc_cluster_available_partitions` — Available partitions for current tenant
### Service Tree (service_tree)
- `boc_service_tree` — Service tree node query (supports parent type/parent ID/node type filtering)
### Security Scanning (scan)
- `boc_scan_list_strategies` — Security scanning strategy list
- `boc_scan_get_report` — Scanning report details
- `boc_scan_list_reports` — Scanning report list
### Configuration/Secret (config_secret)
- `boc_secret_list` — Secret list under specified cluster/namespace
### Network (network)
- `boc_network_list_by_name` — Query network partition by name/IP
- `boc_network_available` — Available (unassigned) network list
- `boc_network_by_env` — Network list under specified tenant
### Partition (partition)
- `boc_partition_list` — Paginate query partition list
- `boc_partition_get_default` — Cluster default partition
- `boc_partition_get_meta` — Query partition metadata by condition
- `boc_partition_list_default` — Default partition list (not paginated)
- `boc_partition_list_nodes` — Partition node list
- `boc_partition_list_all_hosts` — All host node list
- `boc_partition_all_info` — Host full information (cluster/tenant/IP/name filtering)
- `boc_partition_detail` — Partition details
- `boc_partition_list_available` — Available partitions for current tenant
### Monitoring (monitor)
- `boc_monitor_get_project_status` — Single application real-time monitoring status
- `boc_monitor_batch_project` — Batch project monitoring data
- `boc_monitor_batch_project_status` — Batch project status monitoring
- `boc_monitor_get_app` — Single service monitoring data
- `boc_monitor_batch_app` — Batch application monitoring data
- `boc_monitor_get_pod` — Pod monitoring data
- `boc_monitor_batch_container` — Batch container monitoring data
- `boc_monitor_batch_pod` — Batch Pod monitoring data
### Version/Image (version)
- `boc_version_list` — Version list
- `boc_version_get_id_by_name` — Query version ID by name
- `boc_version_list_image_groups` — Version image group list
- `boc_version_list_dispatched_clusters` — Version published cluster list
- `boc_version_list_undispatched_clusters` — Version unpublished cluster list
- `boc_version_get_image_group` — Image group information
- `boc_version_get_yaml` — Specified K8s resource YAML
### Workload (workload)
- `boc_workload_project_list` — Application (Project) list
- `boc_workload_app_list` — Application + service list
- `boc_workload_application_list` — Service/Task (Application) list
- `boc_workload_service_network` — Specified service under network information
- `boc_workload_container_list` — Container list
- `boc_workload_pod_list` — Instance (Pod) list
- `boc_workload_kubectl_pods` — kubectl accessible Pod list
- `boc_workload_check_internal_service` — Check if internal service exists under namespace
- `boc_workload_get_internal_load` — Internal load details
- `boc_workload_list_internal_loads` — Specified service under internal load list
- `boc_workload_internal_service_list` — Internal load list (paginated)
- `boc_workload_internal_service_detail` — Internal load general query
## Architecture
```
┌───────────── 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() unified parsing │
├────────────────────────────────────────────────────────────┤
│ Client layer │
│ ├─ BocApiClient (Protocol) │
│ ├─ BocHttpClient (aiohttp real implementation, injecting header/retries) │
│ ├─ TokenManager (three-step login + memory cache + asyncio.Lock) │
│ └─ paginate() unified pagination iterator │
├────────────────────────────────────────────────────────────┤
│ Cross-cutting │
│ ├─ middleware.wrap_tool_errors (BocMcpError → MCP error) │
│ ├─ logging_setup (JSON/development mode + sensitive field desensitization) │
│ └─ health (liveness/readiness) │
└────────────────────────────────────────────────────────────┘
```
Key design:
- **Authentication process**: BeyondContainer three-step login — `GET /upmstreeapi/bocPortal/getMenus` extract `clientId` → `POST /upmstreeapi/login` exchange `code` → `GET /upmstreeapi/accessToken` obtain `token`/`refreshToken`/`expiredTime`, then each request carries `token`, `refreshToken`, `systemId` in header.
- **Token invalidation handling**: business request returns 401 or matches platform token invalidation message, call `token_mgr.invalidate()` clear cache and re-login (clientId cached), original request automatically retries once.
- **Two response envelopes**: BeyondContainer interface simultaneously exists `{state,code,data,message,entity}` and `{success,currPageNum,pageSize,totalCount,pageCount,rows}` two structures, `BocHttpClient` and each Service's `_parse_list()` unified parsing.
- **Error hierarchy**: `BocMcpError` has clear subclasses (authentication, network, business, configuration), `wrap_tool_errors` middleware converts it to MCP JSON-RPC standard error code.
## Development
```bash
# Run unit tests (default)
python -m pytest
# Run all tests with coverage threshold 80%
python -m pytest --cov=boc_mcp --cov-fail-under=80
# Run E2E tests (need to start service)
python -m pytest -m e2e
# Code inspection
ruff check src tests
ruff format --check src tests
mypy src/boc_mcp
```
Directory structure:
```
src/boc_mcp/
├── __main__.py # python -m boc_mcp entry
├── server.py # create_app / run, MCP assembly
├── config.py # configuration loading (env + yaml)
├── logging_setup.py # log + sensitive field desensitization
├── middleware.py # error conversion to MCP error
├── health.py # /healthz, /healthz/ready
├── auth/
│ ├── models.py # TokenSet
│ └── token_manager.py # three-step login + cache + invalidation re-login
├── client/
│ ├── boc_client.py # BocApiClient Protocol + BocHttpClient
│ ├── errors.py # BocMcpError system
│ └── pagination.py # unified pagination 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 domain model
│ ├── service.py # business logic
│ └── tools.py # @mcp.tool registration
```
## Documentation
- docs/usage-guide.md: installation, configuration, startup, client access, common query scenarios, troubleshooting guide
- docs/api-reference.md: all 58 tool interface documentation (parameters, type, required, return value)
- docs/test-cases.md: automation test index + connect real platform manual test case + CI description
- docs/api-inventory.md: interface list (BeyondContainer API path and tool mapping)
## Kubernetes Deployment
Deployment details located in \deploy/k8s/, use kustomize one-click deployment. See \deploy/k8s/README.md\.
## 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
```
## License
Internal use, follow team specifications.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available