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令牌，並配置防火牆限制外部訪問。

💡 使用建議

如果需要提高生成速度，可使用更高性能的模型或優化網絡帶寬。