8thwallmcp

🚀 8th Wall MCP Server

8th Wall MCP Server 可藉助 Claude Desktop 和 8th Wall Desktop，利用自然語言構建 WebAR 體驗。它提供了豐富的工具和功能，能幫助開發者輕鬆創建 AR 場景。

🚀 快速開始

創建你的第一個 AR 場景

1. 設置項目：

   "Set my project to my-ar-project"
   

2. 添加 3D 內容：

   "Create a red spinning cube at position (0, 1, -2)"
   

3. 添加動畫：

   "Make the cube pulse between 80% and 120% size"
   

4. 添加 AR 特性：

   "Enable face tracking with a debug mesh"
   

使用 8th Wall Desktop

"List all my 8th Wall Desktop projects"
"Set project to beach-scene"
"Add a seagull GLB model from assets at position (0, 2, 0)"
"Add physics to the beach ball"
"Make the rocket orbit the planet"

搜索資源

"Search PolyHaven for space textures"
"Download the damaged helmet GLB"
"Add the downloaded model at position (0, 1.5, -3)"

✨ 主要特性

🛠️ 66 + 用於高級 AR 開發的工具

🤖 人工智能驅動的創建（新功能！）

• 智能編排 - create_ar_experience - 根據描述構建完整的 AR 體驗。
• 模式識別 - 自動識別 AR 體驗類型（面部跟蹤、圖像目標等）。
• 代碼生成 - 根據自然語言生成自定義 JavaScript。
• 體驗模板 - 6 個預構建模板（光繪、模型展示、傳送門、面部過濾器等）。

🧩 自定義開發（新功能！）

• 自定義組件 - 添加和管理 A - Frame 組件。
• 資源發現 - 通過智能推薦搜索 PolyHaven。
• 代碼模板 - 預構建的粒子系統、手勢處理程序、音頻控制器。
• JavaScript 驗證 - 在部署前檢查代碼錯誤。

🎨 場景構建

• 桌面場景構建 - 添加形狀、模型、燈光和動畫。
• AR 特性 - 圖像目標、面部跟蹤、世界跟蹤。
• 動畫系統 - 旋轉、縮放和模型動畫。
• 物理效果 - 為對象添加物理效果（動力學、質量、重力）。

📦 資源與項目管理

• 資源管理 - 搜索 PolyHaven、下載模型、管理文件。
• 項目工具 - 創建、編輯和管理 8th Wall Desktop 項目。
• 開發服務器 - 內置預覽服務器用於測試。

🎨 自然語言場景構建

"Create a spinning red cube with a metallic sphere orbiting around it"
"Add a beach ball with physics that falls when the scene starts"
"Create an AR portal using hider materials"
"Add an image target experience with a video"

🔧 三種操作模式

1. 本地模式（默認） - 本地處理 8th Wall Desktop 項目。
2. 文檔模式 - 訪問 8th Wall 文檔。
3. API 模式 - 與 8th Wall Cloud 集成（需要 API 密鑰）。

📦 安裝指南

選項 1：一鍵安裝（推薦）

1. 下載 mcp - 8thwall - 0.1.0.mcpb 文件。
2. 雙擊 以使用 Claude Desktop 打開。
3. 提示時 點擊安裝。
4. 完成！ 現在所有 47 個工具都可用。

選項 2：手動安裝

1. 克隆倉庫：

   git clone https://github.com/superdwayne/8thwallmcp.git
   cd mcp-8thwall
   

2. 安裝依賴項：

   npm install
   

3. 構建：

   npm run build
   

4. 添加到 Claude Desktop 配置 (~/.claude/claude_desktop_config.json)：

{
  "mcpServers": {
       "mcp-8thwall": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-8thwall/dist/index.js"
      ]
    }
  }
}

5. 重啟 Claude Desktop

🔧 桌面場景構建工具

基本圖形與形狀

• desktop_add_shape - 添加 3D 基本圖形：
  • 幾何體：立方體、球體、圓柱體、圓錐體、平面、圓形、圓環體、環形。
  • 材質：基礎材質、標準材質、馮氏材質。
  • 屬性：顏色、粗糙度、金屬度、不透明度、發光度。
  • 隱藏材質：顏色寫入、深度寫入、深度測試（用於 AR 傳送門）。

3D 模型

• desktop_add_model - 添加 GLB/GLTF 模型：
  • 從 assets/ 文件夾加載。
  • 位置、旋轉、縮放。
  • 動畫播放。
  • 物理支持（靜態、動態、運動學）。

動畫

• desktop_add_rotation_animation - 使對象旋轉：

  • 軸選擇（X、Y、Z）。
  • 速度控制。
  • 循環和反轉選項。
  • 緩動函數。

• desktop_add_scale_animation - 實現脈衝/呼吸效果：

  • 最小/最大縮放比例。
  • 持續時間控制。
  • 循環和反轉。
  • 緩動函數。

• desktop_set_model_animation - 控制模型動畫：

  • 播放特定動畫片段。
  • 循環控制。
  • 播放速度。

AR 特性

• desktop_enable_face_tracking - 面部 AR 體驗。
• desktop_add_image_target - 圖像跟蹤。
• desktop_add_video - 視頻紋理。
• 用於 AR 傳送門的隱藏材質。

📚 詳細文檔

工具類別

🐛 已知問題與修復

✅ v0.1.0 中修復的問題

• 幾何體屬性錯誤 - 修復了圓柱體和圓錐體缺少 heightSegments 和 openEnded 屬性的問題。
• 顏色渲染問題 - 材質現在使用 basic 類型而不是 standard 類型，以實現可靠的顏色渲染。
• 服務器崩潰 - 通過適當的保活間隔修復了進程生命週期管理問題。

當前限制

• MCPB 自動安裝可能需要重啟 Claude Desktop。
• 桌面模式下圖像目標相機預覽顯示為黑色（在手機上測試）。
• 某些平臺上視頻自動播放可能需要用戶交互。

🏗️ 項目結構

mcp-8thwall/
├── src/
│   ├── index.ts              # 服務器入口點
│   ├── tools/
│   │   ├── desktop.ts        # 8th Wall Desktop 工具
│   │   ├── scene.ts          # Web 場景工具
│   │   ├── project.ts        # 項目管理
│   │   ├── assets.ts         # 資源工具
│   │   ├── devserver.ts      # 開發服務器
│   │   └── docs.ts           # 文檔工具
│   ├── clients/
│   │   └── 8thwallClient.ts  # API 客戶端
│   └── utils/
│       └── projectRoot.ts    # 項目根目錄管理
├── dist/                     # 編譯後的 JavaScript
├── manifest.json             # MCPB 清單
├── mcp-8thwall-0.1.0.mcpb   # 桌面擴展包
└── README.md                 # 本文件

🚀 高級用法

環境變量

{
  "mcpServers": {
    "mcp-8thwall": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "MODE": "local",
        "PROJECT_ROOT": "/path/to/your/project",
        "EIGHTHWALL_DESKTOP_ROOT": "~/Documents/8th Wall"
      }
    }
  }
}

可用模式：

• local（默認） - 處理本地 8th Wall Desktop 項目。
• docs - 訪問 8th Wall 文檔。
• api - 與 8th Wall Cloud API 集成。

用於 n8n 的 HTTP 橋接

運行 HTTP 橋接以從 n8n 或其他自動化平臺調用工具：

HTTP_PORT=8787 MODE=local PROJECT_ROOT=./project npm run http

API 端點：

• GET http://localhost:8787/tools - 列出所有工具。
• POST http://localhost:8787/tool/<toolName> - 調用工具。

開發

npm run dev          # 使用 ts - node 運行
npm run build        # 編譯 TypeScript
npm run typecheck    # 僅進行類型檢查
npm run pack:dxt     # 創建 MCPB 包

📖 使用示例

創建一個 AR 海灘場景

1. "Set project to beach-scene"
2. "Add a blue sphere for the sky at (0, 50, 0) with radius 100"
3. "Add a sandy plane as the ground at (0, 0, 0)"
4. "Download a seagull GLB and add it flying at (2, 5, -10)"
5. "Make the seagull rotate slowly on the Y axis"
6. "Add a beach ball with physics at (0, 2, -3)"

創建一個 AR 傳送門

1. "Set project to portal-demo"
2. "Create a portal using hider materials"
3. "Add a rotating torus as the portal ring"
4. "Add a blue emissive sphere as the portal glow"
5. "Make the glow pulse between 80% and 120%"

圖像目標體驗

1. "Set project to image-target-demo"
2. "Add an image target for 'poster.jpg'"
3. "Add a video plane with 'promo-video.mp4'"
4. "Add a GLB model that appears on the image"
5. "Make the model spin on the Y axis"

🤝 貢獻

歡迎貢獻代碼！請參閱：

• CONTRIBUTING.md 瞭解貢獻指南。
• CODE_OF_CONDUCT.md 瞭解我們的行為準則。
• SECURITY.md 瞭解安全報告。

開發工作流程

1. 分叉倉庫。
2. 創建功能分支。
3. 進行更改。
4. 如有必要添加測試。
5. 運行 npm run typecheck。
6. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE。

🔗 鏈接

• 8th Wall Desktop：8thwall.com/desktop
• 模型上下文協議：modelcontextprotocol.io
• Claude Desktop：claude.ai
• PolyHaven 資源：polyhaven.com
• GitHub 問題：報告錯誤

💡 使用建議

• 使用 desktop_list_projects 發現你的 8th Wall Desktop 項目。
• 在 PolyHaven 上搜索免費的 3D 資源、紋理和 HDRI。
• 在手機上測試 AR 特性以進行相機預覽。
• 使用隱藏材質 (colorWrite: false) 實現 AR 傳送門效果。
• 為動態對象啟用物理效果。
• 使用動畫使你的場景生動起來。

🙏 致謝

• 8th Wall 提供了出色的 WebAR 平臺。
• Anthropic 提供了 Claude 和 MCP 協議。
• PolyHaven 提供了免費的 3D 資源。
• MCP 社區 提供了工具和靈感。

由 Dwayne Paisley - Marshall 用心打造