Poly Pizza MCP

🚀 Poly.Pizza MCP 服務器

Poly.Pizza MCP 服務器可讓你直接將 Poly.Pizza 上的 3D 模型導入到 Unity 項目中。它基於 MCP（Model Context Protocol）協議，為開發者提供了便捷的模型導入解決方案。

✨ 主要特性

• 模型搜索：支持通過關鍵字在 Poly.Pizza 上搜索 3D 模型。
• Unity 導入：可將搜索到的模型自動導入到 Unity 項目中。
• 批量導入：允許一次性導入多個模型。
• 緩存功能：對下載的模型進行緩存，方便後續重複使用。
• 預製體自動生成：導入模型後，自動生成 Unity 預製體。
• 版權信息自動生成：對於 CC - BY 許可的模型，自動記錄版權信息。
• Unity UI 設置 API 密鑰：無需設置環境變量，可直接在 Unity 編輯器中輸入 API 密鑰。

📦 安裝指南

1. 安裝 Unity 包（通過包管理器）

在 Unity 中，打開 Window > Package Manager，然後：

1. 點擊 + 按鈕。
2. 選擇 Add package from git URL...。
3. 輸入以下 URL：

https://github.com/HaD0Yun/poly - pizza - mcp.git?path=unity - package

2. 安裝 MCP 服務器

git clone https://github.com/HaD0Yun/poly - pizza - mcp.git
cd poly - pizza - mcp
npm install
npm run build

3. 設置 API 密鑰（推薦使用 Unity UI）

1. 在 Unity 中，點擊 Window > Poly.Pizza MCP 或 Poly.Pizza > Dashboard 菜單。
2. 點擊 Get API Key 按鈕，從 poly.pizza/settings/api 獲取 API 密鑰。
3. 將獲取的 API 密鑰粘貼到輸入框中。
4. 點擊 Save API Key 按鈕。

API 密鑰將保存到 ~/.poly - pizza/config.json 文件中，MCP 服務器會自動讀取。

3 - 1. 設置 API 密鑰（使用環境變量 - 備用方法）

若要使用環境變量，請執行以下操作：

# Windows
set POLY_PIZZA_API_KEY=your - api - key - here

# macOS/Linux
export POLY_PIZZA_API_KEY=your - api - key - here

4. 配置 MCP 客戶端

在 Claude Desktop 或其他 MCP 客戶端的配置文件中添加以下內容：

{
  "mcpServers": {
    "poly - pizza": {
      "command": "npx",
      "args": ["-y", "poly - pizza - mcp"],
      "env": {
        "UNITY_PROJECT_PATH": "/path/to/UnityProject"
      }
    }
  }
}

注意：如果已在 Unity 儀表盤上設置了 API 密鑰，則無需在 env 中包含該密鑰。

💻 使用示例

基礎用法

set_api_key：設置和檢查 API 密鑰狀態

"檢查 API 密鑰狀態"
→ set_api_key()

"設置 API 密鑰"
→ set_api_key(apiKey: "your - api - key")

"刪除 API 密鑰"
→ set_api_key(clear: true)

search_models：在 Poly.Pizza 上搜索模型

"查找汽車模型"
→ search_models(keyword: "car", limit: 10)

import_to_unity：將特定模型導入到 Unity

"將此模型添加到 Unity：5EGWBMpuXq"
→ import_to_unity(modelId: "5EGWBMpuXq", createPrefab: true)

batch_import：批量導入多個模型

"導入所有這些模型"
→ batch_import(modelIds: ["id1", "id2", "id3"])

quick_import：搜索後直接導入第一個結果

"直接導入中世紀劍模型"
→ quick_import(query: "medieval sword")

search_and_batch_import：搜索結果並批量導入

"查找 5 個樹木模型並全部導入"
→ search_and_batch_import(keyword: "tree", limit: 5)

get_popular：獲取熱門模型列表

"最近有哪些熱門模型？"
→ get_popular(limit: 20)

cache_status：檢查和管理緩存狀態

"顯示緩存狀態" → cache_status(action: "status")
"清除緩存" → cache_status(action: "clear")

📚 詳細文檔

Unity 項目結構

MCP 服務器導入模型後，文件將按以下結構保存：

Assets/
└── PolyPizza/
    ├── Models/           # 3D 模型文件（.glb、.fbx 等）
    ├── Prefabs/          # 自動生成的預製體
    ├── CREDITS.txt       # 許可證版權信息
    └── .signals/         # MCP 與 Unity 通信使用（自動管理）

Unity 菜單

在 Unity 編輯器中可使用以下菜單：

• Window > Poly.Pizza MCP：設置 API 密鑰並打開儀表盤。
• Poly.Pizza > Dashboard：設置 API 密鑰並檢查狀態。
• Poly.Pizza > Refresh Assets：刷新資源。
• Poly.Pizza > Open Models Folder：打開模型文件夾。
• Poly.Pizza > Open Prefabs Folder：打開預製體文件夾。
• Poly.Pizza > Create Prefabs from All Models：從所有模型創建預製體。

許可證信息

Poly.Pizza 的模型提供兩種許可證：

使用 CC - BY 許可證的模型時，版權信息將自動記錄在 CREDITS.txt 中。遊戲發佈時，請在版權頁面包含這些信息。

🔧 技術細節

開發命令

# 開發模式（監聽文件變化）
npm run dev

# 構建項目
npm run build

# 運行項目
npm start

問題解決

API 密鑰不工作

• 打開 Unity 中的 Poly.Pizza > Dashboard，檢查 API 密鑰是否已保存。
• 在 https://poly.pizza/settings/api 檢查密鑰是否有效。
• 檢查 ~/.poly - pizza/config.json 文件是否存在，以及 API 密鑰是否正確保存。

Unity 中看不到模型

• 確保 Unity 編輯器已打開。
• 執行 Assets > Refresh 或 Poly.Pizza > Refresh Assets。
• 檢查 .signals 文件夾中的文件是否已處理。

緩存問題

• 使用 cache_status(action: "clear") 清除緩存。

📄 許可證

本項目採用 MIT 許可證。

致謝

• Poly.Pizza - 提供免費的低多邊形 3D 模型。
• 由 dook（Zac Lucarelli）創建。