game-asset-mcp

🚀 游戏资产管理工具

该游戏资产生成器是基于Node.js的工具，借助MCP协议为游戏生成2D和3D资产，并且与Claude桌面版等MCP客户端兼容，能有效提升游戏资产的生成效率。

🚀 快速开始

游戏资产生成器是一个基于Node.js的工具，支持通过MCP协议为游戏生成2D和3D资产。以下是快速开始的步骤：

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 启动服务：

   • 默认在./logs/server.log记录日志，资产存储于./assets

     node src/index.js
     

   • 指定自定义目录：

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

✨ 主要特性

核心功能

• 2D资产生成：使用"gokaygokay/Flux-2D-Game-Assets-LoRA"模型（50步）
• 3D资产图像生成：使用"gokaygokay/Flux-Game-Assets-LoRA-v2"模型（30步）
• 多模型支持：
  • InstantMesh
  • Hunyuan3D-2
  • Hunyuan3D-2mini-Turbo

运行时配置

通过.env文件配置以下参数：

HF_TOKEN=你的HuggingFace令牌
MODEL_SPACE=模型空间名称（例如：gokaygokay/Flux）
PORT= SSE传输端口，默认为3000

📦 安装指南

克隆与依赖安装

1. 克隆仓库到本地：

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

2. 安装项目所需依赖：

   npm install
   

启动服务

• 默认启动，日志记录在./logs/server.log，资产存储于./assets：

  node src/index.js
  

• 指定自定义资产存储目录启动：

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

💻 使用示例

命令行接口

启动服务

node src/index.js

指定存储目录

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

配置文件

编辑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桌面版后生效。

教程示例

示例1：生成2D资产

curl -X POST http://localhost:3000/generate/2d \
  -H "Content-Type: application/json" \
  -d '{"prompt": "一只可爱的小猫"}'

示例2：生成3D资产

curl -X POST http://localhost:3000/generate/3d \
  -H "Content-Type: application/json" \
  -d '{"prompt": "一个未来城市的全景图"}'

📚 详细文档

文件管理

存储位置

资产存储于./assets目录，按以下命名规则组织：

2d_asset_generate_2d_asset_<timestamp>_<unique_id>.png

资源访问

使用MCP URI格式：

• 列举资源：asset://2d_asset/
• 访问文件：asset://2d_asset/filename.png

高级功能

API端点

• 2D资产生成：

  • 端点：POST /generate/2d
  • 参数：{ prompt: "描述你的需求" }

• 3D资产生成：

  • 端点：POST /generate/3d
  • 参数：{ prompt: "描述你的需求" }

错误处理

• 401未授权：缺少或无效的HuggingFace令牌
• 500内部错误：模型推理失败
• 429速率限制：超出API调用次数限制

常见问题

• Q: 如何提高生成速度？

• A: 使用更高性能的模型或优化网络带宽。

• Q: 资源存储目录在哪里？

• A: 默认为./assets，可通过启动参数指定。

• Q: 支持哪些3D格式？

• A: 当前支持obj、gltf、png等常见格式。

开发指南

模块开发

1. 新增2D生成器：

   npm run dev 2d
   

2. 新增3D生成器：

   npm run dev 3d
   

贡献指南

• 提交代码前，请确保通过所有测试用例。
• 遵循 eslint和 prettier的代码规范。

🔧 技术细节

核心模块

• src/index.js：主服务入口
• src/api/：API路由处理
• src/models/：模型加载与推理
• src/storage/：资产存储管理

技术选型

• 框架：Express.js
• 模型管理：HuggingFace Inference API
• 日志记录：默认输出至文件，支持自定义 logger

📄 许可证

本项目遵循MIT许可证，详细内容请查看LICENSE文件。

⚠️ 重要提示

禁止在.env文件中明文存储敏感信息，定期更新HuggingFace令牌，并配置防火墙限制外部访问。

💡 使用建议

如果需要提高生成速度，可使用更高性能的模型或优化网络带宽。