<p align="center">
  <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/MCP-1.0+-6E47FF?style=flat-square&logo=anthropic&logoColor=white" alt="MCP">
  <img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/Tools-25-FF6B35?style=flat-square" alt="Tools">
</p>

<h1 align="center">Tripo CN MCP Server</h1>

<p align="center">
  <strong>将 Tripo 中国站 3D AI 生成能力无缝接入 MCP 生态</strong>
</p>

<p align="center">
  支持 Codex &middot; Claude Code &middot; Cursor &middot; 及所有兼容 MCP 协议的 AI Agent
</p>

---

> **⚠️ 区域说明**：本 Server 仅兼容 **Tripo 中国站 API**（`openapi.tripo3d.com`），不兼容国际站（`openapi.tripo3d.ai`）。API 端点与字段以本文档和 `docs/` 目录下的官方 PDF 文档为准。

## 目录

- [为什么选择 Tripo CN MCP](#为什么选择-tripo-cn-mcp)
- [功能概览](#功能概览)
- [快速开始](#快速开始)
- [环境变量](#环境变量)
- [MCP 客户端配置](#mcp-客户端配置)
- [典型工作流](#典型工作流)
- [双 Agent 协作](#双-agent-协作)
- [项目结构](#项目结构)
- [测试](#测试)
- [安全](#安全)
- [故障排查](#故障排查)
- [许可证](#许可证)

## 为什么选择 Tripo CN MCP

将 Tripo 3D 生成 API 封装为标准 MCP Server 后，AI Agent 可以直接调用 3D 生成能力——无需手动编写 HTTP 请求、处理认证、轮询任务状态。一次配置，所有兼容 MCP 的 Agent 即时获得 3D 创作能力。

**核心优势：**

- 🎯 **一键集成**：标准 MCP 协议，无需额外适配层
- 🔧 **全端点覆盖**：25 个工具覆盖 Tripo 全部公开 API
- 🛡️ **安全优先**：API Key 防泄漏、SSRF 防护、路径安全检查
- 📦 **开箱即用**：`uv run tripo-cn-mcp` 即可启动

## 功能概览

基于 Tripo 中国站 30 份官方 API 文档完整实现，共 **25 个 MCP 工具**。

### 账户与任务管理

| 工具 | 功能 |
|------|------|
| `tripo_cn_get_balance` | 查询账户余额与冻结额度 |
| `tripo_cn_get_usage` | 查询账户用量历史 |
| `tripo_cn_get_task` | 查询单个任务状态及结果 |
| `tripo_cn_wait_for_task` | 自动轮询直到任务完成（支持取消） |
| `tripo_cn_batch_get_tasks` | 批量查询最多 100 个任务 |

### 3D 模型生成

| 工具 | 功能 |
|------|------|
| `tripo_cn_create_text_to_model_task` | 文本 → 3D 模型（14 个可配置参数） |
| `tripo_cn_create_image_to_model_task` | 图片 → 3D 模型（支持 file_token / URL / task_id） |
| `tripo_cn_create_multiview_to_model_task` | 多视图 → 3D 模型（2-8 张图片） |

### 图像生成

| 工具 | 功能 |
|------|------|
| `tripo_cn_create_text_to_image_task` | 文本 → 图像 |
| `tripo_cn_create_image_to_image_task` | 图像 → 图像 |
| `tripo_cn_create_image_to_multiview_task` | 图像 → 多视图 |
| `tripo_cn_create_edit_multiview_task` | 编辑多视图输出 |

### 模型后处理

| 工具 | 功能 |
|------|------|
| `tripo_cn_create_texture_task` | 模型纹理生成 / 重新生成 |
| `tripo_cn_create_convert_task` | 格式转换（glb / fbx / obj / stl / usdz / step / blend / voxel） |
| `tripo_cn_create_segment_task` | 网格分割 |
| `tripo_cn_create_complete_task` | 网格补全与修复 |
| `tripo_cn_create_decimate_task` | 网格减面 |

### 动画管线

| 工具 | 功能 |
|------|------|
| `tripo_cn_create_rig_check_task` | 检查模型是否可绑定骨骼 |
| `tripo_cn_create_rig_task` | 骨骼绑定（biped / quadruped 等） |
| `tripo_cn_create_retarget_task` | 应用预设动画 |

### 文件与下载

| 工具 | 功能 |
|------|------|
| `tripo_cn_upload_file` | 上传文件获取 file_token（图片 ≤20MB，模型 ≤150MB） |
| `tripo_cn_upload_file_presign` | 大文件预签名上传（>60MB 推荐） |
| `tripo_cn_download_url` | 安全 HTTPS 下载（SSRF 防护 + SHA-256 校验） |
| `tripo_cn_download_from_task` | 从已完成任务自动下载结果 |

### 调试工具

| 工具 | 功能 |
|------|------|
| `tripo_cn_inspect_raw_response` | 本地分析 API 响应 JSON 结构 |

## 快速开始

### 前置要求

- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** — Python 包管理器

### 1. 安装 uv

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 克隆项目

```powershell
git clone https://github.com/<your-username>/tripo-cn-mcp.git
cd tripo-cn-mcp
```

### 3. 安装依赖

```powershell
uv sync --dev
```

### 4. 配置环境变量

```powershell
copy .env.example .env
```

编辑 `.env`，填入你的 API Key：

```ini
TRIPO_CN_API_KEY=你的_Tripo_中国站_API_Key
```

### 5. 启动

```powershell
uv run tripo-cn-mcp
```

Server 通过 STDIO 等待 MCP 协议消息，日志输出到 stderr，不干扰协议通信。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|:--:|------|------|
| `TRIPO_CN_API_KEY` | ✅ | — | Tripo 中国站 API Key |
| `TRIPO_CN_BASE_URL` | — | `https://openapi.tripo3d.com/v3` | API Base URL |
| `TRIPO_CN_OUTPUT_DIR` | — | `~/ExternalGenerated/TripoCN` | 文件输出目录 |
| `TRIPO_CN_REQUEST_TIMEOUT_SECONDS` | — | `60` | HTTP 请求超时（秒） |
| `TRIPO_CN_POLL_INTERVAL_SECONDS` | — | `5` | 任务轮询间隔（秒） |
| `TRIPO_CN_MAX_POLL_SECONDS` | — | `900` | 最大轮询时间（秒） |
| `TRIPO_CN_LOG_LEVEL` | — | `INFO` | 日志级别 |
| `TRIPO_CN_ALLOW_UNITY_ASSETS_WRITE` | — | `false` | 允许写入 Unity Assets |

## MCP 客户端配置

### Codex

编辑 `C:\Users\<用户名>\.codex\config.toml`：

```toml
[mcp_servers.tripo_cn]
command = 'C:\Users\<用户名>\AppData\Roaming\Python\Python314\Scripts\uv.exe'
args = [
  "run",
  "--project",
  "D:\projects\tripo-cn-mcp",
  "tripo-cn-mcp"
]
startup_timeout_sec = 30
tool_timeout_sec = 900
enabled = true

[mcp_servers.tripo_cn.env]
TRIPO_CN_API_KEY = '你的_API_Key'
TRIPO_CN_OUTPUT_DIR = 'D:\ExternalGenerated\TripoCN'
TRIPO_CN_LOG_LEVEL = 'INFO'
```

> ⚠️ 切勿将含有 API Key 的配置提交到 Git。优先使用安全凭据存储。

### Claude Code

编辑项目根目录或用户级 `.mcp.json`，参考 [Claude Code MCP 文档](https://docs.anthropic.com/en/docs/claude-code/mcp) 进行配置。

## 典型工作流

### 文本生成 3D 模型（最常用）

```python
# 1. 提交生成任务
task = await tripo_cn_create_text_to_model_task(
    prompt="a cute cat wearing a spacesuit",
    model="v3.1-20260211",
    texture=True,
    pbr=True
)
# → {"success": true, "task_id": "task_abc123"}

# 2. 等待完成
result = await tripo_cn_wait_for_task(task_id="task_abc123")
# → {"success": true, "status": "success", "model_url": "https://..."}

# 3. 下载结果
download = await tripo_cn_download_from_task(task_id="task_abc123")
# → {"success": true, "absolute_path": "C:/.../model_abc.glb"}
```

### 图片生成 3D 模型 → 动画

```python
# 1. 图片生成模型
img_task = await tripo_cn_create_image_to_model_task(
    input="https://example.com/char.png",
    model="P1-20260311"
)

# 2. 检查可绑定性
rig_check = await tripo_cn_create_rig_check_task(
    input_task_id=img_task.task_id
)
# → riggable: true

# 3. 绑定骨骼
rig_task = await tripo_cn_create_rig_task(
    input_task_id=img_task.task_id,
    rig_type="biped"
)

# 4. 应用动画
anim_task = await tripo_cn_create_retarget_task(
    input_task_id=rig_task.task_id,
    animation="preset:walk"
)
```

### 批量查询

```python
batch = await tripo_cn_batch_get_tasks(
    task_ids=["task_abc123", "task_def456"]
)
# → {"success": true, "tasks": {...}, "missed": []}
```

## 双 Agent 协作

本 MCP Server 专为美术 Agent 设计，与 Unity 开发 Agent 形成流水线：

```
美术 Agent                           Unity 开发 Agent
─────────                           ────────────────
tripo-cn-mcp                        Unity MCP
  │ 生成 3D 模型                      │ 导入模型
  ▼                                  ▼
ExternalGenerated/TripoCN  ────►  Assets/ArtGenerated/Staging
  (暂存目录)     人工/自动审核         (临时资源 → 正式 Prefab)
```

**职责分离：**

| Agent | 职责 |
|-------|------|
| 美术 Agent | 调用生成任务、查询状态、下载结果。不操作 Unity 项目 |
| Unity 开发 Agent | 读取已审核模型、导入 Unity、创建材质和 Prefab。不重新生成 |

## 项目结构

```
tripo-cn-mcp/
├── pyproject.toml             # 项目配置与依赖声明
├── uv.lock                    # 依赖版本锁定
├── README.md
├── .env.example               # 环境变量模板
├── .gitignore
├── docs/                      # 官方 API 文档（30 份 PDF）+ 架构/安全说明
│   ├── architecture.md
│   ├── security.md
│   ├── api-gap-analysis.md
│   └── codex-config.md
├── src/tripo_cn_mcp/
│   ├── __main__.py            # 入口点
│   ├── server.py              # FastMCP STDIO Server（25 个工具注册）
│   ├── settings.py            # pydantic-settings 配置管理
│   ├── client.py              # httpx AsyncClient 封装（含错误码映射）
│   ├── errors.py              # 13 个自定义异常类
│   ├── models/                # Pydantic 数据模型
│   ├── services/              # 业务逻辑（轮询、下载、路径安全）
│   └── tools/                 # MCP 工具实现（按领域拆分）
└── tests/                     # 84 个测试（全部 Mock，零额度消耗）
    └── fixtures/              # JSON 测试夹具
```

## 测试

所有测试均使用 Mock，**不会消耗 Tripo API 额度**。

```powershell
# 运行全部测试
uv run pytest

# 代码检查
uv run ruff check .
uv run ruff format --check .
uv run pyright
```

## 安全

详见 [docs/security.md](docs/security.md)，核心策略：

| 策略 | 说明 |
|------|------|
| 🔑 API Key 保护 | 不出现在日志、异常、MCP 结果中 |
| 🌐 SSRF 防护 | 仅 HTTPS，禁止私有网络访问 |
| 📁 路径安全 | 防路径穿越、防符号链接绕过、同名自动编号 |
| 📥 下载安全 | 流式下载 → 临时文件 → 原子重命名，最大 5GB |
| 🎮 Unity 保护 | 默认禁止写入 Assets，需显式开启 |
| 💰 计费保护 | 测试全部 Mock，零额度消耗 |
| 🚫 无 Shell 执行 | 不调用 `eval()` / `exec()` 或系统命令 |

### 暂存目录

```
~/ExternalGenerated/TripoCN/
├── model_abc.glb              # 生成结果
├── model_abc_1.glb            # 同名自动编号
└── tripo_download_*.tmp       # 下载临时文件（自动清理）
```

## 故障排查

### Server 无法启动

```powershell
# 检查依赖
uv sync --dev

# 验证配置（不显示完整 API Key）
uv run python -c "from tripo_cn_mcp.settings import Settings; s=Settings(); print('OK:', s.masked_dict())"
```

### API 调用失败

1. 确认 `TRIPO_CN_API_KEY` 已正确设置
2. 检查网络是否能访问 `openapi.tripo3d.com`
3. 提高日志级别：`TRIPO_CN_LOG_LEVEL=DEBUG`
4. 使用 `tripo_cn_inspect_raw_response` 调试响应结构

### 下载失败

- 确认 URL 以 `https://` 开头
- 检查输出目录是否可写
- 检查磁盘剩余空间
- 模型 URL 有效期仅 5 分钟，请及时下载

## 许可证

[MIT](LICENSE)

---

<p align="center">
  <sub>Built with ❤️ for the AI Agent ecosystem</sub>
</p>