3D-MCP
Überblick
3D-MCP ist eine universelle Implementierung des Model Context Protocol für 3D-Software. Es erstellt eine einheitliche TypeScript-Schnittstelle für LLMs zur Interaktion mit Blender, Maya, Unreal Engine und anderen 3D-Anwendungen über eine einzige, kohärente API.
// 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
});
Kernphilosophie und Designentscheidungen
3D-MCP basiert auf vier miteinander verbundenen Architekturprinzipien, die zusammen ein einheitliches System für die Erstellung von 3D-Inhalten bilden:
- Entity-First-Design : Gut definierte Domänenentitäten bilden die Grundlage aller Vorgänge und ermöglichen eine konsistente Datenmodellierung über alle Plattformen hinweg
- Typsichere CRUD-Operationen : Automatisierte Generierung von Erstellungs-, Lese-, Aktualisierungs- und Löschoperationen mit vollständiger Typvalidierung
- Atomic Operation Layer : Ein minimaler Satz plattformspezifischer Implementierungen, die grundlegende Operationen handhaben
- Zusammensetzbare Tool-Architektur : Komplexe Funktionalität, die durch die plattformunabhängige Kombination atomarer Operationen entsteht
Diese Architektur erzeugt eine Abhängigkeitsumkehr, bei der plattformspezifische Implementierungsdetails auf atomare Operationen beschränkt bleiben, während der Großteil der Codebasis plattformunabhängig bleibt.
┌─────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────┘ └─────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Warum diese Designentscheidungen?
Entity-First-Design wurde gewählt, weil:
- 3D-Anwendungen verwenden unterschiedliche Objektmodelle, teilen aber Kernkonzepte (Netze, Materialien, Animationen).
- Zod-Schemata bieten eine zentrale Informationsquelle für Validierung, Typisierung und Dokumentation
- Durch strenge Typisierung werden Fehler zur Kompilierzeit und nicht zur Laufzeit erkannt
- Umfangreiche Metadaten ermöglichen ein besseres KI-Verständnis von Domänenobjekten
CRUD-Operationen als Grundlage, weil:
- Sie bilden klar ab, was 3D-Anwendungen mit Entitäten tun müssen
- Standardisierte Muster reduzieren den kognitiven Aufwand
- Automatische Generierung eliminiert repetitiven Code mithilfe von
createCrudOperations - Jede Entität erhält automatisch die gleiche konsistente Schnittstelle
Trennung von atomaren und zusammengesetzten Werkzeugen, weil:
- Nur atomare Tools benötigen eine plattformspezifische Implementierung (~20 % der Codebasis)
- Compound-Tools funktionieren auf allen Plattformen ohne Änderungen (~80 % der Codebasis)
- Neue Plattformen müssen nur atomare Operationen implementieren, um alle Funktionen zu erhalten
- Wartbare Architektur mit klarer Trennung der Belange
Technische Architektur
1. Entity-Centric CRUD-Architektur
Die Grundlage des Systems ist ein umfangreiches Typsystem von Domänenentitäten, das CRUD-Operationen generiert:
// 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
});
Entitätsschemata bieten:
- Schemavalidierung : Laufzeitparameterprüfung mit detaillierten Fehlermeldungen
- Typinformationen : Vollständige TypeScript-Typen zur IDE-Unterstützung
- Dokumentation : Selbstdokumentierende API mit Beschreibungen
- Codegenerierung : Vorlagen für plattformspezifische Implementierungen
Entity-Architekturdiagramm
┌──────────────────────────────────────────────────────────────┐
│ 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. Zusammengesetzte Werkzeugarchitektur
Das System schafft eine klare Trennung zwischen atomaren und zusammengesetzten Operationen:
// 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,
};
}
})
Diese Architektur bietet mehrere technische Vorteile:
- Atomare Operationen (~20 % des Systems):
- Direkte Interaktion mit Plattform-APIs
- Benötigen plattformspezifische Implementierungen
- Konzentrieren Sie sich auf einzelne Entitätsvorgänge (Erstellen, Lesen, Aktualisieren, Löschen).
- Für neue Plattformen ist nur eine minimale Implementierung erforderlich
- Zusammengesetzte Operationen (~80 % des Systems):
- Vollständig aus atomaren Operationen aufgebaut
- Kein plattformspezifischer Code
- Implementieren übergeordneter Domänenkonzepte
- Funktioniert auf jeder Plattform ohne Änderungen
Werkzeugzusammensetzungsfluss
┌─────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Schlüsseldateien für die zusammengesetzte Toolarchitektur:
- compounded.ts: Werkzeuge zur zusammengesetzten Modellierung
- compounded.ts: Zusammengesetzte Animationstools
- compounded.ts: Werkzeuge für zusammengesetzte Takelage
3. Codegenerierungs-Pipeline
Das System generiert automatisch plattformspezifische Implementierungen aus TypeScript-Definitionen:
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
│ Entity Schemas │ │ Schema │ │ Platform-Specific Code │
│ & Tools (TS) │ ──> │ Extraction (TS) │ ──> │ (Python/C++/etc.) │
└─────────────────┘ └────────────────────┘ └─────────────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
│ Type │ │ Parameter │ │ Implementation │
│ Definitions │ │ Validation │ │ Templates │
└─────────────────┘ └────────────────────┘ └─────────────────────────┘
Wesentliche Aspekte des Erzeugungssystems:
- Entitätsextraktion : Analysiert Zod-Schemata, um die Entitätsstruktur zu verstehen
- Parameterzuordnung : Konvertiert TypeScript-Typen in plattformnative Typen
- Validierungsgenerierung : Erstellt Parametervalidierungen in Zielsprachen
- Implementierungsvorlagen : Bietet plattformspezifische Codemuster
Das Codegenerierungssystem ist implementiert in:
4. Domänenorganisation
Das System ist in Domänen organisiert, die die Arbeitsabläufe zur Erstellung von 3D-Inhalten widerspiegeln:
- Kern : Grundlegende Entitäten und Operationen, die in allen Domänen verwendet werden
- Modellierung : Netzerstellung, Bearbeitung und Topologieoperationen
- Animation : Keyframes, Kurven, Clips und Animationssteuerung
- Takelage : Skelettsysteme, Steuerungen und Deformation
- Rendering : Materialien, Lichter und Rendereinstellungen
Jede Domäne folgt demselben Organisationsmuster:
entity.ts : Domänenspezifische Entitätsdefinitionenatomic.ts : Atomare Operationen für Domänenentitätencompounded.ts : Höherstufige Operationen, die aus atomaren Tools erstellt wurden
Domänenstrukturdiagramm
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. Entity-Centric CRUD-Architektur
Das System implementiert einen ausgeklügelten entitätszentrierten Ansatz, bei dem:
- Entitäten als Domänenmodelle : Jede Domäne (Modellierung, Animation, Rigging) definiert ihre Kernentitäten, die ihre grundlegenden Konzepte darstellen. Diese werden als Zod-Schemata mit umfangreichen Typinformationen implementiert.
- CRUD als Grundlage : Jede Entität erhält automatisch einen vollständigen Satz von CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Löschen) über das Dienstprogramm
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
}
- Wiederverwendung und Vererbung von Entitäten : In
core/entity.ts definierte Kernentitäten werden durch domänenspezifische Entitäten erweitert, was die Wiederverwendung von Code und ein konsistentes Design über Domänen hinweg fördert. - DDD-inspirierte Architektur : Das System folgt den Prinzipien des domänengesteuerten Designs, indem es den Code um Domänenentitäten und -aggregate herum organisiert, anstatt um technische Belange.
Diese Architektur bietet mehrere wichtige Vorteile:
- Konsistenz : Alle Entitäten haben die gleichen Muster für grundlegende Operationen
- Reduzierter Boilerplate : CRUD-Operationen werden automatisch generiert
- Klare Organisation : Die Tools sind um Domänenentitäten herum organisiert
- Trennung der Belange : Jede Domäne verwaltet ihre eigenen Entitäten und teilt dabei gemeinsame Muster
Die Kombination umfangreicher Entitätsmodelle mit automatischen CRUD-Operationen schafft eine robuste Grundlage, die die Entwicklung vereinfacht und gleichzeitig die Flexibilität für domänenspezifische Operationen aufrechterhält.
Erste Schritte
# Install dependencies
bun install
# Run the server
bun run index.ts
# Extract schemas and generate plugins
bun run packages/scripts/plugin-codegen.ts
Entwicklungs-Workflow
- Entitäten definieren : Erstellen oder erweitern Sie Entitätsschemata in
src/tool/<domain>/entity.ts - CRUD generieren : Verwenden Sie
createCrudOperations , um atomare Operationen zu generieren - Zusammengesetzte Tools erstellen : Erstellen Sie Operationen auf höherer Ebene aus atomaren Tools
- Plugins generieren : Führen Sie den Codegenerator aus, um plattformspezifische Implementierungen zu erstellen
Beitragen
Die architektonischen Entscheidungen in 3D-MCP machen es einzigartig erweiterbar:
- Neue Entitäten hinzufügen : Definieren Sie neue Entitäten und erhalten Sie automatisch CRUD-Operationen
- Neue zusammengesetzte Tools hinzufügen : Kombinieren Sie vorhandene atomare Operationen, um neue Funktionen zu erstellen
- Neue Plattformen hinzufügen : Implementieren Sie die atomaren Tool-Schnittstellen in einem neuen Plugin
Weitere Einzelheiten zum Beitragen finden Sie in unserem Leitfaden zum Beitragen.
3D-MCP: Eine API für alle 3D-Software