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 用心打造