m{ai}geXR-3d-mcp

El servidor MCP 3D multi-framework que realmente funciona. Controla escenas en vivo de Three.js, A-Frame, Babylon.js y React Three Fiber desde cualquier IA compatible con MCP — GitHub Copilot, Claude Desktop, Cursor, lo que sea — con chat asíncrono en el mundo para que puedas hablar con la IA desde dentro del lienzo 3D mientras esta remodela el mundo a tu alrededor.

Los cuatro clientes de framework renderizan resultados coincidentes y visualmente alineados a partir de un estado de escena unificado. Mismo prompt, misma escena, cualquier motor.

Aspectos destacados

• 4 clientes 3D listos para producción — Three.js, A-Frame (1.7.0 + bloom), Babylon.js (PBR), React Three Fiber + Zustand — todos visualmente alineados

• Soporte para WebXR / VR — entra en realidad virtual inmersiva en los cuatro clientes; el panel de chat flotante sigue tu mirada para que puedas hablar con la IA desde dentro del visor

• 9 proveedores de IA listos para usar — OpenAI (GPT-5.2), Anthropic (Claude Sonnet 4.6), Google Gemini 3.1 Pro, Mistral, Groq (Llama 3.3 70B), xAI Grok-4, Cohere Command R+, Together.ai y Ollama local

• 23 herramientas MCP — objetos, luces, cámaras, animación, entorno, E/S de escena, deshacer/rehacer, capturas de pantalla y chat en el mundo

• Animaciones persistentes — las animaciones sobreviven a las recargas de página; el servidor almacena las animaciones activas en el estado de la escena y las reproduce cuando los clientes se reconectan

• Animaciones concurrentes — múltiples propiedades (posición, rotación, escala) se animan simultáneamente en el mismo objeto en todos los motores

• Prompts del sistema por framework — cada cliente le dice a la IA cómo generar geometrías, materiales e iluminación que se vean correctos en ese motor (adaptado de la aplicación iOS maigeXR)

• Chat en el mundo — presiona ~ para hablar con la IA sin salir del visor 3D; lee tus mensajes y responde en una superposición flotante

• IA consciente de la escena — historial de conversación de 20 turnos + inyección de estado de escena en vivo asegura que la IA realice ediciones incrementales, no reconstrucciones destructivas

• Un comando — pnpm dev inicia el servidor + los cuatro clientes simultáneamente; abre automáticamente el cliente de Three.js en tu navegador

• Proveedor de IA intercambiable en caliente — cambia de proveedor a mitad de la sesión desde el menú desplegable del cliente; no se requiere reinicio

Related MCP server: Unity MCP

Inicio rápido

Opción A — npx (no se necesita clonar)

npx maige-3d-mcp

Esto inicia el servidor MCP a través de stdio. Apunta tu cliente MCP (VS Code Copilot, Claude Desktop, Cursor) al comando npx maige-3d-mcp.

Opción B — desde el código fuente

1. Instalar

cd mcp-webgpu
pnpm install

2. Configurar

cp .env.example .env

Agrega al menos una clave API. Todas las variables:

Cada proveedor también tiene una variable de entorno *_MODEL (ej. OPENAI_MODEL=gpt-4.1) — consulta .env.example para ver todos los modelos disponibles.

Dos modos de chat:

• Modo relé (no se necesita clave): la IA anfitriona de MCP (Copilot, Claude Desktop) maneja el chat en el mundo mediante el sondeo de getPendingUserMessages.

• Modo directo (clave en .env): el servidor responde al chat de forma autónoma utilizando el proveedor configurado.

3. Construir y ejecutar

pnpm build:server # compile TypeScript once
pnpm dev # start server + all 4 clients

Los clientes se abren en:

4. Registrar con VS Code Copilot

El archivo .vscode/mcp.json está preconfigurado. Recarga VS Code y maige-3d-mcp aparecerá en el modo agente de Copilot.

Alternativamente, agrégalo a tu configuración global de VS Code:

// .vscode/mcp.json (already included)
{
 "servers": {
 "maige-3d-mcp": {
 "type": "stdio",
 "command": "node",
 "args": ["packages/server/build/main.js"],
 "env": {
 "OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
 "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}",
 "GOOGLE_API_KEY": "${env:GOOGLE_API_KEY}"
 }
 }
 }
}

Proveedores de IA compatibles (9)

Cambia de proveedor desde el menú desplegable en la superposición de chat o cambiando CHAT_PROVIDER en .env. Sobrescribe el modelo por proveedor con variables de entorno *_MODEL (consulta .env.example).

Herramientas MCP disponibles (23)

Objetos

Luces

createLight · updateLight · deleteLight — ambiental, direccional, puntual, foco, hemisférica

Cámara

setCamera · flyToObject

Animación

animateObject · stopAnimation — rotar, rebotar, pulsar, flotar, girar, fotogramas clave personalizados. Las animaciones persisten en el estado del servidor y se reproducen automáticamente al recargar la página. Múltiples propiedades se animan simultáneamente por objeto.

Entorno

setEnvironment — color de fondo, niebla, mapeo de tonos, exposición, alternancia de sombras

Escena

clearScene · loadScene · exportScene · undo · redo · takeScreenshot

Chat en el mundo

Recursos MCP

Prompts MCP

Soporte para WebXR / VR

Los cuatro clientes admiten realidad virtual inmersiva a través de WebXR. Haz clic en el botón 🥽 Enter VR (abajo a la izquierda) para iniciar una sesión.

En VR, el panel de chat flota frente a ti y sigue tu mirada. Las respuestas de la IA aparecen en tiempo real para que puedas dirigir la escena desde dentro del visor.

Requiere un navegador compatible con WebXR (Chrome 79+, Edge 79+, Meta Quest Browser) y un visor de VR o la extensión WebXR API Emulator para pruebas en escritorio.

Chat en el mundo

Presiona ~ (acento grave) o haz clic en AI Chat en la esquina inferior derecha. Escribe un mensaje, presiona Enter y la IA lo recibirá, actuará sobre él y responderá, todo sin salir del visor 3D. La superposición de chat también incluye:

• Selector de proveedor — cambia de proveedor de IA sobre la marcha

• Editor de prompts del sistema — personaliza el comportamiento de la IA por sesión

• Botón Clear Scene — restablece el mundo al instante

• Panel de depuración — presiona Escape para inspeccionar el estado de la escena y la información de conexión

Arquitectura

┌─────────────────────────┐
│ MCP Host (Copilot, │ stdio / JSON-RPC
│ Claude, Cursor, etc.) │◄────────────────────┐
└─────────────────────────┘ │
 │
 ┌──────────────────┴──────────────────┐
 │ MCP Server (Node.js) │
 │ │
 │ tools/ ─ 23 tool definitions │
 │ state/ ─ SceneStateManager + Undo │
 │ chat/ ─ ChatRelay (9 providers) │
 │ ws/ ─ WebSocket bridge :8083 │
 │ └── adapters/ (per-framework) │
 └──────────┬───────────────────────────┘
 │ WebSocket
 ┌────────────────┬───────────────┼───────────────┬────────────────┐
 ▼ ▼ ▼ ▼ │
┌──────────────┐ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ │
│ Three.js │ │ A-Frame │ │ Babylon.js │ │ R3F / React │ │
│ :5173 │ │ :5174 │ │ :5175 │ │ :5176 │ │
│ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │
│ │VR/WebXR │ │ │ │VR/WebXR │ │ │ │VR/WebXR │ │ │ │VR/WebXR │ │ │
│ │ChatPanel │ │ │ │ChatPanel │ │ │ │ChatPanel │ │ │ │ChatPanel │ │ │
│ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ │
└──────────────┘ └──────────────┘ └───────────────┘ └──────────────┘

Cada cliente se conecta a través de WebSocket al mismo servidor MCP. El servidor mantiene un estado de escena canónico único y envía comandos a través de adaptadores por framework que traducen formatos Vec3, modelos de materiales y nombres de geometría a la representación nativa de cada motor.

Características clave del servidor:

• Historial de conversación — la IA recuerda los últimos 20 turnos de diálogo, evitando reconstrucciones destructivas de la escena

• Inyección de estado de escena — cada llamada de IA incluye un resumen de los objetos, luces y entorno actuales para que la IA sepa qué existe ya

• Prompts del sistema por framework — cada cliente le dice a la IA cómo generar geometrías, materiales e iluminación que se vean correctos en ese motor específico

• Deshacer/rehacer — pila de instantáneas de 20 niveles en el servidor, activada a través de herramientas MCP

• Persistencia de animación — las animaciones activas se almacenan en el estado de la escena y se reproducen al reconectarse, por lo que las animaciones en bucle sobreviven a las recargas de página

Diseño del proyecto

mcp-webgpu/
├── .env.example ← all env vars + model lists documented
├── .vscode/mcp.json ← pre-configured for VS Code Copilot agent mode
├── package.json ← pnpm workspace root
├── PLAN.md ← full architecture plan
├── packages/
│ ├── server/ ← MCP server (TypeScript / Node)
│ │ └── src/
│ │ ├── main.ts ← entry + .env discovery
│ │ ├── types.ts ← shared types
│ │ ├── tools/ ← 23 MCP tool definitions
│ │ ├── handlers/ ← tool / prompt / resource handlers
│ │ ├── state/ ← SceneStateManager + UndoStack
│ │ ├── chat/ ← ChatRelay (9 providers) + MessageQueue
│ │ └── ws/ ← WebSocket server + framework adapters
│ │ └── adapters/ ← ThreeAdapter, AFrameAdapter,
│ │ BabylonAdapter, R3FAdapter
│ ├── client-threejs/ ← Three.js (Vite)
│ │ └── src/
│ │ ├── scene.ts ← SceneManager
│ │ ├── commands/ ← command dispatcher
│ │ ├── overlay/ ← ChatOverlay UI
│ │ └── vr/ ← VRSetup + VRChatPanel (WebXR)
│ ├── client-aframe/ ← A-Frame 1.7.0 + bloom (Vite)
│ │ └── src/
│ │ ├── scene.ts ← A-Frame SceneManager
│ │ ├── commands/ ← command dispatcher
│ │ └── overlay/ ← ChatOverlay UI
│ ├── client-babylonjs/ ← Babylon.js + PBR (Vite)
│ │ └── src/
│ │ ├── scene.ts ← Babylon SceneManager
│ │ ├── commands/ ← command dispatcher
│ │ └── overlay/ ← ChatOverlay UI
│ └── client-r3f/ ← React Three Fiber + Zustand (Vite)
│ └── src/
│ ├── App.tsx ← React app shell
│ ├── SceneCanvas.tsx ← R3F canvas + XR wrapper
│ ├── store/ ← Zustand scene store
│ ├── commands/ ← command dispatcher
│ ├── overlay/ ← ChatOverlay UI
│ └── vr/ ← VRChatPanel (React XR component)

Hoja de ruta

• [x] Fase 1 — Cliente Three.js + conjunto completo de herramientas + chat en el mundo

• [x] Fase 2 — Cliente A-Frame (1.7.0, post-procesamiento bloom) + cliente Babylon.js (materiales PBR)

• [x] Fase 3 — Cliente React Three Fiber (estado Zustand, ayudantes drei)

• [x] Fase 3.5 — 9 proveedores de IA, prompts del sistema por framework, alineación visual en los 4 motores

• [x] Fase 4 — Soporte para WebXR / visor VR (los 4 clientes + panel de chat VR flotante)

• [x] Fase 5 — Configuración MCP de VS Code, navegador de apertura automática, historial de conversación + conciencia del estado de la escena

• [x] Fase 6

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• addBehaviorA
• animateObjectA
• clearPendingMessagesA
• clearSceneA
• cloneObjectC
• createLightC
• createObjectA
• createParticlesA