# Tripo AI · MCP Server + 本地 3D 查看器

> 把官方 [`tripo3d`](https://pypi.org/project/tripo3d/) Python SDK 包装成 **MCP Server**，让 AI 客户端（Qoder / Claude Desktop / 任何 MCP 客户端）能用自然语言生成 3D 模型；再附一个**零外网依赖的本地 three.js 查看器**看模型。
>
> **对中国网络特别友好**：国内 `.com` 直连 / 海外 `.ai` + 本地代理两种模式一键切换。

![旋转鸡块复刻](docs/assets/nugget-preview.webp) ![low-poly 小狐狸](docs/assets/fox-preview.webp)

---

## ✨ 能做什么

- 💬 **对话生成 3D**：「生成一个 low-poly 小狐狸」→ 自动出 GLB 模型
- 🖼 **图生 3D**：给张图 → 转成 3D 模型
- 🔧 **9 个工具**：查余额、文生 3D、图生 3D、精修、转格式（GLTF/FBX/OBJ/STL/USDZ/3MF）等
- 🎮 **本地查看器**：旋转/缩放/线框/截图，含[旋转鸡块热梗复刻页](viewer/README.md)
- 🇨🇳 **网络友好**：绕开 `.ai` 域名被墙问题，支持走代理

---

## 📁 目录结构

```
tripo-mcp-cn/
├── server.py           # MCP Server（9 个工具 + 代理补丁）
├── requirements.txt    # 4 个依赖
├── .env.example        # 配置模板（复制成 .env 填 Key）
├── output/             # 生成的模型落这里（gitignore，不入库）
├── examples/           # 仓库自带示例：小狐狸 + 鸡块（clone 即可看）
└── viewer/             # 本地 three.js 3D 查看器
    ├── serve.py        #   零依赖 HTTP 服务
    ├── index.html      #   通用查看器
    ├── nugget.html     #   旋转鸡块复刻页
    └── vendor/         #   three.js 库（已本地化，不连外网）
```

---

## 🚀 快速开始（3 步）

### 1. 装依赖

```powershell
pip install -r requirements.txt
```

### 2. 配 Key

复制 `.env.example` 为 `.env`，填入你的 API Key（下面二选一模式）。

**获取 Key**：登录 Tripo 平台 → 头像 → **API Keys** → 创建（`tsk_` 开头，SDK 强校验前缀）。

| 模式 | 平台 | `.env` 关键配置 | 免费额度 |
|---|---|---|---|
| **A. 海外 + 代理**（推荐） | `platform.tripo3d.ai` | `TRIPO_IS_CHINA=false` + 代理变量 | 新用户约 **600 credits** |
| **B. 国内直连** | `platform.tripo3d.com` | `TRIPO_IS_CHINA=true` | 新用户 **0**，需充值 |

> ⚠️ 国内网络直连 `.ai` 域名会被 DNS 污染、访问不了，所以模式 A **必须配本地代理**（FlClash / Clash Verge 等）。这也是本项目给 `server.py` 打 `aiohttp` `trust_env` 补丁的原因——让官方 SDK 自动读取 `HTTPS_PROXY`。

`.env` 示例（模式 A）：

```
TRIPO_API_KEY=tsk_你的key
TRIPO_IS_CHINA=false
HTTPS_PROXY=http://127.0.0.1:7890   # 端口按你的梯子客户端填：FlClash 默认 7890 / Clash Verge 默认 7897
NO_PROXY=localhost,127.0.0.1,.tripo3d.com
```

### 3. 挂到 MCP 客户端

以 Qoder 为例（其它客户端 `mcpServers` 格式通用）：

```json
{
  "mcpServers": {
    "tripo": {
      "command": "python",
      "args": ["绝对路径/tripo-mcp-cn/server.py"]
    }
  }
}
```

- **UI 方式**：Settings → 搜 MCP → Add Server → 粘贴上面配置
- **文件方式**（找不到 UI 时）：直接写进 `~/.qoder` 对应客户端的 `SharedClientCache/mcp.json`，然后 `Ctrl+Shift+P` → **Reload Window**

看到 `tripo` 带 **绿点 ✓** 即接通。之后在对话里直接说「用 Tripo 生成一个 xxx 的 3D 模型」即可。

---

## 🛠 9 个工具

| 工具 | 作用 |
|---|---|
| `get_balance` | 查账户 credits |
| `text_to_3d` | 文本生成 3D，自动等待 + 下载 GLB |
| `image_to_3d` | 图片生成 3D（本地路径或 URL） |
| `get_task` | 查任务状态（不等待） |
| `wait_task` | 阻塞等待任务完成 |
| `download_glb` | 手动下载指定 task_id 的模型 |
| `refine_model` | 精修 draft 模型提升质量 |
| `convert_format` | 转 GLTF/FBX/OBJ/STL/USDZ/3MF |
| `list_output_dir` | 列出已下载文件 |

### 📌 模型版本号（易错点）

`text_to_3d` / `image_to_3d` 的 `model_version` 必须是下列**有效值之一**，写错会报 `code 2017 The version value is invalid`：

| 版本 | 说明 |
|---|---|
| `v3.1-20260211` | **默认推荐**，最新高质量 |
| `P1-20260311` | Preview |
| `v3.0-20250812` | v3.0 正式版 |
| `v2.5-20250123` | SDK 默认值 |
| `Turbo-v1.0-20250506` | 快速模式 |
| `v2.0-20240919` / `v1.4-20240625` | 旧版 |

生成一次 text→3D 约消耗 **20~60 credits**（视面数/版本）。提示词用**英文**效果最好。

---

## 🎮 本地 3D 查看器

生成完直接本地看，**不依赖任何外网**（three.js 已本地化）。

```powershell
cd viewer
python serve.py 8000
```

浏览器开 `http://127.0.0.1:8000` → 左侧列出 `examples/`（自带示例）+ `output/`（你生成的）里的模型，点选即可 360° 旋转、缩放、线框、截图；也可把任意 `.glb` 拖进去看。

🥚 **彩蛋**：访问 `http://127.0.0.1:8000/nugget` 看经典热梗《鸡块旋转四分钟》复刻页（自转 + 大标题 + 计时 + 飘字 + Web Audio 合成 Funky 律动）。

详见 [viewer/README.md](viewer/README.md)。

---

## 🩺 常见问题

**Q: 报 `API key must start with 'tsk_'`**
A: Key 前缀不对，去平台重新生成 `tsk_` 开头的 Key。

**Q: 报 `code 2017 The version value is invalid`**
A: `model_version` 写错了，用上面表格里的有效值之一。

**Q: `get_balance` 返回 0**
A: 国内平台（`.com`）新用户无免费额度。想白嫖走模式 A：注册**海外** `platform.tripo3d.ai`（约 600 credits），配好代理。

**Q: 海外站连不上 / DNS 解析到奇怪 IP**
A: 国内直连 `.ai` 会被污染。确认梯子开着、`HTTPS_PROXY` 端口填对、`TRIPO_IS_CHINA=false`。生成时保持代理在线。

**Q: 生成卡住不动**
A: 任务在服务端跑，正常 60~180 秒。可另调 `get_task(task_id)` 单独查。

**Q: 注册时验证码收不到**
A: 海外站注册需全局邮箱 + 代理 IP 稳定，换节点或换邮箱重试。

---

## 🙏 致谢

- 官方 SDK：[`tripo3d`](https://pypi.org/project/tripo3d/) by VAST / Tripo AI
- 3D 渲染：[three.js](https://threejs.org/)
- 旋转鸡块梗：源自 YouTube CHRISARTS《Nugget SPEENS for 4 Minutes》

## 📄 License

[MIT](LICENSE)