Game Asset MCP

使用MCP和拥抱面部空间的游戏资产生成器

该项目是一个创新工具，通过利用人工智能发电简化游戏资产创建。无论您是寻求快速原型的游戏开发人员，还是探索生成模型的人工智能爱好者，此工具都可以让您创建 第2天 和 3D游戏资产 轻松地从文本提示中提取。它整合了来自 拥抱面部空间--电源由 "gokaygokay/Flux-2D-Game-Assets-LoRA", "gokaygokay/Flux-Game-Assets-LoRA-v2"，以及三个3D模型生成空间之一(InstantMesh, Hunyuan3D-2，或 Hunyuan3D-2mini-Turbo，您必须将其复制到您的帐户）--并使用 模型上下文协议（MCP） 用于与AI助手进行无缝交互，例如 克劳德桌面.

______________________________________________________________________

目录

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

______________________________________________________________________

项目概述

这 游戏资产生成器 （版本 0.3.0)利用人工智能简化游戏资产的创建。它支持生成 二维资产 （例如，像素艺术精灵）以及 3D资产 （例如，OBJ和GLB模型）从文本提示中，与 拥抱面部空间 和那个 模型上下文协议（MCP）此版本引入了对多个3D模型生成空间的支持--InstantMesh, Hunyuan3D-2，以及 Hunyuan3D-2mini-Turbo--提供灵活性和增强的性能。内置于 Node.js 和那个 MCP TypeScript SDK（v1.7.0），它为资产生成提供了一个强大的跨平台解决方案。

______________________________________________________________________

特性

• 二维资产生成：根据文本提示创建像素艺术、精灵或其他二维资源（例如“像素艺术剑”）。
• 3D资产生成：从文本描述生成3D模型（OBJ和GLB格式），并自动进行图像到模型的转换。
• 多个三维模型空间：支持 InstantMesh, Hunyuan3D-2，以及 Hunyuan3D-2mini-Turbo 用于各种3D生成工作流程。
• MCP集成：通过MCP兼容的客户端与工具无缝交互，如 克劳德桌面.
• 文件管理：在本地自动保存和组织资产 assets 具有资源URI的目录（例如。， asset://{type}/{id}).
• 稳健的输入验证：用途 萨德 用于安全可靠的输入处理。
• 多客户端支持：通过以下方式处理多个同时连接 SSE 运输.
• 安全远程访问：可选 超文本传输安全协议 支持安全的远程通信。
• 可扩展后端：模块化设计，便于集成新型号或功能。
• 交叉平台的：使用与Windows、macOS和Linux兼容 Node.js.
• 可配置的3D生成：通过环境变量自定义推理步骤、制导规模和涡轮模式等参数。

______________________________________________________________________

运作原理

游戏资源生成器通过自动化管道将文本提示转换为游戏就绪资源：

1. 用户输入：提交文本提示（例如，“像素艺术剑”或“等距3D城堡”）。
2. MCP服务器：将提示路由到相应的工具(generate_2d_asset 或 generate_3d_asset).
3. AI模型交互:

- 二维资产：利用 拥抱面部推理API 随着 "gokaygokay/Flux-2D-Game-Assets-LoRA" （50步）。 - 3D资产: - 使用生成初始图像 "gokaygokay/Flux-Game-Assets-LoRA-v2" （30步）。 - 使用以下方法之一将图像转换为三维模型： - InstantMesh：多步骤过程(/preprocess, /generate_mvs, /make3d). - 浑源3D-2：单步过程(/generation_all). - 浑源3D-2微型涡轮：单步过程(/generation_all)具有可配置的涡轮模式。

1. 文件输出：将资产（PNG用于2D，OBJ/GLB用于3D）保存在 assets 目录。
2. 响应：返回资源URI（例如。， asset://3d_model/filename.glb)立即使用。

工作流程图

User Prompt → MCP Server → AI Model(s) → Local File → Resource URI Response

提示会自动增强为“高细节、完整的对象、不截断的白色实心背景”，以获得最佳质量。

______________________________________________________________________

先决条件

• Node.js：16+版本（包括 npm).
• Git：用于克隆存储库。
• 互联网接入：用于拥抱面部API连接。
• 拥抱脸账户：API访问需要；从以下位置获取您的令牌 huggingface.co/settings/tokens.
• NPM包:

- @gradio/client：与拥抱脸部空间互动。 - @huggingface/inference：用于直接模型推理。 - @modelcontextprotocol/sdk：实现MCP服务器。 - dotenv：加载环境变量。 - express：启用SSE传输。 - zod：确保输入验证。 - sharp：处理图像处理。

• 可选的: 克劳德桌面 （或另一个MCP客户端）以增强交互。

______________________________________________________________________

安装

1. 克隆存储库:

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

1. 再进行:

   npm install

1. 配置环境:

- 复制示例 .env 文件：

     cp .env.example .env

- 编辑 .env 与你的 拥抱脸API代币 并复制 模型空间。参见 配置 了解详情。

1. 运行服务器:

- 本地（标准传输）:

     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）或以编程方式：

• 生成二维资源:

- 命令: generate_2d_asset prompt:"pixel art sword" - 输出保存一个PNG文件(例如, 2d_asset_generate_2d_asset_1698765432.png)并返回其URI。

• 生成三维资源:

- 命令: 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"

使用克劳德桌面

配置后（请参阅 配置)，直接在界面中键入命令。

______________________________________________________________________

配置

通过自定义服务器 .env 文件：

必需设置

• HF_令牌：拥抱脸API代币。

  HF_TOKEN=your_hf_token

• 模型空间：复制的3D模型空间（例如。， your-username/InstantMesh).

- 复制以下内容之一： - InstantMesh - 浑源3D-2 - 浑源3D-2微型涡轮

  MODEL_SPACE=your-username/InstantMesh

可选三维模型设置

空间特定默认值

• InstantMesh:

- 步骤：30-75（默认值：75） - 种子：默认42

• 浑源3D-2:

- 步骤：20-50（默认值：20） - 引导比例：默认5.5 - 八叉树决议： 256, 384, 512 （默认值： 256) - 种子：默认1234

• 浑源3D-2微型涡轮:

- 步骤：1-100（默认值：5 Turbo，10为 Fast20为 Standard) - 引导比例：默认值5.0 - 八叉树分辨率：16-512（默认值：256） - 种子：默认1234

传输设置

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

  PORT=3000

Claude桌面设置

编辑配置文件：

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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.
• 兼容性：与合作 克劳德桌面 以及其他MCP客户端。

______________________________________________________________________

故障排除

• API错误：检查网络连接或速率限制；审查 ./logs/server.log.
• 身份验证问题：验证 HF_TOKEN 和 MODEL_SPACE 在……里面 .env.
• ES模块错误：确保Node.js 16+(node --version).
• 日志：检查详细日志：

  tail -f ./logs/server.log

______________________________________________________________________

高级

API端点和集成

• 二维资产生成：用途 "gokaygokay/Flux-2D-Game-Assets-LoRA" （50步）。
• 3D资产图像生成：用途 "gokaygokay/Flux-Game-Assets-LoRA-v2" （30步）。
• 三维模型转换:

- InstantMesh：多步骤(/check_input_image, /preprocess, /generate_mvs, /make3d). - 浑源3D-2：单步(/generation_all). - 浑源3D-2微型涡轮：单步(/generation_all)配备涡轮模式。

版本控制

• 当前版本：0.3.0（新增浑源3D-2迷你涡轮支持）。
• MCP SDK版本: 1.7.0.
• 格式：少校。未成年人。PATCH（SemVer）。

后端架构

• 核心文件: src/index.js.
• 依赖项：参见 package.json.
• 安全：Zod验证、路径遍历预防、HTTPS支持、速率限制。
• 演出：异步处理，带回退重试，GPU配额处理。

______________________________________________________________________

贡献

我们欢迎捐款！参加：

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

遵循标准编码惯例，并在适用的情况下包括测试。

______________________________________________________________________

许可证

根据 MIT许可证。请参阅 许可证 文件以获取详细信息。