# Tripo Studio MCP

本项目把使用者自己的 Tripo Studio 会员账号接入 Codex。它覆盖图片、3D 模型、模型后处理、绑骨与动画，并把输入和结果自动下载到本机私有画廊。

> 本项目不是 Tripo 官方产品，使用的是 Studio 网页当前采用的接口；网页契约变化时需要更新插件。

## 主要能力

- 图片生成：提示词、参考图、动态模板、五种比例、1–4 张、1K/4K、重新生成；
- 图片四视图：从 Studio 图片输出生成 front、left、back、right 四视图；
- 3D 生成：`smart_mesh` 智能网格与 `high_detail` 高精度模型，支持文字、本地单图、本地多视图和 Studio 图片；
- 模型目录：列出模型、读取缩略图、部件、能力与动画预设；未归档模型可临时下载当前 GLB 解析部件；
- 模型导入：GLB、OBJ、FBX、STL；只归档输入与导入结果，不创建或显示质检区；
- 几何处理：部件拆分、部件补全、Triangle/Quad/Smart Poly 重拓扑；
- 纹理处理：文字/单图/多视图纹理、纹理编辑预览与应用、4K/8K 放大、PBR；
- 自动 UV：生成纹理前检测 UV；GLB 缺失 UV 时用 xatlas 补齐，OBJ/FBX/STL 缺失 UV 时交由 Studio 展开，并在付费提交前复核；
- 角色处理：自动绑骨与动画重定向；
- 本地归档：成功结果、输入快照和脱敏参数自动进入仅本机可访问的网页画廊；
- 视觉质检：图片生成直接复用或合成带标签总览，模型生成与后处理自动生成九视角总览，动画自动选取代表姿态；纯模型导入不质检。

## 为效率设计

插件公开 16 个短而明确的工具。所有创建与处理都通过可组合的 `Workflow` 完成：先读取能力目录，再提交一个或多个 Operation 步骤，立即取得 `workflow_id`，随后按需查询本地记录。

共享的单例 MCP 服务负责：

- 每个账号从 3 个远端任务并发开始，按明确接受和 `busy`/429 响应在 3–10 之间自适应调整；
- 同一模型或项目的修改自动串行；
- 登录状态巡检与掉线自动恢复；
- 结果下载、校验和画廊归档；
- 本地视觉质检的排队、缓存、失败降级和最多 2 个渲染任务并发；
- 最后一条 Bootstrap life 连接断开后，MCP backend 立即开始有界优雅关闭：停止接收新请求、关闭服务及其拥有的无头浏览器；
- 已经提交到远端的任务不会重提，下次启动后从本地账本恢复跟踪。

并发数不在工具参数中，使用者和代理都不需要管理。

## 单例运行架构

插件为每个 Codex 任务启动一个轻量 stdio Bootstrap；Bootstrap 自动启动或复用唯一的回环 HTTP MCP backend：

```text
Codex 任务 A → stdio Bootstrap A ─┐
Codex 任务 B → stdio Bootstrap B ─┼─> 127.0.0.1 HTTP MCP Backend
Codex 任务 N → stdio Bootstrap N ─┘          └─ 唯一 runtime：账号、无头浏览器、Workflow、调度、下载和画廊
```

- backend 以全局实例锁保证同一操作系统用户只有一个实例；Bootstrap 从同一份源码公共注册表静态公开 MCP 工具 schema，再把实际调用转发到唯一 runtime，不复制业务状态。
- 工具发现和后台可用性是两项独立验收：`tools/list` 必须等于公共注册表；只读工具调用才证明 backend 已可用。后台启动、版本或 life 连接失败时，工具会返回明确的本机 MCP 错误，而不是由 Skill 伪装为可用。
- 服务固定拥有一个无头 Chrome 和专用 profile；关闭服务时会等待本地调用排空，再关闭浏览器和释放锁。
- Bootstrap 带版本请求头，安装更新后不会让新客户端调用旧服务。更新先排空并停止旧服务，替换 bundle 后由下一次新任务自动启动新版本。
- 已发出的创建或修改请求绝不自动重放；结果不明确时仍按 `outcome_unknown` 处理。服务下次启动只恢复已有账本记录，不重新提交远端任务。

## 快速安装

在目标电脑的 Codex 桌面版中新建任务，粘贴：

```text
阅读 https://raw.githubusercontent.com/Ador-able/tripo-studio-mcp/main/INSTALL.md，并按文档在本机安装 Tripo Studio 插件。
```

安装采用仓库内的 Git marketplace：

```text
.agents/plugins/marketplace.json
```

完整流程见 [INSTALL.md](INSTALL.md)。

## 基本用法

1. 首次使用或换账号时调用 `tripo_set_account`。插件只保存一个账号，新账号验证成功后覆盖旧账号。
2. 调用 `tripo_get_workflow_capabilities`，根据返回的 JSON Schema 组合一个或多个 Operation 步骤。
3. 调用 `tripo_start_workflow`，它只校验、写入本地队列并立即返回 `workflow_id`；不要等待远端任务。
4. 通过 `tripo_get_workflow`、`tripo_list_workflows` 和 `tripo_get_workflow_log` 查询进度、结果与失败详情。需要从头重提时由用户明确调用 `tripo_retry_workflow`。
5. 需要查看全部输入和结果时调用 `tripo_open_gallery`；画廊服务本身已经随后台启动。

换号成功时，旧账号所有非终态 Workflow 会立即在本地标记为 `failed`，原账号的远端任务不会被取消、轮询、对账或自动重提。重试会创建新的 Workflow ID，并可能再次消耗额度。所有任务共用当前账号学习到的 3–10 并发上限。

`model.generate` Operation 的 `tier` 参数区分两种生成模式：

- `smart_mesh`：智能网格，面向游戏和 Web 资产；
- `high_detail`：高精度模型。

余额只在使用者明确查询状态时读取，不参与创建流程或结果判断。Studio 返回错误码 `2010` 时，Workflow 以 `INSUFFICIENT_CREDITS` 失败且不会自动重试。

## 工具分组

- 账号与状态：`tripo_get_status`、`tripo_set_account`、`tripo_clear_account`
- 目录与画廊：`tripo_list_models`、`tripo_get_model`、`tripo_list_images`、`tripo_get_image`、`tripo_list_templates`、`tripo_open_gallery`
- Workflow：能力目录、启动、读取、列表、运行日志、取消、从头重试

完整工具名清单由构建生成在 [plugins/tripo-studio-mcp/TOOL_INVENTORY.md](plugins/tripo-studio-mcp/TOOL_INVENTORY.md)；参数以 MCP 返回的工具 schema 为准。

## 项目结构

```text
.agents/plugins/marketplace.json       Git marketplace
plugins/tripo-studio-mcp/              可直接安装的 Codex 插件
src/                                   TypeScript 源码
tests/                                 离线测试
scripts/build-plugin.mjs               生成自包含插件
```

插件包中的 `mcp/server.mjs` 是构建产物；安装时不需要在插件目录运行 `npm install`。

## 给 Java 开发者的源码阅读路线

建议按下面的顺序阅读 `src/`，先建立调用链，再深入某个业务模块：

1. `index.ts`、`runtime/singleton-server.ts`、`server.ts`：唯一回环 HTTP MCP 服务如何启动、管理会话并直接路由工具；
2. `runtime/core.ts`、`workflows/service.ts`、`actions/service.ts`：工具调用如何变成 Workflow，内部 Action 如何被后台调度；
3. `public-api/schemas.ts`、`public-api/types.ts`：对外参数、返回值和工具注册表；
4. `image-generation/`、`model-generation/`、`operations/`、`texture-pipeline/`：各类具体业务；
5. `studio/`、`auth/`、`artifacts/`：网页接口、登录和文件下载等基础设施。

代码中的中文注释会在首次出现时说明几个 TypeScript 概念：`interface` 和 `type` 都只在编译期存在，类似 Java 的类型声明；`Promise<T>` 可把它理解为 `CompletableFuture<T>`；`unknown` 类似必须先校验/转换后才能使用的 `Object`；Zod schema 则承担运行时 DTO 校验职责。

## 本地开发

要求 Node.js 22 或更高版本：

```powershell
npm ci
npm run verify
```

常用命令：

```powershell
npm run check
npm test
npm run plugin:build
npm run plugin:check
npm run test:plugin
```

修改源码、依赖或工具后必须运行 `npm run plugin:build`。不要手工编辑构建生成的 `server.mjs`、`browsers.json`、`TOOL_INVENTORY.md`、许可证副本或第三方声明。

## 进一步阅读

- [安装与本机重装](INSTALL.md)
- [安全边界](SECURITY.md)
- [贡献与验证](CONTRIBUTING.md)