cloudstack-mcp

v0.0.4

Published

a month ago

CloudStack MCP 服务 - 容器云API工具(资源初始、项目部署等)

Downloads

0High
0Medium
0Low

workshub

CloudStack MCP

容器云平台的 MCP (Model Context Protocol) 服务，为 AI 助手提供 Kubernetes 集群管理、项目创建、容器部署、数据库和 Redis 管理等能力。

功能特性

集群管理 - 查询可用的 CCE 集群列表
项目管理 - 创建项目及完整的 K8s 基础设施（命名空间、网络策略、数据库、Redis）
容器部署 - 部署容器镜像到 K8s 环境，支持健康检查、配置文件、卷挂载等
版本管理 - 查看部署历史版本，支持一键回滚
高级资源 - 直接应用原始 K8s 清单（CronJob、StatefulSet 等）
数据库管理 - 为项目创建 MySQL/PostgreSQL 数据库
Redis 配置 - 获取 Redis 连接配置信息

环境要求

Node.js >= 18.0
npm 或 yarn

安装

本地开发

cd cloudstack-mcp
npm install
npm run build

全局安装

npm install -g .
cloudstack-mcp --version

配置

环境变量

| 变量 | 必填 | 默认值 | 说明 | |------|------|--------|------| | BOT_ID | 是 | - | 在权限系统注册的主机名，用于 HMAC 签名认证 | | BACKEND_URL | 否 | https://cloudstack-gateway.zbj.com | 网关地址 | | BACKEND_PERM_URL | 否 | https://cloudstack-auth-api.zbj.com | 权限管理服务地址 | | BACKEND_PERM_KEY | 是 | - | 权限服务接口鉴权 token | | DIRECT_MODE | 否 | false | 直连模式，跳过签名验证，适用于本地测试 | | DIRECT_AIOPS_KEY | DIRECT_MODE=true 时必填 | - | DIRECT_MODE 时的 API Key |

权限系统注册

在启动服务前，需要先在 cloudstack-auth-web 中注册主机：

访问权限管理 Web 界面
新增主机，填写 BOT_ID 作为主机名
系统会自动生成密钥（secret）
启动 MCP 服务时使用相同的 BOT_ID

使用方式

命令行启动

# 设置环境变量后启动
BOT_ID=my-bot cloudstack-mcp

# 或导出环境变量
export BOT_ID=my-bot
cloudstack-mcp

命令行参数

cloudstack-mcp              # 启动 MCP 服务（stdio 模式）
cloudstack-mcp --help       # 显示帮助信息
cloudstack-mcp --version    # 显示版本号

AI IDE 配置

Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "cloudstack": {
      "command": "node",
      "args": ["/path/to/cloudstack-mcp/dist/index.js"],
      "env": {
        "BOT_ID": "your-bot-id",
        "BACKEND_PERM_KEY": "your-perm-key"
      }
    }
  }
}

Claude Desktop

编辑 Claude Desktop 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cloudstack": {
      "command": "node",
      "args": ["/path/to/cloudstack-mcp/dist/index.js"],
      "env": {
        "BOT_ID": "your-bot-id",
        "BACKEND_PERM_KEY": "your-perm-key"
      }
    }
  }
}

MCP Inspector 调试

使用官方 Inspector 工具进行调试：

# 全局安装后
BOT_ID=my-bot BACKEND_PERM_KEY=your-key npx @modelcontextprotocol/inspector cloudstack-mcp

# 或指定路径
BOT_ID=my-bot BACKEND_PERM_KEY=your-key npx @modelcontextprotocol/inspector node ./dist/index.js

可用工具

list_clusters

查询当前可用的 CCE（云容器引擎）集群列表。

何时使用：

需要了解有哪些可用集群时
创建项目或部署应用前，需要确定目标集群
其他工具需要集群名称参数时，先调用此工具获取可选值

参数： 无

返回示例：

{
  "success": true,
  "data": {
    "clusters": ["openclaw", "production"],
    "default": "openclaw"
  }
}

create_project

初始化一个新的应用项目，自动创建完整的开发运维基础设施。

何时使用：

新应用项目启动时，需要创建完整的基础设施
首次部署应用前，必须先创建项目
需要为新项目配置 dev/test/prod 等多环境

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | project | string | 是 | 项目名称。小写字母开头，仅允许小写字母、数字、连字符。如 my-app、order-service | | cluster | string | 否 | 目标 CCE 集群名。不填则使用默认集群 | | environments | string[] | 否 | 要创建的环境列表，默认 ["test", "prod"] | | enableRds | boolean | 否 | 是否创建 RDS MySQL 数据库，默认 true | | enableRedis | boolean | 否 | 是否创建 Redis 连接 Secret，默认 true | | dbType | string | 否 | 数据库类型：mysql 或 postgres，默认 mysql |

幂等性： 重复调用安全，已存在的资源会自动跳过。

示例：

{
  "project": "my-app",
  "environments": ["test", "prod"],
  "enableRds": true,
  "enableRedis": true
}

deploy_container

将容器镜像部署到指定的 K8s 环境，自动创建或更新 Deployment、Service 和 Ingress 资源。

何时使用：

应用代码构建完成，需要部署新版本时
更新已部署应用的环境变量、资源配置或镜像版本
需要配置健康检查、卷挂载或自定义配置文件

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | project | string | 是 | 项目名称，必须是通过 create_project 已创建的项目 | | image | string | 是 | 容器镜像完整地址。如 swr.cn-north-1.myhuaweicloud.com/zbjdevops/my-app:latest | | environment | string | 是 | 目标环境：test 或 prod | | cluster | string | 否 | CCE 集群名。不填则使用默认集群 | | replicas | number | 否 | Pod 副本数量，默认 1。生产环境建议 2 或以上 | | domain | string | 否 | 自定义 Ingress 域名。不填则自动生成 | | containerPort | number | 否 | 容器内应用监听的端口号，默认 8080 | | envVars | object | 否 | 环境变量键值对。如 { "NODE_ENV": "production" } | | secrets | string[] | 否 | 要注入的 K8s Secret 名称列表 | | resources | object | 否 | 资源配置，包含 requests 和 limits | | healthCheck | object | 否 | 存活探针配置 | | readinessCheck | object | 否 | 就绪探针配置 | | configFiles | object | 否 | 配置文件内容。key 为文件名，value 为文件内容 | | volumes | array | 否 | 自定义卷挂载配置 |

resources 结构：

{
  "resources": {
    "requests": {
      "cpu": "100m",
      "memory": "128Mi"
    },
    "limits": {
      "cpu": "500m",
      "memory": "512Mi"
    }
  }
}

healthCheck 结构：

{
  "healthCheck": {
    "path": "/health",
    "port": 8080,
    "initialDelay": 30,
    "period": 10
  }
}

示例：

{
  "project": "my-app",
  "image": "swr.cn-north-1.myhuaweicloud.com/zbjdevops/my-app:v1.0.0",
  "environment": "prod",
  "replicas": 2,
  "containerPort": 8080,
  "envVars": {
    "NODE_ENV": "production",
    "LOG_LEVEL": "info"
  },
  "resources": {
    "requests": { "cpu": "100m", "memory": "128Mi" },
    "limits": { "cpu": "500m", "memory": "512Mi" }
  },
  "healthCheck": {
    "path": "/health",
    "port": 8080,
    "initialDelay": 30
  }
}

增量更新： 更新已有 Deployment 时，未传递的可选字段会保留原值。

list_revisions

查询指定项目和环境的 Deployment 版本历史记录。

何时使用：

需要回滚部署时，先调用此工具查看可用版本
了解部署历史和当前运行版本
排查问题时需要确认当前运行的镜像版本

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | project | string | 是 | 项目名称 | | environment | string | 是 | 目标环境：test 或 prod | | cluster | string | 否 | CCE 集群名。不填则使用默认集群 |

示例：

{
  "project": "my-app",
  "environment": "prod"
}

rollback_deployment

将 Deployment 回滚到之前的历史版本。

何时使用：

新版本部署后发现问题，需要紧急回滚
配置错误导致服务不可用，需要恢复到上一版本
发布流程出现异常，需要撤销最近的部署

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | project | string | 是 | 项目名称 | | environment | string | 是 | 目标环境：test 或 prod | | cluster | string | 否 | CCE 集群名。不填则使用默认集群 | | revision | number | 否 | 目标版本号。不填则回滚到上一个版本 |

示例：

{
  "project": "my-app",
  "environment": "prod"
}

注意： 建议先调用 list_revisions 确认版本号。

apply_raw_manifests

直接应用原始 Kubernetes YAML/JSON 清单，用于部署 deploy_container 不支持的资源类型。

何时使用：

需要部署 CronJob（定时任务）、StatefulSet（有状态应用）等高级资源
需要创建自定义 ConfigMap、Secret、HorizontalPodAutoscaler
需要精细控制 K8s 资源的完整配置

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | namespace | string | 是 | 目标命名空间。必须是 create_project 创建的命名空间 | | cluster | string | 否 | CCE 集群名。不填则使用默认集群 | | manifests | array | 是 | Kubernetes 资源对象数组（JSON 格式） |

允许的资源类型：

Deployment、StatefulSet、DaemonSet
Job、CronJob
Service、Ingress
ConfigMap、Secret
HorizontalPodAutoscaler、PodDisruptionBudget
NetworkPolicy
ServiceAccount、Role、RoleBinding
PersistentVolumeClaim

禁止的资源类型： 集群级资源（Namespace、ClusterRole、Node 等）出于安全考虑不允许使用。

示例：

{
  "namespace": "my-app-test",
  "manifests": [
    {
      "apiVersion": "batch/v1",
      "kind": "CronJob",
      "metadata": { "name": "cleanup-job" },
      "spec": {
        "schedule": "0 0 * * *",
        "jobTemplate": {
          "spec": {
            "template": {
              "spec": {
                "containers": [{
                  "name": "cleanup",
                  "image": "cleanup:latest"
                }],
                "restartPolicy": "OnFailure"
              }
            }
          }
        }
      }
    }
  ]
}

create_database

为已存在的项目单独创建 RDS 数据库和用户，生成对应的 K8s Secret。

何时使用：

项目创建时未启用 RDS（enableRds: false），后续需要添加数据库
需要为特定环境补充创建数据库
数据库被误删后需要重新创建

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | project | string | 是 | 项目名称（必须已存在） | | environment | string | 是 | 目标环境：test 或 prod | | cluster | string | 否 | CCE 集群名。不填则使用默认集群 | | dbType | string | 否 | 数据库类型：mysql 或 postgres，默认 mysql |

示例：

{
  "project": "my-app",
  "environment": "test",
  "dbType": "mysql"
}

注意： create_project 默认已创建数据库，此工具仅用于补充创建场景。

get_redis_config

查询项目的 Redis 连接配置信息。

何时使用：

需要获取 Redis 连接信息用于应用配置
排查 Redis 连接问题时需要确认配置
需要了解 Redis 的 keyPrefix 以避免键冲突

参数：

示例：

{
  "project": "my-app",
  "environment": "prod"
}

架构说明

调用链路

AI Client (Cursor/Claude)
    ↓ MCP Protocol (stdio)
cloudstack-mcp
    ↓ HTTP + HMAC Signature
APISIX Gateway (hostname-auth plugin)
    ↓
Java Backend API
    ↓
Kubernetes / RDS / Redis

认证机制

MCP 服务启动时，从权限管理服务（BACKEND_PERM_URL）获取密钥（secret）

每次请求时，计算 HMAC-SHA256 签名：

signature = HMAC-SHA256(secret, "{hostname}:{timestamp}")

请求携带认证头：
- X-Hostname: 主机名（BOT_ID）
- X-Timestamp: Unix 时间戳（秒）
- X-Signature: HMAC 签名
APISIX 网关验证：
- 主机名已注册且启用
- 时间戳在 ±30 秒内（防重放攻击）
- 签名验证通过
- 请求路径匹配允许的路由

401 自动重试

当运维手动重置密钥后，MCP 服务会在收到 401 响应时自动重新获取密钥并重试一次。

开发指南

项目结构

cloudstack-mcp/
├── src/
│   ├── index.ts           # 服务入口，工具定义和分发
│   ├── types/
│   │   └── index.ts       # TypeScript 类型定义
│   ├── utils/
│   │   └── http-client.ts # HTTP 客户端，HMAC 签名
│   └── tools/
│       ├── cluster.ts     # 集群管理工具
│       ├── project.ts     # 项目管理工具
│       ├── deploy.ts      # 部署管理工具
│       ├── database.ts    # 数据库管理工具
│       └── redis.ts       # Redis 管理工具
├── dist/                  # 编译输出
├── package.json
└── tsconfig.json

添加新工具

在 src/tools/ 目录下创建新的工具类文件
在 src/index.ts 中导入并实例化工具类
在 ListToolsRequestSchema 处理器中添加工具定义
在 CallToolRequestSchema 处理器中添加调用分发

构建与运行

# 开发模式（编译并运行）
npm run dev

# 仅编译
npm run build

# 运行编译产物
BOT_ID=my-bot npm start

错误处理

常见错误

| 错误信息 | 原因 | 解决方案 | |---------|------|---------| | 环境变量 BOT_ID 未配置 | 未设置 BOT_ID 环境变量 | 设置 export BOT_ID=your-bot-id | | 环境变量 BACKEND_PERM_KEY 未配置 | 未设置 BACKEND_PERM_KEY 环境变量 | 设置 export BACKEND_PERM_KEY=your-key | | 主机 "xxx" 未在权限管理系统注册 | BOT_ID 未在权限系统注册 | 在 cloudstack-auth-web 中新增主机 | | 权限管理服务不可达 | 无法连接到权限服务 | 检查 BACKEND_PERM_URL 和网络连接 | | 401 Unauthorized | 签名验证失败 | 检查时间同步，确认主机未被禁用 | | 403 Forbidden | 路径不在允许列表 | 在权限系统中配置允许的路由 |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

CloudStack MCP

功能特性

环境要求

安装

本地开发

全局安装

配置

环境变量

权限系统注册

使用方式

命令行启动

命令行参数

AI IDE 配置

Cursor

Claude Desktop

MCP Inspector 调试

可用工具

list_clusters

create_project

deploy_container

list_revisions

rollback_deployment

apply_raw_manifests

create_database

get_redis_config

架构说明

调用链路

认证机制

401 自动重试

开发指南

项目结构

添加新工具

构建与运行

错误处理

常见错误

相关文档

License