使用 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 ，您必须将其复制到您的帐户中），并使用模型上下文协议 (MCP)与Claude Desktop等 AI 助手无缝交互。

项目概述

游戏资源生成器( 0.3.0版本) 利用人工智能简化游戏资源的创建。它支持根据文本提示生成2D 资源（例如像素艺术精灵）和3D 资源（例如 OBJ 和 GLB 模型），并与Hugging Face Spaces和模型上下文协议 (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 集成：通过与 MCP 兼容的客户端（如**Claude Desktop）**与工具无缝交互。
文件管理：使用资源 URI（例如， asset://{type}/{id} ）自动保存和组织本地assets目录中的资产。
强大的输入验证：使用Zod进行安全可靠的输入处理。
多客户端支持：通过SSE 传输处理多个同时连接。
安全远程访问：可选的HTTPS支持，实现安全的远程通信。
可扩展的后端：模块化设计，可轻松集成新模型或功能。
跨平台：使用Node.js与 Windows、macOS 和 Linux 兼容。
可配置的 3D 生成：通过环境变量自定义推理步骤、指导规模和涡轮模式等参数。

工作原理

游戏资产生成器通过自动化管道将文本提示转换为可用于游戏的资产：

用户输入：提交文本提示（例如，“像素艺术剑”或“等距 3D 城堡”）。
MCP 服务器：将提示路由到适当的工具（ generate_2d_asset或generate_3d_asset ）。
AI模型交互：
- 2D Assets ：利用"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 ）。
文件输出：将资产（2D 为 PNG，3D 为 OBJ/GLB）保存在assets目录中。
响应：返回资源 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 客户端）用于增强交互。

安装

克隆存储库：
git clone https://github.com/yourusername/game-asset-mcp.git cd game-asset-mcp
安装依赖项：
npm install
配置环境：
- 复制示例.env文件：
  cp .env.example .env
- 使用你的Hugging Face API 令牌和重复的MODEL_SPACE编辑.env文件。详情请参阅配置。
运行服务器：
- 本地（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 ）。
- 复制以下之一：
  - 即时网格
  - 混元3D-2
  - 浑元3D-2mini-Turbo GXP10

可选的 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`

特定空间的默认值

即时网格：
- 步骤：30-75（默认值：75）
- 种子：默认 42
混元3D-2 ：
- 步骤：20-50（默认值：20）
- 指导量表：默认 5.5
- 八叉树分辨率： 256 , 384 , 512 （默认值： 256 ）
- 种子：默认 1234
浑元3D-2mini-Turbo ：
- 步骤：1-100（默认值： Turbo为 5、 Fast为 10、 Standard为 20）
- 指导量表：默认 5.0
- 八叉树分辨率：16-512（默认值：256）
- 种子：默认 1234

传输设置

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

Claude 桌面设置

编辑配置文件：

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 集成

**模型上下文协议 (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 模块错误：确保 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 ）。
- 混元3D-2 ：单步（ /generation_all ）。
- Hunyuan3D-2mini-Turbo ：具有涡轮模式的单步（ /generation_all ）。

版本控制

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

后端架构

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

贡献

欢迎投稿！参与方式：

分叉存储库：在 GitHub 上创建您的副本。
进行更改：添加功能、修复错误或增强文档。
提交拉取请求：详细说明您的更改。
未解决的问题：报告错误或建议改进。

遵循标准编码约定并在适用的情况下进行测试。

执照

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

Game Asset Generator

Integrations