游戏资源MCP

Name: 游戏资源MCP
Author: MubarakHAlketbi

作者：MubarakHAlketbi95 星标更新：2025-03-23

安装使用来源：spider==github.com

项目介绍

技术文档摘要

使用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），带有可配置的涡轮模式。
文件输出：将资产（2D为PNG，3D为OBJ/GLB）保存在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:"像素艺术剑"
- 输出：保存PNG文件（例如2d_asset_generate_2d_asset_1698765432.png）并返回其URI。
生成3D资产：
- 命令：generate_3d_asset prompt:"等距3D城堡"
- 输出：保存OBJ/GLB文件及中间图像，返回它们的URI。提供操作ID以跟踪长时间任务。

提示示例

自然交互：
- generate_2d_sprite prompt:"像素艺术剑"
- generate_3d_model prompt:"等距3D城堡"

使用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（语义化版本）。

后端架构

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

贡献

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

分叉仓库：在GitHub上创建您的副本。
修改代码：添加功能，修复bug，或改进文档。
提交拉取请求：详细说明您的更改。
报告问题：报告bug或提出改进建议。

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

许可证

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