gauss-mcp 0.1.1

MCP server for Gauss automatic import workflows

gauss-mcp

一个基于 FastMCP 的 Python MCP server，用来把公开图片 URL 驱动到 Gauss 自动导入链路。

当前 v1 聚焦这条主链路：

1. ImageType
2. Img2Pano（仅普通图需要）
3. PanoClear（按需）
4. Pano2PointCloud
5. SpatialTune
6. GaussImport
7. GaussInfo（轮询 v2/gauss/info 直到展示信息就绪）
8. 返回 design_id / plan_id / level_id / result_url / gauss_info_status / gauss_splat_url / gauss_drc_url

不在本轮范围内：本地图片上传、渲染发布。

能力概览

• 运行状态持久化到 SQLite + artifact 文件
• 支持中断恢复，不依赖会话上下文
• 支持从中间步骤派生 variant run
• 支持导出单步调试信息和完整 run report
• clear_furniture、floor_height_m 缺失时显式停下来等待用户输入
• ImageType 失败时，skill 可以向用户确认是否为全景图，再通过人工覆盖继续推进
• GaussImport 成功后会继续轮询 v2/gauss/info，直到展示信息可读
• 如果本地等待窗口结束但展示信息仍在生成，run 会保持 running，后续继续 gauss_resume_run 即可

环境要求

• Python 3.11+
• uv

安装

本地开发

uv sync

已发布包

如果已经发布到 PyPI 或内网 Python 仓库，其他人可以直接运行：

uvx gauss-mcp

配置

必填鉴权配置

本地开发可以创建 .env，变量名必须使用 GAUSS_* 前缀：

GAUSS_APPUID=your_appuid
GAUSS_APPKEY=your_appkey
GAUSS_APPSECRET=your_appsecret
GAUSS_API_BASE_URL=https://api-beta.kujiale.com/p/openapi/
GAUSS_WEB_BASE_URL=https://www.kujiale.com

可选运行时配置

GAUSS_STATE_DIR=/absolute/path/to/gauss-mcp/state
GAUSS_RUNS_DIR=/absolute/path/to/gauss-mcp/runs
GAUSS_TIMEOUT_S=300
GAUSS_POLL_INTERVAL_S=2
GAUSS_LOG_LEVEL=INFO
GAUSS_TRANSPORT=stdio
GAUSS_HOST=127.0.0.1
GAUSS_PORT=8000

全量参数说明

• GAUSS_APPUID：OpenAPI 鉴权所需的 appuid。默认 None，调用真实接口时通常必填。
• GAUSS_APPKEY：OpenAPI 鉴权所需的 appkey。默认 None。
• GAUSS_APPSECRET：OpenAPI 鉴权所需的 appsecret。默认 None。
• GAUSS_API_BASE_URL：OpenAPI 基础地址。默认 https://api-beta.kujiale.com/p/openapi/。
• GAUSS_WEB_BASE_URL：结果页基础地址，用于拼接 result_url。默认 https://www.kujiale.com。
• GAUSS_STATE_DIR：SQLite 状态目录。默认行为：
  • 从源码仓库直接运行时，使用 <repo>/data/state
  • 从已安装包或 uvx gauss-mcp 运行时，使用 ~/.gauss-mcp/state
• GAUSS_RUNS_DIR：run artifact 目录。默认行为：
  • 从源码仓库直接运行时，使用 <repo>/data/runs
  • 从已安装包或 uvx gauss-mcp 运行时，使用 ~/.gauss-mcp/runs
• GAUSS_TIMEOUT_S：单步远端轮询等待窗口，单位秒。默认 300。
• GAUSS_POLL_INTERVAL_S：轮询间隔，单位秒。默认 2。
• GAUSS_LOG_LEVEL：日志级别。默认 INFO。
• GAUSS_TRANSPORT：MCP 传输方式。默认 stdio。可选值：stdio、sse、streamable-http。
• GAUSS_HOST：HTTP 类传输绑定地址。默认 127.0.0.1；仅在 GAUSS_TRANSPORT=sse 或 streamable-http 时生效。
• GAUSS_PORT：HTTP 类传输监听端口。默认 8000；仅在 GAUSS_TRANSPORT=sse 或 streamable-http 时生效。

补充说明：

• database_path 由 GAUSS_STATE_DIR 派生，固定为 <state_dir>/gauss_mcp.sqlite3，不单独暴露环境变量。
• 分发给其他人时，推荐显式配置 GAUSS_STATE_DIR、GAUSS_RUNS_DIR，避免状态写入默认目录后不易排查。
• 不要把真实密钥提交到仓库。

启动 MCP Server

默认使用 stdio 传输。

如果设置 GAUSS_TRANSPORT=sse 或 GAUSS_TRANSPORT=streamable-http，进程会改为监听 GAUSS_HOST:GAUSS_PORT。

从源码仓库启动

uv run gauss-mcp

或：

uv run python -m gauss_mcp

从已发布包启动

uvx gauss-mcp

打包与发布

当前工程已经具备 Python 包分发能力：

• pyproject.toml 已声明 uv_build 构建后端
• 已提供 console script：gauss-mcp
• 可以构建 sdist / wheel 后上传到 PyPI 或内网仓库

典型发布流程：

uv build
uv run twine check dist/*
uv run twine upload dist/*

说明：

• 发布前记得更新 pyproject.toml 中的 project.version
• 如果使用内网仓库，可按仓库要求补充 twine upload 参数
• 发布完成后，其他人可直接通过 uvx gauss-mcp 使用

Claude Code / MCP 配置

推荐优先使用“已发布包 + uvx”的方式分发给其他人，不要求对方 clone 仓库。

方式一：用 CLI 添加到 Claude Code

添加到当前项目：

claude mcp add --scope project \
  --env GAUSS_APPUID=your_appuid \
  --env GAUSS_APPKEY=your_appkey \
  --env GAUSS_APPSECRET=your_appsecret \
  --env GAUSS_API_BASE_URL=https://api-beta.kujiale.com/p/openapi/ \
  --env GAUSS_WEB_BASE_URL=https://www.kujiale.com \
  gauss-mcp -- uvx gauss-mcp

如果想给自己全局使用，把 --scope project 改成 --scope user。

方式二：在项目根目录提供 .mcp.json

{
  "mcpServers": {
    "gauss-mcp": {
      "command": "uvx",
      "args": ["gauss-mcp"],
      "env": {
        "GAUSS_APPUID": "your_appuid",
        "GAUSS_APPKEY": "your_appkey",
        "GAUSS_APPSECRET": "your_appsecret",
        "GAUSS_API_BASE_URL": "https://api-beta.kujiale.com/p/openapi/",
        "GAUSS_WEB_BASE_URL": "https://www.kujiale.com"
      }
    }
  }
}

配置建议：

• 本地开发继续用 .env + uv run gauss-mcp 即可
• 分发给其他人时，更推荐用 Claude Code 的 env 配置显式注入参数，不要假设对方工作目录里一定有 .env
• 如果团队要共享 .mcp.json，不要把真实密钥直接提交到仓库

主要工具

Run 管理

• gauss_create_run
• gauss_get_run
• gauss_list_runs
• gauss_set_run_options
• gauss_resume_run
• gauss_create_variant

Step 执行

• gauss_run_image_type
• gauss_run_img2pano
• gauss_run_pano_clear
• gauss_run_pano2pointcloud
• gauss_run_spatial_tune
• gauss_run_gauss_import
• gauss_run_gauss_info

调试与导出

• gauss_get_step
• gauss_retry_step
• gauss_export_run_report

Resources

• gauss://runs/{run_id}
• gauss://runs/{run_id}/steps
• gauss://runs/{run_id}/steps/{step_key}
• gauss://runs/{run_id}/report

Skill 交互约定

推荐配合 .claude/skills/gauss-import/SKILL.md 使用。

正常情况下，skill 会采用“逐步展示、逐步汇报”的策略，而不是一上来就用一次 gauss_resume_run(wait=true) 把多个步骤吞在一起。

新建导入任务时

skill 会按下面的顺序执行，并在每一步结束后明确展示结果：

1. gauss_create_run
2. gauss_run_image_type
3. gauss_run_img2pano（仅 is_pano=false 时）
4. gauss_run_pano_clear（按需）
5. gauss_run_pano2pointcloud
6. gauss_run_spatial_tune
7. gauss_run_gauss_import
8. gauss_run_gauss_info

展示时会尽量明确：

• 当前 step 是否执行
• 关键结果是什么
• 哪些 step 被跳过
• 跳过原因是什么
• 下一步将做什么
• 当首次拿到可用全景图时，当前回复里同时展示 markdown 图片 ![全景图](...) 和 URL 文本
• 如果 PanoClear 产出了新的 cleared_panorama_url，会再次展示清家具后的全景图和 URL

例如：

• ImageType 已执行，结果是全景图 → Img2Pano 会被明确标记为“已跳过，原因是当前图已可直接视为全景图”，并在当前回复里同时展示 ![全景图](<source_url>) 和原始 URL
• ImageType 已执行，结果是普通图 → 下一步将显式执行 Img2Pano；一旦拿到 panorama_url，会立即展示全景图预览和 URL
• 如果用户选择清家具，且 PanoClear 返回了新的 cleared_panorama_url → 会再次展示清家具后的全景图预览和 URL

已有 run 时

如果用户给的是 run_id，skill 会优先复用当前 run，而不是重建：

1. 先调用 gauss_get_run(include_steps=true) 读取当前状态
2. 明确展示 run 的 status、current_step 和已完成步骤
3. 需要继续时再调用 gauss_resume_run 或对应单步工具
4. 失败时先读取失败 step 详情，再向用户解释原因和下一步建议

显式人机 gate

当前仍有 3 个显式的人机 gate：

1. clear_furniture 未提供
2. floor_height_m 未提供
3. ImageType / Img2Pano 异常后，怀疑图片类型误判，需要人工确认是否为全景图

第 3 个 gate 的典型处理方式：

• ImageType 失败 → 先读取 image_type step 详情，再询问用户这是不是全景图
• Img2Pano 异常，且前面存在 is_pano=false 的判断 → 明确告诉用户 ImageType 这一步已经跑过了，但当前怀疑可能误判，再询问用户这张图其实是不是全景图
• 用户回答“是全景图” → gauss_set_run_options(is_pano=true)，再继续 gauss_resume_run(wait=true)
• 用户回答“不是全景图” → gauss_set_run_options(is_pano=false)，再继续 gauss_resume_run(wait=true)

开发与验证

uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run twine check dist/*

真实环境 smoke test

真实 smoke test 会在上游创建实际任务。执行前请确认：

• .env 中已配置有效鉴权信息
• 输入的是公开可访问的图片 URL
• 你接受在测试环境创建真实导入任务

项目结构

src/gauss_mcp/
  __main__.py
  client.py
  config.py
  models.py
  server.py
  workflow.py
  persistence/
tests/

当前状态

本地质量门禁已打通：

• ruff
• mypy
• pytest
• uv build
• twine check

如果下一步要做真实链路验证，建议直接围绕 gauss-import skill 跑一次完整 smoke。