Game Asset Generator using MCP and Hugging Face Spaces

项目所有者很快会查看此代码库，预计于 2026 年 6 月更新

使用 MCP 和 Hugging Face Spaces 生成游戏资源

本项目是一款创新工具，借助 AI 驱动的生成技术，简化游戏资源的创作过程。无论你是希望快速制作原型的游戏开发者，还是探索生成模型的 AI 爱好者，都可以轻松地通过文本提示词创建 2D 和 3D 游戏资源。该工具集成了来自 Hugging Face Spaces 的 AI 模型，由 "gokaygokay/Flux-2D-Game-Assets-LoRA"、"gokaygokay/Flux-Game-Assets-LoRA-v2" 以及三个 3D 模型生成空间之一（InstantMesh、Hunyuan3D-2 或 Hunyuan3D-2mini-Turbo，你必须将其复制到自己的账户）提供支持，并使用 Model Context Protocol (MCP) 与 Claude Desktop 等 AI 助手无缝交互。

---

目录

1. 项目概述
2. 功能
3. 工作原理
4. 前置条件
5. 安装
6. 使用方法
7. 配置
8. 文件管理
9. MCP 集成
10. 故障排除
11. 高级用法
12. 贡献
13. 许可证

---

项目概述

Game Asset Generator（版本 0.3.0）利用 AI 简化游戏资源的创建流程。它支持根据文本提示词生成 2D 资源（例如，像素艺术精灵）和 3D 资源（例如，OBJ 和 GLB 模型），并与 Hugging Face Spaces 和 Model Context Protocol (MCP) 集成。此版本新增了对多个 3D 模型生成空间的支持——InstantMesh、Hunyuan3D-2 和 Hunyuan3D-2mini-Turbo，提供更大的灵活性和更出色的性能。该项目使用 Node.js 和 MCP TypeScript SDK (v1.7.0) 构建，为资源生成提供了可靠的跨平台解决方案。

---

功能

• 2D 资源生成：根据文本提示词创建像素艺术、精灵或其他 2D 资源（例如，“像素艺术剑”）。
• 3D 资源生成：根据文本描述生成 3D 模型（OBJ 和 GLB 格式），并自动将图像转换为模型。
• 多个 3D 模型空间：支持 InstantMesh、Hunyuan3D-2 和 Hunyuan3D-2mini-Turbo，适用于各种 3D 生成工作流。
• MCP 集成：通过 Claude Desktop 等兼容 MCP 的客户端与工具无缝交互。
• 文件管理：自动将资源保存并整理到本地 assets 目录中，并提供资源 URI（例如，asset://{type}/{id}）。
• 可靠的输入验证：使用 Zod 确保输入处理安全可靠。
• 多客户端支持：通过 SSE transport 处理多个并发连接。
• 安全的远程访问：可选支持 HTTPS，确保远程通信安全。
• 可扩展后端：采用模块化设计，便于集成新模型或功能。
• 跨平台：使用 Node.js，兼容 Windows、macOS 和 Linux。
• 可配置的 3D 生成：通过环境变量自定义推理步数、引导比例和 Turbo 模式等参数。

---

工作原理

Game Asset Generator 通过自动化工作流将文本提示词转换为可用于游戏的资源：

1. 用户输入：提交文本提示词（例如，“像素风格的剑”或“等距视角的 3D 城堡”）。
2. MCP 服务：将提示词路由到相应的工具（generate_2d_asset 或 generate_3d_asset）。
3. AI 模型交互：
   • 2D 资源：使用 "gokaygokay/Flux-2D-Game-Assets-LoRA" 调用 Hugging Face Inference API（50 步）。
   • 3D 资源：
     • 使用 "gokaygokay/Flux-Game-Assets-LoRA-v2" 生成初始图像（30 步）。
     • 使用以下任一方式将图像转换为 3D 模型：
       • InstantMesh：多步处理（/preprocess、/generate_mvs、/make3d）。
       • Hunyuan3D-2：单步处理（/generation_all）。
       • Hunyuan3D-2mini-Turbo：单步处理（/generation_all），支持配置 Turbo 模式。
4. 文件输出：将资源（2D 为 PNG，3D 为 OBJ/GLB）保存到 assets 目录。
5. 响应：返回资源 URI（例如，asset://3d_model/filename.glb），供立即使用。

工作流图

User Prompt → MCP Server → AI Model(s) → Local File → Resource URI Response

系统会自动为提示词添加“高细节、完整对象、未被裁切、纯白背景”，以获得最佳质量。

---

前置条件

• Node.js：16+ 版本（包含 npm）。
• Git：用于克隆代码库。
• 互联网访问：调用 Hugging Face API 所必需。
• Hugging Face 账号：访问 API 所需；请从 huggingface.co/settings/tokens 获取令牌。
• NPM 包：
  • @gradio/client：与 Hugging Face Spaces 交互。
  • @huggingface/inference：用于直接进行模型推理。
  • @modelcontextprotocol/sdk：实现 MCP 服务。
  • dotenv：加载环境变量。
  • express：启用 SSE 传输。
  • zod：确保输入经过验证。
  • sharp：处理图像。
• 可选：Claude Desktop（或其他 MCP 客户端），以获得更好的交互体验。

---

安装

1. 克隆代码库：

   git clone https://github.com/yourusername/game-asset-mcp.git
   cd game-asset-mcp
   

2. 安装依赖：

   npm install
   

3. 配置环境：

   • 复制示例 .env 文件：

     cp .env.example .env
     

   • 在 .env 中填写你的 Hugging Face API 令牌和重复的 MODEL_SPACE。详情请参阅配置。

4. 运行服务：

   • 本地（stdio 传输）：

     npm start
     

   • 自定义工作目录：

     node src/index.js /path/to/directory
     

   • 远程（SSE 传输）：

     node src/index.js --sse
     

   • 通过 HTTPS 远程运行：

     node src/index.js --sse --https
     

     需要 ssl/key.pem 和 ssl/cert.pem（请参阅 ssl/README.md）。

注意：使用 ES 模块（package.json 中的 "type": "module"）。请确保已安装 Node.js 16+（node --version）。

---

用法

通过 MCP 客户端（例如 Claude Desktop）或以编程方式与服务交互：

• 生成 2D 资源：

  • 命令：generate_2d_asset prompt:"pixel art sword"
  • 输出：保存 PNG 文件（例如，2d_asset_generate_2d_asset_1698765432.png）并返回其 URI。

• 生成 3D 资源：

  • 命令：generate_3d_asset prompt:"isometric 3D castle"
  • 输出：保存 OBJ/GLB 文件和中间图像，并返回其 URI。对于长时间运行的任务，还会提供操作 ID。

提示词示例

• 自然交互：
  • generate_2d_sprite prompt:"pixel art sword"
  • generate_3d_model prompt:"isometric 3D castle"

使用 Claude Desktop

完成配置后（请参阅配置），直接在界面中输入命令。

---

配置

通过 .env 文件自定义服务：

必需设置

• HF_TOKEN：Hugging Face API 令牌。

  HF_TOKEN=your_hf_token
  

• MODEL_SPACE：你复制的 3D 模型空间（例如，your-username/InstantMesh）。
  • 复制以下任意一个：
    • InstantMesh
    • Hunyuan3D-2
    • Hunyuan3D-2mini-Turbo

  MODEL_SPACE=your-username/InstantMesh
  

可选 3D 模型设置

变量	说明	有效范围/默认值
MODEL_3D_STEPS	推理步数	因空间而异（见下文）
MODEL_3D_GUIDANCE_SCALE	模型遵循提示词的程度	0.0-100.0（默认值：5.0-5.5）
MODEL_3D_OCTREE_RESOLUTION	3D 模型的细节级别	因空间而异（见下文）
MODEL_3D_SEED	随机性控制	0-10000000（默认值：因空间而异）
MODEL_3D_REMOVE_BACKGROUND	移除图像背景	true/false（默认值：true）
MODEL_3D_TURBO_MODE	生成模式（仅适用于 Hunyuan3D-2mini-Turbo）	Turbo、Fast、Standard（默认值：Turbo）
MODEL_SPACE_TYPE	覆盖空间类型检测	instantmesh、hunyuan3d、hunyuan3d_mini_turbo

特定空间的默认值

• InstantMesh：
  • 步数：30-75（默认值：75）
  • 种子：默认值 42
• Hunyuan3D-2：
  • 步数：20-50（默认值：20）
  • Guidance Scale：默认值 5.5
  • Octree Resolution：256、384、512（默认值：256）
  • 种子：默认值 1234
• Hunyuan3D-2mini-Turbo：
  • 步数：1-100（Turbo 默认值为 5，Fast 默认值为 10，Standard 默认值为 20）
  • Guidance Scale：默认值 5.0
  • Octree Resolution：16-512（默认值：256）
  • 种子：默认值 1234

传输设置

• PORT：SSE 传输端口（默认值：3000）。

  PORT=3000
  

Claude Desktop 设置

编辑配置文件：

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "game-asset-generator": {
      "command": "node",
      "args": ["/full/path/to/game-asset-mcp/src/index.js"]
    }
  }
}

编辑后重启 Claude Desktop。

---

文件管理

• 存储位置：资源保存在工作目录中的 ./assets。
• 命名约定：文件名由前缀、工具名称、时间戳和唯一 ID 组成（例如，2d_asset_generate_2d_asset_1698765432_abcd1234.png）。
• 自定义：设置自定义目录：

  node src/index.js /path/to/custom/directory
  

• 资源访问：使用 MCP URI（例如，asset://2d_asset/filename.png）列出或读取资源。

---

MCP 集成

Model Context Protocol (MCP) 使此工具能够安全地为 AI 客户端提供服务：

• 工具：generate_2d_asset、generate_3d_asset。
• 资源：通过 asset:// URI 管理。
• 提示词：generate_2d_sprite、generate_3d_model。
• 兼容性：可与 Claude Desktop 及其他 MCP 客户端配合使用。

---

故障排除

• API 错误：检查网络连接或速率限制；查看 ./logs/server.log。
• 身份验证问题：检查 .env 中的 HF_TOKEN 和 MODEL_SPACE。
• ES Modules 错误：确保使用 Node.js 16+（node --version）。
• 日志：查看详细日志：

  tail -f ./logs/server.log
  

---

高级

API 端点和集成

• 2D 资源生成：使用 "gokaygokay/Flux-2D-Game-Assets-LoRA"（50 步）。
• 3D 资源图像生成：使用 "gokaygokay/Flux-Game-Assets-LoRA-v2"（30 步）。
• 3D 模型转换：
  • InstantMesh：多步骤（/check_input_image、/preprocess、/generate_mvs、/make3d）。
  • Hunyuan3D-2：单步骤（/generation_all）。
  • Hunyuan3D-2mini-Turbo：单步骤（/generation_all），支持 Turbo 模式。

版本管理

• 当前版本：0.3.0（新增 Hunyuan3D-2mini-Turbo 支持）。
• MCP SDK 版本：1.7.0。
• 格式：MAJOR.MINOR.PATCH（SemVer）。

后端架构

• 核心文件：src/index.js。
• 依赖项：请参阅 package.json。
• 安全性：Zod 验证、防止路径遍历、支持 HTTPS、速率限制。
• 性能：异步处理、带退避机制的重试、GPU 配额处理。

---

贡献

欢迎贡献！参与方式：

1. Fork 仓库：在 GitHub 上创建自己的副本。
2. 进行更改：添加功能、修复错误或完善文档。
3. 提交拉取请求：详细说明更改内容。
4. 提交问题：报告错误或提出改进建议。

请遵循标准编码规范，并在适用时添加测试。

---

许可证

本项目根据 MIT 许可证授权。详情请参阅 LICENSE 文件。