内容
# YuniKorn MCP 服务器
一个与 Apache YuniKorn 调度器接口的模型上下文协议（MCP）服务器，允许 AI 代理观察和推理 Kubernetes 批量工作负载资源管理、队列层次结构和应用程序状态。
## 截图
使用 [MCP 检查工具](https://modelcontextprotocol.io/docs/tools/inspector) 检查 Yunikorn 工具
使用 [Opencode](https://opencode.ai/) 通过 MCP 查询 Yunikorn 调度器
## 功能
- **7 种 MCP 工具**: 查询分区、队列、应用程序、节点、用户使用情况和调度器健康状态
- **2 种 MCP 资源**: 分区列表和节点利用率的静态数据访问
- **异步 HTTP**: 使用 `httpx` 进行非阻塞 API 调用
- **正确的错误映射**: YuniKorn HTTP 错误映射到标准 MCP 错误响应
- **资源感知**: 处理 YuniKorn 的原始字节和毫核值
- **启用 CORS**: 允许来自任何来源的浏览器连接以进行 MCP 检查
- **可流式 HTTP**: 默认传输方式，支持 stdio 回退以进行 IDE 集成
## 安装
```bash
uv pip install -r requirements.txt
```
如果您正在使用虚拟环境，请确保首先激活它：
```bash
source .venv/bin/activate
uv pip install -r requirements.txt
```
## 使用
### 运行服务器
默认传输方式是在 **Streamable HTTP** 上，端口为 8000：
#### 在本地运行
```bash
uv run python -m main
```
#### 使用 Docker 运行
```bash
docker run -p 8000:8000 -e YUNIKORN_BASE_URL="http://<REPLACE_ME>/ws/v1" docker.io/frenoid/yunikorn-mcp-server:latest
```
#### 命令行选项
| 选项 | 描述 | 默认值 |
|--------|-------------|---------|
| `--transport` | 传输协议（`stdio`，`streamable-http`） | `streamable-http` |
| `--host` | 绑定的主机（仅限 HTTP 传输） | `0.0.0.0` |
| `--port` | 监听端口（仅限 HTTP 传输） | `8000` |
| `--log-level` | 日志级别 | `INFO` |
示例：
```bash
# 在自定义端口上使用 Streamable HTTP
uv run python -m main --transport streamable-http --host 127.0.0.1 --port 8080
# 为 Claude Code / IDE 集成使用 Stdio 模式
uv run python -m main --transport stdio
```
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `YUNIKORN_BASE_URL` | YuniKorn REST API 的基本 URL | `http://localhost:9089/ws/v1/` |
| `TLS_INSECURE` | 禁用 HTTPS 证书验证（`true`/`false`） | `false` |
```bash
# 连接到远程 YuniKorn 实例
YUNIKORN_BASE_URL=http://yunikorn.example.com:9089/ws/v1/ uv run python -m main
# 连接到具有自签名证书的 HTTPS 端点
YUNIKORN_BASE_URL=https://yunikorn.example.com:9089/ws/v1/ TLS_INSECURE=true uv run python -m main
```
### 使用 MCP 检查工具连接
Streamable HTTP 端点在 `/mcp` 路径上公开：
```
http://localhost:8000/mcp
```
## 测试
针对实时 YuniKorn 实例运行测试套件：
```bash
YUNIKORN_BASE_URL=http://your-yunikorn-host:9089/ws/v1/ uv run python test_server.py
```
运行快速合规性检查：
```bash
YUNIKORN_BASE_URL=http://your-yunikorn-host:9089/ws/v1/ uv run python test_updated_server.py
```
### 数据格式说明
- **内存**: 以原始字节（64 位有符号整数）表示。
- **CPU（vcore）**: 以毫核（千分之一核，即 1000m = 1 核）表示。
- **其他资源**: 没有分配特定单位。
- **活动应用程序**: 虚拟的“活动”状态表示新建、已接受、运行中、完成中和失败状态。
- **allocationID 与 uuid**: `uuid` 已弃用。`allocationID` 包含与 `uuid` 相同的基本值，并带有连字符-计数器后缀（例如，`-0`，`-1`）。
- **allocationDelay**: 分配时间和请求时间之间的差值。
## API 一致性
此 MCP 服务器符合 [Apache YuniKorn 调度器 REST API](https://yunikorn.apache.org/docs/api/scheduler/)（v1.8.0）。每个工具直接映射到一个文档化的端点。
| 工具 | YuniKorn 端点 |
|------|-------------------|
| `get_partitions` | `GET /ws/v1/partitions` |
| `get_partition_queues` | `GET /ws/v1/partition/{partitionName}/queues` |
| `get_applications_by_state` | `GET /ws/v1/partition/{partitionName}/applications/{state}?status={status}` |
| `inspect_application` | `GET /ws/v1/partition/{partitionName}/application/{appId}` |
| `get_node_details` | `GET /ws/v1/partition/{partitionName}/nodes` 或 `/node/{nodeId}` |
| `get_user_usage` | `GET /ws/v1/partition/{partitionName}/usage/users` 或 `/usage/user/{userName}` |
| `check_scheduler_health` | `GET /ws/v1/scheduler/healthcheck` |
**资源：**
| 资源 | YuniKorn 端点 |
|----------|-------------------|
| `yunikorn://partitions/list` | `GET /ws/v1/partitions` |
| `yunikorn://nodes/utilization` | `GET /ws/v1/scheduler/node-utilizations` |
## 错误映射
| YuniKorn HTTP 代码 | MCP 错误 |
|--------------------|-----------|
| `400 Bad Request` | `INVALID_REQUEST` |
| `404 Not Found` | `INVALID_REQUEST` |
| `500 Internal Server Error` | `INTERNAL_ERROR` |
MCP 市场