基于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)利用AI技术简化游戏资产创建流程。它支持从文本提示生成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)无缝交互。
文件管理：自动将资产保存并组织到本地assets目录中，并使用资源URI(如asset://{type}/{id})进行管理。
健壮的输入验证：使用Zod进行安全可靠的输入处理。
多客户端支持：通过SSE传输处理多个并发连接。
安全的远程访问：可选的HTTPS支持，确保安全的远程通信。
可扩展的后端：模块化设计，便于集成新模型或功能。
跨平台兼容：使用Node.js，兼容Windows、macOS和Linux。
可配置的3D生成：通过环境变量自定义参数，如推理步骤、引导比例和涡轮模式。

工作原理

游戏资产生成器通过自动化流程将文本提示转换为游戏就绪的资产：

用户输入：提交文本提示(如"像素艺术剑"或"等距3D城堡")。
MCP服务器：将提示路由到适当的工具(generate_2d_asset或generate_3d_asset)。
AI模型交互：
- 2D资产：利用Hugging Face推理API和"gokaygokay/Flux-2D-Game-Assets-LoRA"(50步)。
- 3D资产：
  - 使用"gokaygokay/Flux-Game-Assets-LoRA-v2"(30步)生成初始图像。
  - 将图像转换为3D模型，使用以下工具之一：
    - InstantMesh：多步骤流程(/preprocess、/generate_mvs、/make3d)。
    - Hunyuan3D-2：单步骤流程(/generation_all)。
    - Hunyuan3D-2mini-Turbo：单步骤流程(/generation_all)，支持可配置的涡轮模式。
文件输出：将资产(PNG用于2D，OBJ/GLB用于3D)保存到assets目录。
响应：返回资源URI(如asset://3d_model/filename.glb)，供立即使用。

工作流程图

用户提示 → MCP服务器 → AI模型 → 本地文件 → 资源URI响应

提示会自动增强"高细节、完整对象、未截断、白色纯背景"，以获得最佳质量。

先决条件

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
```
- 编辑.env，填写你的Hugging Face API令牌和复制的MODEL_SPACE。详见配置说明。
运行服务器：
- 本地(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模块("type": "module"在package.json中)。确保安装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)。
- 复制以下之一：
```
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)
- 引导比例：默认5.5
- 八叉树分辨率：256, 384, 512 (默认: 256)
- 种子：默认1234
Hunyuan3D-2mini-Turbo：
- 步骤：1-100 (默认: Turbo=5, Fast=10, Standard=20)
- 引导比例：默认5.0
- 八叉树分辨率：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集成

**模型上下文协议(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)。
- Hunyuan3D-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配额处理。

贡献指南

我们欢迎贡献！参与方式：

Fork仓库：在GitHub上创建你的副本。
进行更改：添加功能、修复错误或增强文档。
提交Pull请求：详细说明你的更改。
提交问题：报告错误或提出改进建议。

遵循标准编码规范，并在适用时包含测试。

许可证

根据MIT许可证授权。详见LICENSE文件。