Metadata-Version: 2.3
Name: image-to-design-mcp
Version: 0.1.5
Summary: MCP server for image-to-design workflow automation
Requires-Dist: mcp>=1.12.4
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# gauss-mcp

基于 `uv` 管理的 Python MCP server，用于把本地图片导入为方案，并通过 job 协议提供可轮询的进度与结果。

## 当前 MVP 范围

- 输入本地图片路径
- 上传图片
- 判断普通图/全景图
- 普通图转全景图
- 可选清家具
- 全景图转点云
- 空间调整
- 导入方案
- 返回 design link

## 核心设计

- 普通 tool 调用保持短切片，不等待整条 job 结束
- 对外主流程暴露 7 个 job tools：
  - `gauss_start_image_job`
  - `gauss_update_job_inputs`
  - `gauss_wait_current_stage`
  - `gauss_poll_job`
  - `gauss_get_job`
  - `gauss_resume_job`
  - `gauss_list_jobs`
- `gauss_wait_current_stage` 是默认等待手段：服务端内部执行 `poll + wait`，只等待“当前阶段结束”或一个 `timeout_sec` 切片，默认 60 秒；超时返回 `status=in_progress`
- `gauss_poll_job` 保留给 debug 或细粒度观察，不再要求 agent 自己 Bash `sleep`
- 对于用户未提前给出的阶段参数，可以在 `gauss_start_image_job` 时显式传 `null`，等进入对应阶段前再通过 `gauss_update_job_inputs` 补齐
- `clear_furniture` 只在 `pano_clear` 阶段生效，`level_height_mm` 只在 `gauss_import` 阶段生效
- 通过阶段事件与阶段摘要给 skill 提供进度展示依据，而不是 fake percent
- 紧凑 `job` 返回会在已有可展示全景图时携带 `pano_url`，供 skill 直接展示图片反馈
- Claude Code skill 不会在任务一开始统一追问参数；只有在 `pano_clear` / `gauss_import` 开始前才会询问对应设置
- 长耗时阶段按 15-30 秒节奏推进；同步 wait tool 会复用阶段轮询间隔，减少 transcript 噪音
- `gauss_import` 完成后会立即产出 `design_url`，用户可以先打开方案预览；`gauss_show_info` 继续补齐 `splat_url` / `drc_url`
- job 状态落盘到 `IMAGE_TO_DESIGN_JOB_STATE_DIR`，支持中断后继续查询或恢复

## 阶段顺序

1. `upload`
2. `image_type`
3. `img2pano`
4. `pano_clear`
5. `pano2pointcloud`
6. `spatial_tune`
7. `gauss_import`
8. `gauss_show_info`

## 开发

```bash
uv sync --dev
uv run pytest
uv run ruff check src tests
```

## 运行 MCP Server

```bash
uv run gauss-mcp
```

## 本地 smoke test

默认使用同步 wait tool：

```bash
uv run python scripts/e2e_image_to_plan.py /absolute/path/to/image.png
```

可选参数：

```bash
uv run python scripts/e2e_image_to_plan.py /absolute/path/to/image.png \
  --floor-plan-name demo-plan \
  --level-height-mm 2800 \
  --no-clear-furniture \
  --wait-timeout-sec 60
```

如需切回细粒度 poll 调试：

```bash
uv run python scripts/e2e_image_to_plan.py /absolute/path/to/image.png --mode poll
```

## Claude Code Skill

Skill 位于：

```text
.claude/skills/gauss-image-to-plan/SKILL.md
```

它基于 `gauss_*` job tools 做阶段式编排：

- 启动新任务时可先把未知的 `clear_furniture` / `level_height_mm` 置为 `null`，不阻塞上传与前置处理
- 当 `job.current_stage == pano_clear` 且 `job.clear_furniture == null` 时，再询问是否清家具，并调用 `gauss_update_job_inputs`
- 当 `job.current_stage == gauss_import` 且 `job.level_height_mm == null` 时，再询问层高，并调用 `gauss_update_job_inputs`
- 主路径优先使用 `gauss_wait_current_stage`，不再要求 agent 自己 Bash `sleep`
- 长耗时阶段默认按 60 秒切片同步等待，减少 transcript 噪音
- 如果 `next_poll_after_sec=null`，说明当前阶段在等用户补齐输入，不继续自动 wait
- `job.pano_url` 首次可用时，会在对话里展示全景图反馈
- `gauss_import` 完成后先返回可预览的 `design_url`
- `gauss_show_info` 继续补齐 `splat_url` / `drc_url`
- `gauss_poll_job` 只保留给 debug 或细粒度观察
