HelloWorld
登录
游

游戏资产生成器MCP

一个MCP服务器，它使用来自Hugging Face Spaces的AI模型从文本提示生成2D和3D游戏资源，使开发人员能够通过Claude Desktop或其他MCP客户端轻松创建游戏艺术。

image-and-video-processingdeveloper-toolsgames-and-gamification

658 查看 · 2026-07-07 更新

简介

一个MCP服务器，它使用来自Hugging Face Spaces的AI模型从文本提示生成2D和3D游戏资源，使开发人员能够通过Claude Desktop或其他MCP客户端轻松创建游戏艺术。

简介

一个MCP服务器，它使用来自Hugging Face Spaces的AI模型从文本提示生成2D和3D游戏资源，使开发人员能够通过Claude Desktop或其他MCP客户端轻松创建游戏艺术。

使用 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 助手无缝交互。

支持我 - 捐赠 构建使用 - Roo Code

目录

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

项目概述

游戏资产生成器（版本 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 集成: 通过兼容 MCP 的客户端（如 Claude Desktop）无缝交互。
  • 文件管理: 自动保存并将资源组织在本地 assets 目录中，并提供资源 URI（例如，asset://{type}/{id}）。
  • 强大的输入验证: 使用 Zod 进行安全可靠的输入处理。
  • 多客户端支持: 通过 SSE 传输 处理多个同时连接。
  • 安全远程访问: 可选的 HTTPS 支持，用于安全的远程通信。
  • 可扩展后端: 模块化设计，便于集成新模型或功能。
  • 跨平台: 使用 Node.js 兼容 Windows、macOS 和 Linux。
  • 可配置的 3D 生成: 通过环境变量自定义参数，如推理步骤、引导比例和涡轮模式。

工作原理

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

  1. 用户输入: 提交一个文本提示（例如，“像素艺术剑”或“等距 3D 城堡”）。
  2. MCP 服务器: 将提示路由到适当的工具（generate_2d_asset 或 generate_3d_asset）。
  3. AI 模型交互:
    • 2D 资源: 使用 Hugging Face Inference 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），支持可配置的涡轮模式。
  4. 文件输出: 在 assets 目录中保存资源（2D 为 PNG，3D 为 OBJ/GLB）。
  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
    • 使用您的 Hugging Face API 令牌 和复制的 MODEL_SPACE 编辑 .env 文件。详情请参见 配置。

  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 模块 ("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_RESOLUTION3D模型的细节级别根据空间变化（见下文）
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桌面设置

编辑配置文件：

  • 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 模块错误: 确保 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 配额处理。

贡献

我们欢迎贡献！要参与，请执行以下步骤：

  1. 分叉仓库: 在 GitHub 上创建你的副本。
  2. 进行更改: 添加功能、修复错误或增强文档。
  3. 提交拉取请求: 详细说明你的更改。
  4. 提出问题: 报告错误或建议改进。

请遵循标准编码规范，并在适用的情况下包含测试。

许可

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

服务配置

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

来源