DeepCube 本地安装与 MCP 接入配置指南

1. 准备安装信息

开始安装前，先准备以下信息：

如果只让 Agent 查询 DeepCube SDK 文档，不查真实模型元数据，可以暂时不准备 DeepFOS 环境地址和鉴权信息。

2. 确认 Python 解释器

DeepCube 要求 Python 3.10 及以上，推荐使用 Python 3.12。本文后续命令以 Python 3.12 为例：

python3.12 --version
python3.12 -m pip --version

如果没有 Python 3.12，建议先安装 Python 3.12。若受本机环境限制，也可以使用 Python 3.10 及以上版本，但需要把后续命令中的 python3.12 替换成实际解释器命令或解释器绝对路径。机器上有多个 Python 时，后续命令都使用 python3.12 -m pip 这类解释器绑定命令，不要直接用裸 pip。

3. 获取 DeepCube 发行包

DeepCube 当前不是公开开源包。安装前需要先获取对应平台的发行版 wheel。

获取方式：

1. 有内部权限的用户可从 Gitee Releases 下载：

https://gitee.com/proinnova/deepcube/releases

1. 如果没有 Gitee 内部权限，请从项目指定渠道获取最新发行版 wheel。

选择 wheel 时应匹配本机系统和 CPU 架构。例如：

macOS Apple Silicon: deepcube-<version>-cp38-abi3-macosx_11_0_arm64.whl
macOS Intel:         deepcube-<version>-cp38-abi3-macosx_10_12_x86_64.whl
Linux x86_64:        deepcube-<version>-cp38-abi3-linux_x86_64.whl
Linux aarch64:       deepcube-<version>-cp38-abi3-linux_aarch64.whl
Windows x86_64:      deepcube-<version>-cp38-abi3-win_amd64.whl

4. 安装 DeepCube

拿到 wheel 后安装 DeepCube。安装前再次确认解释器为 Python 3.10 及以上，推荐 Python 3.12。建议安装时带上 MCP 可选依赖：

python3.12 -m pip install "<deepcube-wheel-file>[mcp]"

示例：

python3.12 -m pip install "<deepcube-发行版-wheel文件>[mcp]"

这里的 [mcp] 是 Python 包的 extras / 可选依赖语法，不表示安装一个独立的 MCP 包。它的意思是：安装 DeepCube，同时补齐运行 DeepCube MCP server 所需的额外依赖，例如 mcp、deepfos、cachetools 等。

如果已经安装过不带 MCP 可选依赖的 DeepCube，可再执行一次带 [mcp] 的安装命令补齐 MCP 依赖：

python3.12 -m pip install "<deepcube-wheel-file>[mcp]"

如果所在环境已配置 DeepCube 内部包索引，也可以从包索引安装：

python3.12 -m pip install "deepcube[mcp]"

注意：该命令依赖内部包索引。DeepCube 当前不能默认从公开 PyPI 安装。

macOS 如遇证书错误，可先运行 Python 安装器提供的 Install Certificates.command，再重新安装。

5. 验证 DeepCube 与 MCP 能力

以下命令以推荐的 Python 3.12 为例；如果实际使用 Python 3.10 及以上的其他解释器，请替换为对应解释器。

python3.12 -m pip show deepcube deepfos mcp
python3.12 -m pip check
python3.12 -m deepcube.mcp --help

如果 pip check 没有 broken requirements，且 deepcube.mcp --help 能输出帮助信息，说明 DeepCube 已安装，且 DeepCube 自带的 MCP server 可以启动。此时就可以交给 Qoder、Trae 或其他 Agent 配置使用。

6. 阅读已安装包内的 MCP README

DeepCube 安装完成后，详细 MCP 使用说明在包内 README。以下命令仍以推荐的 Python 3.12 为例；如果使用其他 Python 3.10 及以上解释器，请替换为实际解释器：

python3.12 -c "from deepcube.mcp.paths import mcp_readme_path; print(mcp_readme_path())"

该 README 说明了：

• deepcube-mcp 的工具列表。

• --env-url、--headers、--transport 等参数。

• Cursor 等 MCP 客户端如何配置。

• SDK 文档模式和在线元数据模式的区别。

• 常见错误和排查方式。

7. 准备给 Agent 的信息

把以下信息交给 Qoder、Trae、Cursor、Codex 等工具，让它按“第二部分：给 Coding Agent 的执行指南”配置和验证：

Python 解释器路径：Python 3.10 及以上，推荐 Python 3.12，例如 <python3.12-path>
DeepFOS 环境地址：例如 https://<host>/<prefix>/deepfos-server
app：<your-app>
space：<your-space>
cookie：<your-cookie>
目标模型名称：可选，例如 <cube-name>
目标模型路径：可选，例如 <cube-path>

如果还没有环境鉴权信息，让 Agent 先按 SDK 文档模式配置；后续拿到环境信息后再补在线元数据能力。

8. 让 Agent 查详细说明

让 Agent 优先阅读已安装目录下的 deepcube/mcp/README.md。本文只提供额外安装和交付建议，具体 MCP 参数以包内 README 和代码为准。

python3.12 -c "from deepcube.mcp.paths import mcp_readme_path; print(mcp_readme_path())"

用户只需要确认 DeepCube 已安装、MCP 可选依赖已补齐，并把 Python 3.10 及以上的解释器路径、环境鉴权信息和目标模型信息交给 Agent。推荐使用 Python 3.12。后续具体配置与验证可由 Agent 按包内 README 和本文第二部分完成。

1. Agent 的目标

Agent 的目标不是“只告诉用户怎么做”，而是尽量帮助用户完成以下闭环：

确认 Python 解释器
-> 获取 DeepCube wheel
-> 安装 DeepCube 并补齐 MCP 可选依赖
-> 验证依赖
-> 配置 MCP 启动参数
-> 验证 MCP 工具
-> 查询一个真实模型

如果用户只需要离线 SDK 文档能力，可以停在 deepcube_ping。如果用户需要在线元数据能力，必须获取真实 DeepFOS 连接参数。

2. 安装前检查

Agent 应先检查本机解释器：

python3.12 --version
python3.12 -m pip --version

DeepCube 要求 Python 3.10 及以上，推荐 Python 3.12。Agent 应优先使用 Python 3.12；如果不存在 Python 3.12，应提示用户安装，或确认是否已有其他 Python 3.10 及以上且经过验证的解释器。不要擅自反复安装多个解释器。

多解释器环境下，禁止直接使用裸 pip。应使用：

python3.12 -m pip install ...

3. 安装 DeepCube 并补齐 MCP 可选依赖

Agent 必须先确认用户是否已获取 DeepCube 发行版。DeepCube 当前不是公开开源包，不能默认从公网 PyPI 安装成功。

安装 DeepCube 前必须确认当前解释器版本为 Python 3.10 及以上；推荐 Python 3.12。后续示例命令使用 python3.12，如实际解释器不同，应替换为用户确认后的解释器路径。

推荐让用户提供以下之一：

• 本地 wheel 文件路径。

• 可访问的内部 Gitee Releases 下载地址。

• 已配置好的内部包索引。

有内部权限时，可引导用户从以下地址下载对应平台 wheel：

https://gitee.com/proinnova/deepcube/releases

从本地 wheel 安装：

python3.12 -m pip install "<deepcube-wheel-file>[mcp]"

这里的 [mcp] 是 DeepCube wheel 声明的可选依赖组，用于补齐运行 DeepCube MCP server 所需依赖；它不是另一个独立包。

仅当用户明确说明内部包索引已配置时，才使用包名安装：

python3.12 -m pip install "deepcube[mcp]"

安装后必须执行：

python3.12 -m pip check
python3.12 -m deepcube.mcp --help

只有 pip check 无 broken requirements，且 deepcube.mcp --help 可启动，才算 DeepCube 安装与 MCP 能力验证完成。

4. 平台连接参数规则

Agent 不得自行编造以下参数：

• env-url

• app

• space

• cookie

• user

• 任何 x-deepfos-* 扩展头

如果用户没有提供平台连接信息，应明确说明：

当前只能使用 SDK 文档类 MCP 工具；在线元数据工具需要真实 DeepFOS 环境参数。

如果用户提供浏览器 curl，Agent 应只提取当前目标环境所需字段。

提取规则：

env-url = 请求 URL 中到 /deepfos-server 为止
app = 请求头 app
space = 请求头 space
language = 请求头 language，可选
cookie = 当前环境对应的 Cookie

不要把多个环境的 Cookie 混入同一个 MCP headers。

5. 启动参数生成规则

stdio 模式推荐启动参数：

python3.12 -m deepcube.mcp \
  --transport stdio \
  --env-url "https://<host>/<prefix>/deepfos-server" \
  --headers '{"app":"<app>","space":"<space>","language":"zh-cn","cookie":"<cookie>"}'

本地 stdio 集成不要主动加入 --discovery。只有用户明确说明环境走 Eureka / Nacos / K8s 服务发现时，才考虑服务发现配置。

6. MCP 客户端配置生成规则

Agent 生成 MCP 客户端配置时，优先使用明确解释器路径。该解释器必须是 Python 3.10 及以上，推荐 Python 3.12：

{
  "mcpServers": {
    "deepcube": {
      "command": "<python3.12-path>",
      "args": [
        "-m",
        "deepcube.mcp",
        "--transport",
        "stdio",
        "--env-url",
        "https://<host>/<prefix>/deepfos-server",
        "--headers",
        "{\"app\":\"<app>\",\"space\":\"<space>\",\"language\":\"zh-cn\",\"cookie\":\"<cookie>\"}"
      ]
    }
  }
}

如果用户只需要 SDK 文档能力，生成不含平台参数的配置：

{
  "mcpServers": {
    "deepcube": {
      "command": "<python3.12-path>",
      "args": [
        "-m",
        "deepcube.mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

7. 验证 MCP 链路

Agent 应按以下顺序验证：

deepcube_ping
deepcube_list_cubes(search="<cube-name>")
deepcube_list_cube_dimensions(element_name="<cube-name>", path="<cube-path>")

验证成功的最低标准：

• deepcube_ping 返回 status: ok。

• deepcube_list_cubes 能返回目标模型或可解释的错误。

• 在线查询失败时，错误信息能指向鉴权、URL、app、space 或模型参数问题。

如果 deepcube_list_cubes 返回多个模型，Agent 应提示用户选择正确路径，不应凭空选择。

8. 失败处理原则

Agent 应根据错误类型处理：

Agent 不应盲目重试，不应猜测新的 Cookie，不应使用文档中的示例 URL 当作真实环境。

9. 交付给用户时应说明什么

完成配置后，Agent 应向用户说明：

• 使用的 Python 解释器路径。

• Python 解释器版本是否满足 3.10 及以上，是否使用推荐的 3.12。

• deepcube / deepfos / mcp 版本。

• pip check 是否通过。

• DeepCube MCP 启动命令或客户端配置。

• 是否已验证 deepcube_ping。

• 如果连接了平台，是否已验证 deepcube_list_cubes。

不要在最终回复里完整回显用户 Cookie。可以说明 Cookie 已被用于本地配置或验证，但应脱敏展示。