8th Wall MCP Server

Build WebAR experiences with natural language using Claude Desktop and 8th Wall Desktop

🚀 One-Click Install

Download the latest version:

📦 6.3 MB • 🎨 Pure Three.js • 📱 AR-Tested • 🐛 Bug Fixes

Double-click to install! No terminal commands, no configuration files.

---

✨ What's New

Latest Updates (v0.2.10) 🐛

FIXED: ECS ATTRIBUTE ERRORS

• 🐛 Fixed "No attribute registered" Error - Disabled broken animation tools
• ❌ Broken Tools Removed - desktop_add_rotation_animation and desktop_add_scale_animation disabled
• ✅ Use Three.js Animations - All animations now use desktop_add_threejs_script
• 🎯 No More Runtime Errors - Zero ECS attribute errors in Desktop projects
• 📝 Helpful Error Messages - Broken tools now guide you to the correct approach
• 🚀 Stable & Reliable - All working tools tested and verified

Previous Updates (v0.2.9) 🔥

A-FRAME COMPONENTS COMPLETELY REMOVED

• 🗑️ Deleted All A-Frame Components - Removed particleSystem.js, audioController.js, gestureHandler.js, physicsHelper.js
• ✅ No More AFRAME Errors - Zero chance of "Can't find variable: AFRAME" errors
• ⚠️ Clear Tool Warnings - A-Frame tools now clearly marked as "WEB PROJECTS ONLY"

Previous Updates (v0.2.8) 📚

Documentation Clarity

• 🎯 Documentation Added - Clear explanation: Desktop = Three.js, NOT A-Frame
• ✅ No More Confusion - A-Frame is only for web projects, not Desktop
• 📚 DESKTOP_THREEJS_ONLY.md - Complete guide to proper Desktop development
• 🛠️ Right Tools - Use desktop_add_threejs_script for Desktop projects

Previous Updates (v0.2.7) 🛡️

AFRAME Safety Checks (for web projects only)

• 🛡️ Safe AFRAME Registration - All components now check for AFRAME before registering
• ⏱️ Load Event Waiting - Components wait for window 'load' event before initialization
• 🐛 Zero Runtime Errors - Eliminated "Can't find variable: AFRAME" errors
• 📝 Comprehensive Logging - Detailed console messages for debugging
• ✅ Graceful Fallback - Helpful error messages guide users to add A-Frame if needed
• 🔄 Webpack HMR Compatible - No more disconnection issues

Previous Updates (v0.2.6) 🚀

Three.js is Now the Default Framework!

• 🎯 Three.js Default - All new projects now default to Three.js instead of A-Frame
• 🐛 Mobile Fixes - Eliminated A-Frame loading errors on mobile devices
• ✅ Better Compatibility - Improved mobile browser support with pure Three.js
• 🔄 Auto-Fallback - Scene tools automatically use Three.js when engine is unknown
• 📚 Full Documentation - Comprehensive migration guide and updated templates
• ⚡ No Breaking Changes - A-Frame still supported via explicit template parameter

Previous Updates (v0.2.5) 🎨

Three.js Script Generator

• 🎯 desktop_add_threejs_script - Generate battle-tested Three.js scripts for AR interactions
• ✅ Proper XR8 Integration - Handles pipeline initialization, scene access, and camera setup correctly
• 📱 AR-Tested - Works perfectly on mobile devices with touch/click interactions
• 🎨 Interactive Objects - Creates tap-to-change-color spheres, particle systems, and more
• 📍 Optimal Positioning - Places objects 5m ahead at eye level with proper FOV
• 🐛 Comprehensive Logging - Detailed debugging output for troubleshooting
• 📦 6.3 MB - Includes all dependencies and templates

Previous Updates (v0.2.4)

• 🤖 AI-Powered AR Creation - Create complete AR experiences from natural language
• 🎨 6 Experience Templates - Light painting, model showcase, portals, face filters
• 💻 Code Generation - Generate custom JavaScript components
• 🧩 Custom Components - Add and manage A-Frame components
• 🔍 Unified Asset Discovery - Search PolyHaven assets with recommendations
• 🎯 Smart Orchestration - Analyzes requests and chains tools automatically

🎯 Features

🛠️ 66+ Tools for Advanced AR Development

🤖 AI-Powered Creation (NEW!)

• Smart Orchestration - create_ar_experience - Build complete AR experiences from descriptions
• Pattern Recognition - Automatically identifies AR experience types (face tracking, image targets, etc.)
• Code Generation - Generate custom JavaScript from natural language
• Experience Templates - 6 pre-built templates (light painting, portals, face filters, etc.)

🧩 Custom Development (NEW!)

• Custom Components - Add and manage A-Frame components
• Asset Discovery - Search PolyHaven with smart recommendations
• Code Templates - Pre-built particle systems, gesture handlers, audio controllers
• JavaScript Validation - Check code for errors before deployment

🎨 Scene Building

• Desktop Scene Building - Add shapes, models, lights, and animations
• AR Features - Image targets, face tracking, world tracking
• Animation System - Rotation, scale, and model animations
• Physics - Add physics to objects (dynamics, mass, gravity)

📦 Asset & Project Management

• Asset Management - Search PolyHaven, download models, manage files
• Project Tools - Create, edit, and manage 8th Wall Desktop projects
• Dev Server - Built-in preview server for testing

🎨 Natural Language Scene Building

"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"

🔧 Three Operation Modes

1. Local Mode (Default) - Work with 8th Wall Desktop projects locally
2. Docs Mode - Access 8th Wall documentation
3. API Mode - Integrate with 8th Wall Cloud (requires API key)

---

📦 Installation

Option 1: One-Click Install (Recommended)

1. Download the mcp-8thwall-0.1.0.mcpb file
2. Double-click to open with Claude Desktop
3. Click Install when prompted
4. Done! All 47 tools are now available

Option 2: Manual Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Build:

   npm run build
   

4. Add to Claude Desktop config (~/.claude/claude_desktop_config.json):

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

5. Restart Claude Desktop

---

🎮 Quick Start

Create Your First AR Scene

1. Set your project:

   "Set my project to my-ar-project"
   

2. Add 3D content:

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

3. Add animations:

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

4. Add AR features:

   "Enable face tracking with a debug mesh"
   

Work with 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 for Assets

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

---

🔧 Desktop Scene Building Tools

Primitives & Shapes

• desktop_add_shape - Add 3D primitives:
  • Geometries: box, sphere, cylinder, cone, plane, circle, torus, ring
  • Materials: basic, standard, phong
  • Properties: color, roughness, metalness, opacity, emissive
  • Hider materials: colorWrite, depthWrite, depthTest (for AR portals)

3D Models

• desktop_add_model - Add GLB/GLTF models:
  • Load from assets/ folder
  • Position, rotation, scale
  • Animation playback
  • Physics support (static, dynamic, kinematic)

Animations

• desktop_add_rotation_animation - Spin objects:

  • Axis selection (X, Y, Z)
  • Speed control
  • Loop and reverse options
  • Easing functions

• desktop_add_scale_animation - Pulse/breathe effects:

  • Min/max scale
  • Duration control
  • Loop and reverse
  • Easing functions

• desktop_set_model_animation - Control model animations:

  • Play specific animation clips
  • Loop control
  • Playback speed

AR Features

• desktop_enable_face_tracking - Face AR experiences
• desktop_add_image_target - Image tracking
• desktop_add_video - Video textures
• Hider materials for AR portals

---

📚 Documentation

Tool Categories

<details> <summary><b>Project Management (12 tools)</b></summary>

• project_get_root / project_set_root - Manage project directory
• desktop_list_projects / desktop_set_project - 8th Wall Desktop projects
• project_get_info - Get project structure
• project_list_files - List files
• project_read_file / project_write_file - File operations
• project_delete_file / project_move_file - File management
• project_scaffold - Create new project
• project_export_zip - Export for upload

</details>

<details> <summary><b>Scene Building (13 tools)</b></summary>

• desktop_add_shape - Primitives (box, sphere, etc.)
• desktop_add_model - GLB/GLTF models
• desktop_add_rotation_animation - Spin objects
• desktop_add_scale_animation - Pulse effects
• desktop_add_image_target - Image tracking
• desktop_add_video - Video textures
• desktop_enable_face_tracking - Face AR
• desktop_set_model_animation - Model animations
• desktop_read_json / desktop_write_json / desktop_patch_json - JSON manipulation
• desktop_guess_scene - Find scene files

</details>

<details> <summary><b>Asset Management (8 tools)</b></summary>

• assets_status - Check PolyHaven availability
• assets_search_polyhaven - Search assets
• assets_polyhaven_categories - Browse categories
• assets_polyhaven_files - Get asset metadata
• assets_download_url - Download files
• assets_unzip - Extract archives
• prompts_asset_strategy - Asset guidance

</details>

<details> <summary><b>Development Tools (3 tools)</b></summary>

• devserver_start / devserver_stop - Local preview
• health_ping - Health check

</details>

<details> <summary><b>Web Scene Tools (11 tools)</b></summary>

For A-Frame and Three.js projects:

• scene_detect_engine - Detect A-Frame or Three.js
• scene_add_gltf_model - Add models
• scene_set_background_color - Background
• scene_add_primitive - Primitives
• scene_add_light - Lighting
• scene_set_environment_hdr - HDR environment
• scene_add_animation - Animations
• scene_add_textured_plane - Image planes
• scene_add_orbit_controls - Three.js controls
• scene_add_grid_helper / scene_add_floor - Helpers

</details>

<details> <summary><b>Documentation (2 tools)</b></summary>

• docs_get_page - Fetch documentation
• docs_search - Search docs

</details>

---

🐛 Known Issues & Fixes

✅ Fixed in v0.1.0

• Geometry Properties Error - Fixed missing heightSegments and openEnded properties for cylinders and cones
• Color Rendering Issue - Materials now use basic type instead of standard for reliable color rendering
• Server Crashes - Fixed process lifecycle management with proper keep-alive intervals

Current Limitations

• MCPB auto-installation may require Claude Desktop restart
• Image target camera preview shows black in Desktop mode (test on phone)
• Video autoplay may require user interaction on some platforms

---

🏗️ Project Structure

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

---

🚀 Advanced Usage

Environment Variables

{
  "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"
      }
    }
  }
}

Available Modes:

• local (default) - Work with local 8th Wall Desktop projects
• docs - Access 8th Wall documentation
• api - Integrate with 8th Wall Cloud API

HTTP Bridge for n8n

Run an HTTP bridge to call tools from n8n or other automation platforms:

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

API Endpoints:

• GET http://localhost:8787/tools - List all tools
• POST http://localhost:8787/tool/<toolName> - Invoke a tool

Development

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

---

📖 Examples

Create an AR Beach Scene

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)"

Create an AR Portal

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%"

Image Target Experience

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

Contributions are welcome! Please see:

• CONTRIBUTING.md for contribution guidelines
• CODE_OF_CONDUCT.md for our code of conduct
• SECURITY.md for security reporting

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run npm run typecheck
6. Submit a pull request

---

📄 License

MIT License - see LICENSE for details

---

🔗 Links

• 8th Wall Desktop: 8thwall.com/desktop
• Model Context Protocol: modelcontextprotocol.io
• Claude Desktop: claude.ai
• PolyHaven Assets: polyhaven.com
• GitHub Issues: Report a bug

---

💡 Tips

• Use desktop_list_projects to discover your 8th Wall Desktop projects
• Search PolyHaven for free 3D assets, textures, and HDRIs
• Test AR features on a phone for camera preview
• Use hider materials (colorWrite: false) for AR portal effects
• Enable physics for dynamic objects
• Use animations to bring your scenes to life

---

🙏 Acknowledgments

• 8th Wall for their amazing WebAR platform
• Anthropic for Claude and the MCP protocol
• PolyHaven for free 3D assets
• The MCP Community for tools and inspiration

---

Built with ❤️ by Dwayne Paisley-Marshall