MCP 服务器

Game Asset Generator

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

README

使用 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 生成：通过环境变量自定义推理步骤、引导比例和 Turbo 模式等参数。

工作原理

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

用户输入：提交文本提示（例如，“像素艺术剑”或“等距 3D 城堡”）。
MCP 服务器：将提示路由到相应的工具（generate_2d_asset 或 generate_3d_asset）。
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：具有可配置 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
```
- 使用您的 Hugging Face API 令牌和复制的 MODEL_SPACE 编辑 .env。有关详细信息，请参见配置。
运行服务器：
- 本地（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 模块（package.json 中的 "type": "module"）。确保已安装 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：具有 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 Request：详细说明您的更改。
打开 Issues：报告错误或提出改进建议。

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

许可证

在 MIT 许可证 下获得许可。有关详细信息，请参见 LICENSE 文件。