AI Galaxy Compute MCP

智星云（AI Galaxy）OpenAPI v2 的安全封装，提供 CLI 和 stdio MCP 两种使用方式，供 Codex 或其他自动化 agent 在预算与安全边界内完成算力发现、询价、租用、连接和退租。

目标不是无约束消费，而是提供“实时发现 → 询价 → 预算校验 → 显式创建 → 接入 → 退租 → 磁盘清理”的受控自动化闭环。

特性

• 仅依赖 Python 标准库 + mcp，无需额外运行时。
• CLI 入口：ai-galaxy-compute
• MCP 入口：ai-galaxy-compute-mcp（stdio）
• 支持 CPU 与 GPU 实例筛选、实时询价、创建前预算校验。
• 租用/退租为两阶段操作，必须显式确认，且使用一次性 HMAC 审批令牌。
• 默认不返回初始化密码、VNC/SSH 临时密码等敏感字段。
• 所有远程写操作不自动重试，避免网络抖动导致重复下单。
• 自动续费固定关闭；对时长、总价、小时价、GPU 数、磁盘、带宽均设有策略上限。

安全模型

1. 凭据来源

   • 环境变量 AI_GALAXY_ACCESS_KEY / AI_GALAXY_SECRET_KEY；或
   • 权限为 0600 的本地 JSON 文件，路径通过 AI_GALAXY_CREDENTIALS_FILE 指定。
   • 不要把凭据写入 .env、计划文件、shell history 或提交到 Git。

2. 默认只读

   • auth、catalog、balance、instances、status、connect 不会创建或修改资源。
   • plan / plan_release 只询价，不下单。

3. 写操作两阶段

   • plan → 生成私有 approval_token。
   • rent 必须传入与计划文件完全匹配的 approval_token，且受预算上限保护。
   • 令牌由本机 0600 随机密钥用 HMAC 签发，计划文件被修改后立即失效。
   • 令牌消费记录持久化；创建请求超时后禁止复用，必须先 instances 对账。

4. 敏感信息脱敏

   • connect 默认只返回 host、端口、用户名；只有 --include-sensitive 才返回密码。

安装

git clone <repo-url>
cd ai-galaxy-compute
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

依赖：Python >= 3.10，mcp>=1.28,<2。

配置凭据

推荐方式（MCP 必须使用此方式）：

mkdir -p ~/.config/ai-galaxy-compute
install -m 600 /dev/null ~/.config/ai-galaxy-compute/credentials.json

编辑文件，写入：

{
  "access_key": "你的 AccessKey",
  "secret_key": "你的 SecretKey"
}

确认权限：

chmod 600 ~/.config/ai-galaxy-compute/credentials.json
export AI_GALAXY_CREDENTIALS_FILE="$HOME/.config/ai-galaxy-compute/credentials.json"

也可以临时使用环境变量（仅 CLI）：

export AI_GALAXY_ACCESS_KEY='...'
export AI_GALAXY_SECRET_KEY='...'

注意：通过 shell 输入会进入 history，生产环境建议使用凭据文件。

CLI 使用

只读检查

ai-galaxy-compute auth
ai-galaxy-compute balance
ai-galaxy-compute catalog
ai-galaxy-compute instances

筛选并询价（不会创建实例）

ai-galaxy-compute plan \
  --gpu-type 'GeForce RTX 4090' \
  --gpu-count 1 \
  --image ubuntu22_cuda12 \
  --hours 1 \
  --min-cpu 4 \
  --min-memory 16 \
  --max-hourly-price 2 \
  --max-total-price 2 > rental.plan.json

确认后租用

检查 rental.plan.json，复制其中的 approval_token：

ai-galaxy-compute rent \
  --plan-file rental.plan.json \
  --approval-token '<token>' \
  --max-total-price 2

查询与连接

ai-galaxy-compute status '<instance_name>'
ai-galaxy-compute connect '<instance_name>' --wait-seconds 600

退租

ai-galaxy-compute release-plan '<instance_name>' > release.preview.json
ai-galaxy-compute release \
  --preview-file release.preview.json \
  --approval-token '<token>'

平台提前退租不会自动释放保留磁盘；如果实例进入状态 8，仍需另行调用保留磁盘释放接口。当前版本不会声称状态 8 已完成清理。

MCP 注册

codex mcp add aiGalaxyCompute \
  --env AI_GALAXY_CREDENTIALS_FILE=$HOME/.config/ai-galaxy-compute/credentials.json \
  --env AI_GALAXY_STATE_DIR=$HOME/.local/state/ai-galaxy-compute \
  -- $HOME/.local/bin/ai-galaxy-compute-mcp

提供的工具：

工具	作用
catalog	实时 CPU/GPU 规格、库存和价格
balance	账户余额与额度
plan_rental	选择并询价，返回 plan_id，不创建实例
rent	消费一次性内部计划并创建实例，必须 confirm=true
get_instance	等待运行并返回脱敏连接信息
plan_release	为本 MCP 创建的实例生成退租询价
release	消费退租计划，必须 confirm=true
cleanup_kept_disk	永久释放保留磁盘，必须 confirm=true

测试

单元测试不使用真实凭据、不访问网络、不产生费用：

PYTHONPATH=src python -m unittest discover -s tests -v

线上测试建议按 auth -> catalog -> instances -> plan 顺序进行；除非明确决定产生费用，不运行 rent。

项目结构

src/ai_galaxy_compute/
├── client.py      # 签名 HTTP 客户端和 OpenAPI 端点
├── broker.py      # 规格选择、预算策略、询价、租用、连接状态
├── cli.py         # 命令行入口
├── mcp_server.py  # FastMCP 工具定义
├── plan_store.py  # 私有计划、文件锁、ownership 和状态迁移
├── ledger.py      # HMAC 审批令牌与一次性消费记录
├── signing.py     # 请求签名
├── transport.py   # multipart/form-data HTTP 传输
└── errors.py      # 异常类型

tests/             # 单元测试

接口依据

• 基础地址：https://app.ai-galaxy.cn
• 所有请求：POST multipart/form-data
• 签名：非空参数按参数名升序拼接，追加 &secret=<SecretKey> 后计算 MD5
• 文档入口：https://s.apifox.cn/b0fc397f-c455-4c9a-9d82-875fc48ae106/doc-5644954

License

MIT