8th Wall Mcp

8th Wall MCP Server

使用 Claude Desktop 和 8th Wall Desktop，通过自然语言构建 WebAR 体验

🚀 一键安装

下载最新版本：

📦 6.3 MB • 🎨 纯 Three.js • 📱 已通过 AR 测试 • 🐛 错误修复

双击即可安装！ 无需终端命令，也无需配置文件。

---

✨ 更新内容

最新更新（v0.2.10）🐛

已修复：ECS 属性错误

• 🐛 已修复“No attribute registered”错误 - 已禁用存在问题的动画工具
• ❌ 已移除无法使用的工具 - 已禁用 desktop_add_rotation_animation 和 desktop_add_scale_animation
• ✅ 使用 Three.js 动画 - 所有动画现在都使用 desktop_add_threejs_script
• 🎯 不再出现运行时错误 - Desktop 项目中不再出现 ECS 属性错误
• 📝 有用的错误消息 - 无法使用的工具现在会引导你采用正确的方法
• 🚀 稳定可靠 - 所有可用工具均已测试和验证

先前更新（v0.2.9）🔥

已彻底移除 A-Frame 组件

• 🗑️ 已删除所有 A-Frame 组件 - 已移除 particleSystem.js、audioController.js、gestureHandler.js、physicsHelper.js
• ✅ 不再出现 AFRAME 错误 - 不会再出现“Can't find variable: AFRAME”错误
• ⚠️ 明确的工具警告 - A-Frame 工具现在明确标记为“仅限 WEB 项目”

先前更新（v0.2.8）📚

文档说明更清晰

• 🎯 新增文档 - 清楚说明：Desktop 使用 Three.js，而非 A-Frame
• ✅ 不再混淆 - A-Frame 仅用于 Web 项目，不用于 Desktop
• 📚 DESKTOP_THREEJS_ONLY.md - 完整介绍正确的 Desktop 开发方式
• 🛠️ 使用正确的工具 - Desktop 项目请使用 desktop_add_threejs_script

先前更新（v0.2.7）🛡️

AFRAME 安全检查（仅限 Web 项目）

• 🛡️ 安全注册 AFRAME - 所有组件在注册前都会检查 AFRAME 是否存在
• ⏱️ 等待加载事件 - 组件会等待 window 的 'load' 事件后再初始化
• 🐛 运行时错误归零 - 消除了“Can't find variable: AFRAME”错误
• 📝 全面日志记录 - 提供详细的控制台消息，便于调试
• ✅ 平稳回退 - 实用的错误消息会在需要时引导用户添加 A-Frame
• 🔄 兼容 Webpack HMR - 不再出现断连问题

先前更新（v0.2.6）🚀

Three.js 现已成为默认框架！

• 🎯 默认使用 Three.js - 所有新项目现在默认使用 Three.js，而非 A-Frame
• 🐛 移动端修复 - 消除了移动设备上的 A-Frame 加载错误
• ✅ 兼容性更佳 - 使用纯 Three.js 改进了对移动浏览器的支持
• 🔄 自动回退 - 引擎未知时，场景工具会自动使用 Three.js
• 📚 完整文档 - 提供全面的迁移指南和更新后的模板
• ⚡ 无破坏性变更 - 仍可通过显式的模板参数使用 A-Frame

之前的更新（v0.2.5）🎨

Three.js 脚本生成器

• 🎯 desktop_add_threejs_script - 生成经过实战验证的 Three.js 脚本，用于 AR 交互
• ✅ 完善的 XR8 集成 - 正确处理管线初始化、场景访问和摄像头设置
• 📱 经过 AR 测试 - 在移动设备上运行流畅，支持触摸和点击交互
• 🎨 交互式对象 - 创建点击变色球体、粒子系统等
• 📍 最佳定位 - 在前方 5 m、视线高度处放置对象，并正确设置 FOV
• 🐛 全面的日志记录 - 提供详细的调试输出，便于排查问题
• 📦 6.3 MB - 包含所有依赖项和模板

之前的更新（v0.2.4）

• 🤖 AI 驱动的 AR 创建 - 通过自然语言创建完整的 AR 体验
• 🎨 6 种体验模板 - 光绘、模型展示、传送门、人脸滤镜
• 💻 代码生成 - 生成自定义 JavaScript 组件
• 🧩 自定义组件 - 添加和管理 A-Frame 组件
• 🔍 统一资产发现 - 搜索 PolyHaven 资产并获取推荐
• 🎯 智能编排 - 分析请求并自动串联工具

🎯 功能

🛠️ 66+ 种高级 AR 开发工具

🤖 AI 驱动的创作（新增！）

• 智能编排 - 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

---

🎮 快速入门

创建你的第一个 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)"

---

🔧 桌面场景构建工具

基元与形状

• desktop_add_shape - 添加 3D 基元：
  • 几何体：box、sphere、cylinder、cone、plane、circle、torus、ring
  • 材质：basic、standard、phong
  • 属性：color、roughness、metalness、opacity、emissive
  • 遮挡材质：colorWrite、depthWrite、depthTest（用于 AR 门户）

3D 模型

• desktop_add_model - 添加 GLB/GLTF 模型：
  • 从 assets/ 文件夹加载
  • 位置、旋转、缩放
  • 动画播放
  • 支持物理效果（static、dynamic、kinematic）

动画

• 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 门户的遮挡材质

---

📚 文档

工具类别

项目管理（12 个工具）

• project_get_root / project_set_root - 管理项目目录
• desktop_list_projects / desktop_set_project - 8th Wall Desktop 项目
• project_get_info - 获取项目结构
• project_list_files - 列出文件
• project_read_file / project_write_file - 文件操作
• project_delete_file / project_move_file - 文件管理
• project_scaffold - 创建新项目
• project_export_zip - 导出以供上传

场景构建（13 个工具）

• desktop_add_shape - 基元（box、sphere 等）
• desktop_add_model - GLB/GLTF 模型
• desktop_add_rotation_animation - 旋转物体
• desktop_add_scale_animation - 脉冲效果
• desktop_add_image_target - 图像追踪
• desktop_add_video - 视频纹理
• desktop_enable_face_tracking - 面部 AR
• desktop_set_model_animation - 模型动画
• desktop_read_json / desktop_write_json / desktop_patch_json - JSON 操作
• desktop_guess_scene - 查找场景文件

资源管理（8 个工具）

• assets_status - 检查 PolyHaven 是否可用
• assets_search_polyhaven - 搜索资源
• assets_polyhaven_categories - 浏览类别
• assets_polyhaven_files - 获取资源元数据
• assets_download_url - 下载文件
• assets_unzip - 解压归档文件
• prompts_asset_strategy - 资源指南

开发工具（3 个工具）

• devserver_start / devserver_stop - 本地预览
• health_ping - 健康检查

Web 场景工具（11 个工具）

适用于 A-Frame 和 Three.js 项目：

• scene_detect_engine - 检测 A-Frame 或 Three.js
• scene_add_gltf_model - 添加模型
• scene_set_background_color - 背景
• scene_add_primitive - 基元
• scene_add_light - 灯光
• scene_set_environment_hdr - HDR 环境
• scene_add_animation - 动画
• scene_add_textured_plane - 图像平面
• scene_add_orbit_controls - Three.js 控件
• scene_add_grid_helper / scene_add_floor - 辅助工具

文档（2 个工具）

• docs_get_page - 获取文档
• docs_search - 搜索文档

---

🐛 已知问题与修复

✅ 已在 v0.1.0 中修复

• 几何体属性错误 - 修复了圆柱体和圆锥体缺少 heightSegments 和 openEnded 属性的问题
• 颜色渲染问题 - 材质现在使用 basic 类型，而不是 standard 类型，以确保颜色可靠渲染
• 服务崩溃 - 修复了进程生命周期管理，并正确设置了保持活动状态的间隔时间

当前限制

• MCPB 自动安装可能需要重启 Claude Desktop
• 在桌面模式下，图像目标的摄像头预览会显示为黑屏（请在手机上测试）
• 在某些平台上，视频自动播放可能需要用户交互

---

🏗️ 项目结构

mcp-8thwall/
├── src/
│   ├── index.ts              # Server entry point
│   ├── tools/
│   │   ├── desktop.ts        # 8th Wall Desktop tools
│   │   ├── scene.ts          # Web scene tools
│   │   ├── project.ts        # Project management
│   │   ├── assets.ts         # Asset tools
│   │   ├── devserver.ts      # Dev server
│   │   └── docs.ts           # Documentation tools
│   ├── clients/
│   │   └── 8thwallClient.ts  # API client
│   └── utils/
│       └── projectRoot.ts    # Project root management
├── dist/                     # Compiled JavaScript
├── manifest.json             # MCPB manifest
├── mcp-8thwall-0.1.0.mcpb   # Desktop Extension package
└── README.md                 # This file

---

🚀 高级用法

环境变量

{
  "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          # Run with ts-node
npm run build        # Compile TypeScript
npm run typecheck    # Type checking only
npm run pack:dxt     # Create MCPB package

---

📖 示例

创建 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. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 运行 npm run typecheck
6. 提交拉取请求

---

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE

---

🔗 链接

• 8th Wall Desktop：8thwall.com/desktop
• Model Context Protocol：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 Community 提供工具和灵感

---

由 Dwayne Paisley-Marshall 倾心打造 ❤️