MCP 3D

Descripción general

3D-MCP es una implementación universal del Protocolo de Contexto de Modelo para software 3D. Crea una interfaz TypeScript unificada para que los LLM interactúen con Blender, Maya, Unreal Engine y otras aplicaciones 3D mediante una única API coherente.

// LLMs use the same interface regardless of underlying 3D software
await tools.animation.createKeyframe({
  objectId: "cube_1",
  property: "rotation.x",
  time: 30,
  value: Math.PI/2
});

Filosofía central y decisiones de diseño

3D-MCP se basa en cuatro principios arquitectónicos interconectados que juntos crean un sistema unificado para la creación de contenido 3D:

Diseño que prioriza la entidad : las entidades de dominio bien definidas forman la base de todas las operaciones, lo que permite un modelado de datos consistente en todas las plataformas.
Operaciones CRUD de tipo seguro : generación automatizada de operaciones de creación, lectura, actualización y eliminación con validación de tipo completa
Capa de operación atómica : un conjunto mínimo de implementaciones específicas de la plataforma que manejan operaciones fundamentales
Arquitectura de herramientas componibles : funcionalidad compleja creada mediante la combinación de operaciones atómicas de manera independiente de la plataforma.

Esta arquitectura crea una inversión de dependencia donde los detalles de implementación específicos de la plataforma se aíslan en operaciones atómicas, mientras que la mayoría de la base del código permanece independiente de la plataforma.

┌─────────────────────────────────────────────────────────────────────────┐
│                             LLM / User API                              │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ MCP Tool API
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          Compound Operations                            │
│                                                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │ Modeling Tools  │  │ Animation Tools │  │ Rigging Tools           │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Implemented by
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           Atomic Operations                             │
│                                                                         │
│  ┌─────────── Entity CRUD ────────────┐ ┌────────── Non-CRUD ─────────┐ │ 
│  │ create{Entity}s update{Entity}s ...│ │  select, undo, redo, etc.   │ │  
│  └────────────────────────────────────┘ └─────────────────────────────┘ │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Plug-in Server Request
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                       Platform-Specific Adapters                        │
│                                                                         │
│  ┌──── Blender ────┐  ┌────── Maya ─────┐  ┌─── Unreal Engine ────┐     │
│  │ createKeyframes │  │ createKeyframes │  │ createKeyframes      │     │    
│  └─────────────────┘  └─────────────────┘  └──────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────┘

¿Por qué estas decisiones de diseño?

Se eligió el diseño Entity-First porque:

Las aplicaciones 3D utilizan diferentes modelos de objetos pero comparten conceptos centrales (mallas, materiales, animaciones)
Los esquemas Zod proporcionan una única fuente de verdad para la validación, la tipificación y la documentación.
La tipificación fuerte detecta errores en tiempo de compilación en lugar de en tiempo de ejecución
Los metadatos enriquecidos permiten una mejor comprensión de la IA de los objetos del dominio

Operaciones CRUD como base porque:

Se corresponden claramente con lo que las aplicaciones 3D necesitan hacer con las entidades.
Los patrones estandarizados reducen la sobrecarga cognitiva
La generación automática elimina el código repetitivo mediante createCrudOperations
Cada entidad obtiene automáticamente la misma interfaz consistente

Separación de herramientas atómicas y compuestas porque:

Solo las herramientas atómicas necesitan una implementación específica de la plataforma (aproximadamente el 20 % del código base)
Las herramientas compuestas funcionan en todas las plataformas sin modificaciones (aproximadamente el 80 % del código base)
Las nuevas plataformas solo necesitan implementar operaciones atómicas para obtener toda la funcionalidad
Arquitectura mantenible con clara separación de preocupaciones

Arquitectura técnica

1. Arquitectura CRUD centrada en la entidad

La base del sistema es un rico sistema de tipos de entidades de dominio que genera operaciones CRUD:

// Define entities with rich metadata using Zod
export const Mesh = NodeBase.extend({
  vertices: z.array(Tensor.VEC3).describe("Array of vertex positions [x, y, z]"),
  normals: z.array(Tensor.VEC3).optional().describe("Array of normal vectors"),
  // ... other properties
});

// CRUD operations generated automatically from entity schemas
const entityCruds = createCrudOperations(ModelEntities);
// => Creates createMeshs, getMeshs, updateMeshs, deleteMeshs, listMeshs

// All operations preserve complete type information
await tool.createRigControls.execute({
  name: "arm_ctrl",          
  shape: "cube",            // TypeScript error if not a valid enum value
  targetJointIds: ["joint1"], // Must be string array
  color: [0.2, 0.4, 1],     // Must match Color schema format
  // IDE autocomplete shows all required/optional fields
});

Los esquemas de entidad proporcionan:

Validación de esquema : Comprobación de parámetros en tiempo de ejecución con mensajes de error detallados
Información de tipo : tipos TypeScript completos para asistencia IDE
Documentación : API autodocumentada con descripciones
Generación de código : plantillas para implementaciones específicas de la plataforma

Diagrama de arquitectura de entidades

┌──────────────────────────────────────────────────────────────┐
│                Core Entity Definitions                       │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│  │ BaseEntity  │  │ NodeBase    │  │ Other Core Entities │   │
│  └─────────────┘  └─────────────┘  └─────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                           ▲
                           │ extends
                           │
┌──────────────────────────────────────────────────────────────┐
│                Domain-Specific Entities                      │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│  │ Model       │  │ Animation   │  │ Rigging             │   │
│  │ Entities    │  │ Entities    │  │ Entities            │   │
│  └─────────────┘  └─────────────┘  └─────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                           │
                           │ input to
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                Automatic CRUD Generation                     │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ createCrudOperations(Entities)                          │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
                           │
                           │ generates
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                     Atomic Operations                        │
│                                                              │
│  ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐    │
│  │ create{Entity}s │ │ get{Entity}s │ │ update{Entity}s │ .. │
│  └─────────────────┘ └──────────────┘ └─────────────────┘    │
└──────────────────────────────────────────────────────────────┘
                           │
                           │ foundation for
                           ▼
┌──────────────────────────────────────────────────────────────┐
│                    Compound Operations                       │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ No need for platform-specific code. Use atomic ops only.│ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

2. Arquitectura de herramientas compuestas

El sistema crea una clara separación entre operaciones atómicas y compuestas:

// From compounded.ts - Higher level operations composed from atomic operations
createIKFKSwitch: defineCompoundTool({
  // ...parameter and return definitions...
  execute: async (params) => {
    // Create IK chain using atomic operations
    const ikChainResult = await tool.createIKChains.execute({/*...*/});
    
    // Create control with full type-checking
    const ikControlResult = await tool.createRigControls.execute({
      name: `${switchName}_IK_CTRL`,
      shape: ikControlShape,  // Type-checked against schema
      targetJointIds: [jointIds[jointIds.length - 1]],
      color: ikColor,
      // ...other parameters
    });
    
    // Position the control at the end effector
    await tool.batchTransform.execute({/*...*/});
    
    // Create constraints to connect the system
    await tool.createConstraint.execute({/*...*/});
    
    // Return standardized response with created IDs
    return {
      success: true,
      switchControlId: switchControlResult.id,
      ikControlId: ikControlResult.id,
      fkControlIds,
      poleVectorId: poleVectorId || undefined,
    };
  }
})

Esta arquitectura proporciona varias ventajas técnicas:

Operaciones atómicas (~20% del sistema):
- Interactuar directamente con las API de la plataforma
- Necesita implementaciones específicas de la plataforma
- Centrarse en operaciones de entidad única (crear, leer, actualizar, eliminar)
- Formulario de implementación mínima requerido para nuevas plataformas
Operaciones compuestas (~80% del sistema):
- Construido íntegramente a partir de operaciones atómicas
- Código cero específico de la plataforma
- Implementar conceptos de dominio de nivel superior
- Trabaja en cualquier plataforma sin modificaciones

Flujo de composición de herramientas

┌─────────────────────────────────────────────────────────────────────────┐
│                        High-Level Tool Definition                       │
└──────────────────────────────────────┬──────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Compound Tool Pattern                           │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │ defineCompoundTool({                                             │   │
│  │   description: string,                                           │   │
│  │   parameters: zod.Schema,                                        │   │
│  │   returns: zod.Schema,                                           │   │
│  │   execute: async (params) => {                                   │   │
│  │     // Composed entirely from atomic operations                  │   │
│  │     await tool.atomicOperation1.execute({...});                  │   │
│  │     await tool.atomicOperation2.execute({...});                  │   │
│  │     return { success: true, ...results };                        │   │
│  │   }                                                              │   │
│  │ })                                                               │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Plug-in Server Request
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         Platform Adaptation                             │
│                                                                         │
│  ┌──────────────────────────┐  ┌─────────────────────────────────────┐  │
│  │ Blender Implementation   │  │ Maya Implementation                 │  │
│  │ of Atomic Operations     │  │ of Atomic Operations                │  │
│  └──────────────────────────┘  └─────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

Archivos clave para la arquitectura de herramientas compuestas:

Compounded.ts: herramientas de modelado compuesto
Compounded.ts: Herramientas de animación compuesta
Compounded.ts: Herramientas de aparejo compuesto

3. Canalización de generación de código

El sistema genera automáticamente implementaciones específicas de la plataforma a partir de definiciones de TypeScript:

┌─────────────────┐     ┌────────────────────┐     ┌─────────────────────────┐
│ Entity Schemas  │     │ Schema             │     │ Platform-Specific Code  │
│ & Tools (TS)    │ ──> │ Extraction (TS)    │ ──> │ (Python/C++/etc.)       │
└─────────────────┘     └────────────────────┘     └─────────────────────────┘
      │                        │                             │
      │                        │                             │
      ▼                        ▼                             ▼
┌─────────────────┐     ┌────────────────────┐     ┌─────────────────────────┐
│ Type            │     │ Parameter          │     │ Implementation          │
│ Definitions     │     │ Validation         │     │ Templates               │
└─────────────────┘     └────────────────────┘     └─────────────────────────┘

Aspectos claves del sistema de generación:

Extracción de entidades : analiza los esquemas Zod para comprender la estructura de las entidades.
Mapeo de parámetros : convierte tipos de TypeScript en tipos nativos de la plataforma
Generación de validación : crea una validación de parámetros en los idiomas de destino
Plantillas de implementación : proporciona patrones de código específicos de la plataforma

El sistema de generación de código se implementa en:

plugin-codegen.ts : Script de generación de código principal
extract-schemas.ts : extrae esquemas Zod de archivos TypeScript en archivos JSON temporales.

4. Organización del dominio

El sistema está organizado en dominios que reflejan flujos de trabajo de creación de contenido 3D:

Núcleo : Entidades base y operaciones utilizadas en todos los dominios
Modelado : creación de mallas, edición y operaciones de topología
Animación : fotogramas clave, curvas, clips y control de animación
Aparejo : sistemas esqueléticos, controles y deformación
Renderizado : materiales, luces y configuraciones de renderizado

Cada dominio sigue el mismo patrón organizativo:

entity.ts : definiciones de entidades específicas del dominio
atomic.ts : Operaciones atómicas para entidades de dominio
compounded.ts : Operaciones de alto nivel creadas a partir de herramientas atómicas

Diagrama de estructura del dominio

packages/src/tool/
│
├── core/                  # Core shared components
│   ├── entity.ts          # Base entities all domains use
│   ├── utils.ts           # Shared utilities including CRUD generation
│   └── ...
│
├── model/                 # Modeling domain
│   ├── entity.ts          # Mesh, Vertex, Face, etc.
│   ├── atomic.ts          # Atomic modeling operations
│   ├── compounded.ts      # Higher-level modeling tools
│   └── ...
│
├── animation/             # Animation domain
│   ├── entity.ts          # Keyframe, AnimCurve, Clip, etc.
│   ├── atomic.ts          # Atomic animation operations
│   ├── compounded.ts      # Higher-level animation tools
│   └── ...
│
├── rig/                   # Rigging domain
│   ├── entity.ts          # Joint, IKChain, Control, etc.
│   ├── atomic.ts          # Atomic rigging operations
│   ├── compounded.ts      # Higher-level rigging tools
│   └── ...
│
└── rendering/             # Rendering domain
    ├── entity.ts          # Camera, Light, RenderSettings, etc.
    ├── atomic.ts          # Atomic rendering operations
    ├── compounded.ts      # Higher-level rendering tools
    └── ...

5. Arquitectura CRUD centrada en la entidad

El sistema implementa un sofisticado enfoque centrado en la entidad donde:

Entidades como modelos de dominio : Cada dominio (modelado, animación, rigging) define sus entidades principales, que representan sus conceptos fundamentales. Estas se implementan como esquemas Zod con información de tipos completa.
CRUD como base : cada entidad recibe automáticamente un conjunto completo de operaciones CRUD (crear, leer, actualizar, eliminar) a través de la utilidad createCrudOperations :

// Each domain starts with CRUD operations for all its entities
const entityCruds = createCrudOperations(ModelEntities);

const modelAtomicTools = {
  ...entityCruds,  // Foundation of all atomic tools
  // Domain-specific operations build on this foundation
}

Reutilización y herencia de entidades : las entidades principales definidas en core/entity.ts se amplían mediante entidades específicas del dominio, lo que promueve la reutilización de código y un diseño consistente en todos los dominios.
Arquitectura inspirada en DDD : el sistema sigue los principios de diseño impulsado por el dominio al organizar el código en torno a entidades y agregados del dominio en lugar de preocupaciones técnicas.

Esta arquitectura proporciona varios beneficios clave:

Consistencia : Todas las entidades tienen los mismos patrones para las operaciones básicas
Boilerplate reducido : las operaciones CRUD se generan automáticamente
Organización clara : las herramientas están organizadas en torno a entidades de dominio
Separación de preocupaciones : cada dominio administra sus propias entidades mientras comparte patrones comunes

La combinación de modelos de entidades enriquecidas con operaciones CRUD automáticas crea una base sólida que simplifica el desarrollo y al mismo tiempo mantiene la flexibilidad para las operaciones específicas del dominio.

Empezando

# Install dependencies
bun install

# Run the server
bun run index.ts

# Extract schemas and generate plugins
bun run packages/scripts/plugin-codegen.ts

Flujo de trabajo de desarrollo

Definir entidades : crear o ampliar esquemas de entidades en src/tool/<domain>/entity.ts
Generar CRUD : utilice createCrudOperations para generar operaciones atómicas
Crear herramientas compuestas : cree operaciones de nivel superior a partir de herramientas atómicas
Generar complementos : ejecute el generador de código para crear implementaciones específicas de la plataforma

Contribuyendo

Las decisiones arquitectónicas en 3D-MCP lo hacen excepcionalmente extensible:

Agregar nuevas entidades : define nuevas entidades y obtén automáticamente operaciones CRUD
Agregar nuevas herramientas compuestas : combine operaciones atómicas existentes para crear nuevas funcionalidades
Agregar nuevas plataformas : Implementar las interfaces de herramientas atómicas en un nuevo complemento

Consulte nuestra guía de contribución para obtener más detalles sobre cómo contribuir.

3D-MCP: Una API para gobernar todo el software 3D

3D-MCP

Integrations