game-asset-mcp

一个 MCP 服务器，让 AI 代理能够端到端地制作可直接用于游戏的 3D 资产——参考图、网格、PBR 纹理、来源记录——并且可以为你已经拥有的网格重新贴图。

大多数资产生成工具止步于"输入提示词，得到网格"。那是简单的一半。真正阻碍项目推进的是你已经拥有的网格：你上周建模的 kitbash 拼搭件、材质不符合你美术方向的市场道具、需要在周五之前看起来像腐蚀钢材的灰盒。texture_existing_asset 接受你提供的网格，为其赋予新的 PBR 材质，而不会重新生成你已经认可的几何体。

一切都有记录。每个任务都会保留提示词、种子、提供商模型版本、提供商任务 ID，以及每个下载字节的 SHA-256——所以六个月后你仍然能回答"这个文件是谁生成的？"

该服务器在设计上就与提供商无关。目前它驱动 Tripo 进行 3D 生成，驱动 Leonardo.Ai 生成参考图，两者都通过两个小型接口（ImageProvider、Model3DProvider）实现。添加提供商不会改变工具表面。参见 docs/architecture.md 了解为何如此构建。

环境要求

• Node.js >= 18.17 —— 服务器使用全局 fetch、FormData、Blob 和 AbortController。

• 无原生模块、无构建工具链、无数据库。它可以在任何能运行 Node 的地方运行。

• 至少一个提供商 API 密钥（参见配置）。一个就够——它们是惰性验证的。

安装

无需永久安装即可运行：

npx game-asset-mcp

或者安装到项目中：

npm install game-asset-mcp

或者从源码构建：

git clone https://github.com/<your-account>/game-asset-mcp.git
cd game-asset-mcp
npm install
npm run build     # emits dist/
node dist/server.js

服务器通过 stdio 进行 MCP 通信。直接在终端中启动时，它会静静地等待客户端与之对话——这是正确行为，不是卡死。日志输出到 stderr；stdout 属于协议。

配置

将 .env.example 复制为 .env，或者在 MCP 客户端的 env 块中设置变量（这通常是更好的选择——参见下面的代码片段）。

⚠️ Tripo API 积分与 Tripo Studio 订阅分开计费

这一点几乎坑了所有人。Tripo Studio 网页订阅不会为 API 调用提供资金。 它们是两个不同的产品，有两个不同的余额。如果你一直在 Studio 网页应用中愉快地生成模型，而你的第一次 create_3d_asset 调用却因积分不足被拒绝，那不是你配置错了——你需要在开发者平台上购买 API 积分。请在 platform.tripo3d.ai 购买，而不是在 Studio 应用中。

一个提供商就够

凭据是惰性验证的——在工具需要它们的那一刻验证，绝不在启动时验证。如果你只设置了 TRIPO_API_KEY，服务器可以正常启动，所有 3D 工具都能工作；图像工具会返回一个明确的 CONFIG_MISSING 错误，指出你缺少的变量。反之亦然。你永远不会被迫为了使用管道中你需要的那一半而持有你不想要的账户。

MCP 客户端设置

Claude Code / Claude Desktop

添加到你的 MCP 配置中（claude_desktop_config.json，或 Claude Code 项目中的 .mcp.json）：

{
  "mcpServers": {
    "game-asset": {
      "command": "node",
      "args": ["/absolute/path/to/game-asset-mcp/dist/server.js"],
      "env": {
        "TRIPO_API_KEY": "tsk_...",
        "LEONARDO_API_KEY": "...",
        "ASSET_OUTPUT_DIR": "/absolute/path/to/your/project/assets/generated",
        "ASSET_LOG_LEVEL": "info"
      }
    }
  }
}

为 args 和 ASSET_OUTPUT_DIR 使用绝对路径。MCP 客户端的工作目录不是你以为的那个目录，相对输出目录会把资产散落到意想不到的地方。

任何其他 MCP 客户端

同一个服务器，以通用方式描述——一个 stdio 子进程：

{
  "name": "game-asset",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "game-asset-mcp"],
  "env": {
    "TRIPO_API_KEY": "tsk_...",
    "LEONARDO_API_KEY": "...",
    "ASSET_OUTPUT_DIR": "/absolute/path/to/assets/generated"
  }
}

可用工具

只有五个工具会花钱，而且每个工具在被调用之前都会在其描述中说明这一点。

示例工作流

完整管道：从想法到已检查的资产

1. generate_asset_reference   → spends image credits, returns assetJobId + N candidates
2. (inspect the images)       → look at the returned reference images and choose one
3. select_reference           → free; records which candidate wins
4. create_3d_asset            → spends 3D credits, returns a task to poll
5. get_asset_job              → free; poll until status is "ready" (or "failed")
6. download_asset             → free; pulls model + textures + previews into the workspace
7. inspect_asset              → free; confirms what actually landed on disk

第 2 步不是装饰。在花费 3D 积分之前选择参考图，正是管道在此处拆分的原因：糟糕的参考图会产生融化的网格，而你只有在支付重建费用之后才会发现这一点。

重新贴图：更短、更便宜，而且是大多数工具没有的流程

你已经有了网格。无需参考、无需选择、无需重建：

1. texture_existing_asset     → spends texturing credits on a mesh you supply
2. get_asset_job              → free; poll until ready
3. download_asset             → free
4. inspect_asset              → free

一次付费调用而不是两次，而且你已经认可的几何体会原样返回。

成本和副作用

消耗提供商积分的调用： generate_asset_reference、generate_reference_variations、create_3d_asset、texture_existing_asset，以及 create_game_prop 内部的图像生成步骤。此服务器中没有任何其他操作会被收费。

免费的调用： select_reference、get_asset_job、download_asset、inspect_asset、list_asset_jobs。想轮询和下载多少次都行。

消耗积分的 POST 请求绝不会自动重试。 这是一个深思熟虑的、承重性的规则，它位于 HTTP 层，而不是每个调用点。当创建生成任务的请求失败时——超时、socket 重置、502——客户端无法判断提供商是否在连接断开之前接受了它。重试可能是免费的；也可能让你为一个从未收到的网格被双重收费。所以它不会重试，错误会直接返回，是否再试一次由你决定。幂等读取——状态轮询、文件下载——可以自由地带退避重试，因为重复执行它们不花任何代价。

其他值得了解的副作用：

• 文件会写入磁盘。 所有内容都落在 ASSET_OUTPUT_DIR 下。不会写入其外部任何内容：路径会被解析，任何逃逸工作区根目录的路径都会被拒绝。

• 不会静默覆盖任何内容。 重名的资产会获得数字后缀（crate、crate_2、……），而不是销毁你可能已经审阅过的结果。

• 下载有上限，上限为 ASSET_MAX_DOWNLOAD_BYTES，并且在流式传输过程中强制执行，而不是依据 Content-Length 头——一个谎报大小的服务器无法耗尽你的内存。

• 仅限 HTTPS。 非 HTTPS URL 会被直接拒绝，包括提供商响应中出现的那些。

• API 密钥会在日志中集中脱敏，因此没有任何单个日志调用点会泄露密钥。

工作区布局

每个资产都有一个自包含的目录。六个月后在文件浏览器中打开它，它仍然能自我解释：

assets/generated/
├── .jobs/                          job records, one JSON file per job
│   └── asset_<uuid>.json
└── <asset_name>/
    ├── asset.json                  complete provenance: spec, prompt, seed,
    │                               model version, provider ids, file hashes
    ├── source/                     the reference image(s) the mesh was built from
    ├── model/                      the mesh (GLB by default)
    ├── textures/                   extracted PBR maps
    ├── previews/                   provider-rendered turnarounds
    └── metadata/                   raw provider payloads, kept for debugging

<asset_name> 是你的规格中的名称，经过清理：小写化，非字母数字字符折叠为下划线。.jobs 目录故意做成点目录——浏览你的资产工作区时应该看到资产，而不是记账数据。

故障排除

每个错误都带有机器可读的 code 和 retryable 标志，因此代理无需解析文字就能决定下一步做什么。

CONFIG_MISSING —— 缺少凭据。 你调用的工具需要你尚未配置的提供商。消息会指出确切的环境变量。在 MCP 客户端的 env 块中设置它并重启客户端——.env 文件只有在服务器的工作目录是你以为的那个目录时才会被读取，而在 MCP 客户端下通常不是。

PROVIDER_HTTP 且状态码为 401/403 —— API 密钥无效。 密钥错误、已被吊销，或者是错误提供商的密钥。两个具体的坑：Leonardo 密钥需要在账户上启用 API 访问权限（仅网页登录不会授予该权限）；而一个没有 API 积分余额的 Tripo 密钥，即使密钥本身有效，也可能在第一次付费调用时失败。参见上面的积分警告。

RATE_LIMITED — HTTP 429。 标记为可重试。轮询和下载会自动退避并重试（400 毫秒、800 毫秒、1600 毫秒，上限为 8 秒）。生成请求则不会——请自行在窗口期结束后重试，并且要有意识地重试，因为这会花费金钱。

PROVIDER_TASK_FAILED — 任务在提供方侧失败。 HTTP 调用成功，但生成未成功。提供方自身的消息会保留在错误详情中。审核拒绝也会落在这里：请重写提示词，而不是原样重试。请注意，Tripo 的响应可能携带 HTTP 200 但信封 code 非零；这属于失败，本服务器会将其视为失败，而不是报告虚假的成功。

下载失败并返回 PROVIDER_HTTP 403/404 — URL 已过期。 这是最常见的意外情况。提供方的模型和预览 URL 是短时效的。 它们经过签名、会过期，二十分钟前还能用的 URL 现在已经失效。解决办法不是重试同一个 URL——而是再次调用 get_asset_job 重新向提供方轮询以获取新 URL，然后立即执行 download_asset。养成习惯：任务一报告 ready 就立即下载，而不是等到长时间会话结束时才下载。

INVALID_INPUT — 不支持的图像格式。 参考图像应为标准的 Web 安全栅格格式（PNG、JPEG、WebP）。HDR、EXR、分层 PSD、SVG 和多页 TIFF 均不可作为可重建的输入。对于 texture_existing_asset，网格必须是 GLB、GLTF、FBX、OBJ 或 STL。请先转换；提供方不会替你完成。

PROVIDER_MALFORMED_RESPONSE — 提供方返回了意外内容。 非 JSON 响应体、空信封、无数据的成功响应，或上传后未返回文件令牌。通常意味着提供方侧事故或 API 版本漂移。设置 ASSET_LOG_LEVEL=debug 可查看请求结构（键已脱敏），并在假设问题出在本地之前，先查看提供方的状态页面。

DOWNLOAD_TOO_LARGE。 文件超过了 ASSET_MAX_DOWNLOAD_BYTES。高质量的 PBR GLB 可能很大；如果你确实需要该文件，请调高限制。

PATH_ESCAPE。 提供方提供的文件名试图解析到你的工作区之外。写入已被拒绝。正常操作中不应发生这种情况——如果发生，请提交 issue。

状态

这是早期软件，最可能发生漂移的部分已明确标注，而不是默默假设其稳定。

Tripo 的 v3 端点路径被固定在一个模块中（src/providers/model3d/tripo.ts），并在该文件顶部的注释中进行了说明。Tripo 的公开文档以两种方式描述 v3 接口——通用任务端点和按操作划分的路径——且两者都出现在当前文档中。本客户端实现的是任务形式，这与可观察到的行为一致：每次生成都会返回一个 task_id 供轮询，并暴露 TRIPO_BASE_URL，以便你无需修改代码即可重新定向。路径是实时冒烟测试首先检查的内容，因为错误的路径会返回 404，看起来与 API 密钥错误完全一样。

从未对真实提供方 API 发起过任何调用。 这是这里最重要的注意事项，因此直接说明，而不是藏起来。全部 165 个测试都针对模拟对象或本地文件系统运行。它们覆盖了提示词构建、状态映射、路径安全、任务存储、HTTP 层的重试和重定向规则，以及针对真实文件的 glTF 检查——但一套全绿的测试套件并不能说明 Leonardo 和 Tripo 的行为是否与本客户端的假设一致。

具体来说，以下内容仍未验证：

• 上述 Tripo v3 端点路径。

• texture_model 是否接受上传的网格（file_token），还是只接受先前 Tripo 任务生成的网格（original_model_task_id）。这决定了你是否能对已拥有的模型重新贴图，而这正是本服务器存在的意义。解决这个问题需要花费一次 HD 贴图调用。

• src/providers/image/leonardo.ts 中的 Leonardo 模型 ID，这些 ID 是从已发布的文档中转录的。请对照 GET /platformModels 进行核对；过期的 ID 会以 HTTP 400 失败，看起来像是格式错误的请求体。LEONARDO_MODEL_ID 和每次调用的 modelId 都作为逃生舱存在。

如果你是第一个使用真实密钥运行此服务器的人，请做好修复端点路径的准备，并请将你的发现提交为 issue。

已验证的内容： npm run verify 会构建服务器，通过 stdio 与真实的 MCP 客户端启动它，完成握手并断言全部十一个工具均已注册。这是协议层面的往返验证，而不是版本字符串——一个未能注册其工具的服务器仍然可以正常启动。

贡献

欢迎提交 issue 和 pull request。如果你要添加提供方，请实现 ImageProvider 或 Model3DProvider，并且不要改动其他任何内容——如果新提供方迫使工具接口发生变化，说明抽象有误，而这正是值得首先讨论的 bug。

许可证

MIT © 2026 Ben Haire。参见 LICENSE。