3D Model Context Protocol
3D MCP предлагает единый TypeScript-интерфейс для LLM, позволяющий управлять Blender, Maya и Unreal Engine. Автоматизируйте создание 3D-контента с помощью типобезопасных CRUD-операций и платформонезависимых инструментов.
3D-MCP — это универсальная реализация протокола контекста модели для 3D-программного обеспечения, предоставляющая единый интерфейс TypeScript для больших языковых моделей (LLM) для взаимодействия с 3D-приложениями, такими как Blender, Maya и Unreal Engine. Она абстрагирует платформенно-зависимые сложности с помощью дизайна, ориентированного на сущности, типобезопасных CRUD-операций и четкого разделения атомарных и составных операций, что позволяет разработчикам создавать платформенно-независимые инструменты для 3D-контента. Благодаря изоляции деталей реализации и автоматизации генерации кода, 3D-MCP способствует поддерживаемости и упрощает разработку управляемых ИИ 3D-рабочих процессов.
Ключевые особенности
Примеры использования
3D-MCP is a universal implementation of the Model Context Protocol for 3D software. It creates a unified TypeScript interface for LLMs to interact with Blender, Maya, Unreal Engine, and other 3D applications through a single coherent 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
});3D-MCP is built on four interconnected architectural principles that together create a unified system for 3D content creation:
- Entity-First Design: Well-defined domain entities form the foundation of all operations, enabling consistent data modeling across platforms
- Type-Safe CRUD Operations: Automated generation of create, read, update, delete operations with complete type validation
- Atomic Operation Layer: A minimal set of platform-specific implementations that handle fundamental operations
- Composable Tool Architecture: Complex functionality built by combining atomic operations in a platform-agnostic way
This architecture creates a dependency inversion where platform-specific implementation details are isolated to atomic operations, while the majority of the codebase remains platform-independent.
┌─────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────┘ └─────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Entity-First Design was chosen because:
- 3D applications use different object models but share core concepts (meshes, materials, animations)
- Zod schemas provide single-source-of-truth for validation, typing, and documentation
- Strong typing catches errors at compile time rather than runtime
- Rich metadata enables better AI understanding of domain objects
CRUD Operations as Foundation because:
- They map cleanly to what 3D applications need to do with entities
- Standardized patterns reduce cognitive overhead
- Auto-generation eliminates repetitive code using
createCrudOperations - Every entity automatically gets the same consistent interface
Atomic and Compound Tool Separation because:
- Only atomic tools need platform-specific implementation (~20% of codebase)
- Compound tools work across all platforms without modification (~80% of codebase)
- New platforms only need to implement atomic operations to gain all functionality
- Maintainable architecture with clear separation of concerns
The system's foundation is a rich type system of domain entities that generates CRUD operations:
// 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
});Entity schemas provide:
- Schema Validation: Runtime parameter checking with detailed error messages
- Type Information: Complete TypeScript types for IDE assistance
- Documentation: Self-documenting API with descriptions
- Code Generation: Templates for platform-specific implementations
┌──────────────────────────────��───────────────────────────────┐
│ 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.│ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
The system creates a clear separation between atomic and compound operations:
// 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,
};
}
})This architecture provides several technical advantages:
-
Atomic Operations (~20% of the system):
- Directly interact with platform APIs
- Need platform-specific implementations
- Focus on single entity operations (create, read, update, delete)
- Form minimal implementation required for new platforms
-
Compound Operations (~80% of the system):
- Built entirely from atomic operations
- Zero platform-specific code
- Implement higher-level domain concepts
- Work on any platform without modification
┌─────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Key files for the compound tool architecture:
- compounded.ts: Compound modeling tools
- compounded.ts: Compound animation tools
- compounded.ts: Compound rigging tools
The system automatically generates platform-specific implementations from TypeScript definitions:
┌──���──────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
│ Entity Schemas │ │ Schema │ │ Platform-Specific Code │
│ & Tools (TS) │ ──> │ Extraction (TS) │ ──> │ (Python/C++/etc.) │
└─────────────────┘ └────────────────────┘ └─────────────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
│ Type │ │ Parameter │ │ Implementation │
│ Definitions │ │ Validation │ │ Templates │
└─────────────────┘ └────────────────────┘ └───���─────────────────────┘
Key aspects of the generation system:
- Entity Extraction: Analyzes Zod schemas to understand entity structure
- Parameter Mapping: Converts TypeScript types to platform-native types
- Validation Generation: Creates parameter validation in target languages
- Implementation Templates: Provides platform-specific code patterns
The codegen system is implemented in:
- plugin-codegen.ts: Main code generation script
- extract-schemas.ts: Extracts Zod schemas from TypeScript files into temporary JSON files.
The system is organized into domains that mirror 3D content creation workflows:
- Core: Base entities and operations used across all domains
- Modeling: Mesh creation, editing, and topology operations
- Animation: Keyframes, curves, clips, and animation control
- Rigging: Skeletal systems, controls, and deformation
- Rendering: Materials, lights, and render settings
Each domain follows the same organizational pattern:
entity.ts: Domain-specific entity definitionsatomic.ts: Atomic operations for domain entitiescompounded.ts: Higher-level operations built from atomic tools
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
└── ...
The system implements a sophisticated entity-centric approach where:
-
Entities as Domain Models: Each domain (modeling, animation, rigging) defines its core entities that represent its fundamental concepts. These are implemented as Zod schemas with rich type information.
-
CRUD as Foundation: Every entity automatically receives a complete set of CRUD operations (Create, Read, Update, Delete) through the
createCrudOperationsutility:
// 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
}-
Entity Reuse and Inheritance: Core entities defined in
core/entity.tsare extended by domain-specific entities, promoting code reuse and consistent design across domains. -
DDD-Inspired Architecture: The system follows Domain-Driven Design principles by organizing code around domain entities and aggregates rather than technical concerns.
This architecture provides several key benefits:
- Consistency: All entities have the same patterns for basic operations
- Reduced Boilerplate: CRUD operations are generated automatically
- Clear Organization: Tools are organized around domain entities
- Separation of Concerns: Each domain manages its own entities while sharing common patterns
The combination of rich entity models with automatic CRUD operations creates a robust foundation that simplifies development while maintaining flexibility for domain-specific operations.
# Install dependencies
bun install
# Run the server
bun run index.ts
# Extract schemas and generate plugins
bun run packages/scripts/plugin-codegen.ts- Define Entities: Create or extend entity schemas in
src/tool/<domain>/entity.ts - Generate CRUD: Use
createCrudOperationsto generate atomic operations - Create Compound Tools: Build higher-level operations from atomic tools
- Generate Plugins: Run the code generator to create platform-specific implementations
The architectural decisions in 3D-MCP make it uniquely extensible:
- Add New Entities: Define new entities and automatically get CRUD operations
- Add New Compound Tools: Combine existing atomic operations to create new functionality
- Add New Platforms: Implement the atomic tool interfaces in a new plugin
See our contributing guide for more details on how to contribute.
3D-MCP: One API to rule all 3D software
3D Model Context Protocol
Обзор
3D-MCP — это универсальная реализация Model Context Protocol для трёхмерных редакторов. Она предоставляет единый TypeScript-интерфейс, через который большие языковые модели (LLM) могут управлять Blender, Maya, Unreal Engine и другими 3D-приложениями, используя один и тот же API.
// LLM использует одинаковый интерфейс независимо от программы
await tools.animation.createKeyframe({
objectId: "cube_1",
property: "rotation.x",
time: 30,
value: Math.PI / 2
});
Архитектура
3D-MCP построен на четырёх взаимосвязанных принципах:
- Entity-First Design — чётко определённые сущности (меши, материалы, анимации) лежат в основе всех операций.
- Type-Safe CRUD — автоматическая генерация create/read/update/delete с полной проверкой типов.
- Atomic Operations — минимальный набор платформозависимых реализаций (около 20% кода).
- Composable Tools — сложные функции собираются из атомарных операций и работают на всех платформах без изменений (около 80% кода).
Entity-Centric CRUD
Сущности описываются с помощью Zod-схем, которые служат единственным источником истины для валидации, типов и документации. Из схем автоматически генерируются CRUD-операции:
export const Mesh = NodeBase.extend({
vertices: z.array(Tensor.VEC3).describe("Массив позиций вершин [x, y, z]"),
normals: z.array(Tensor.VEC3).optional().describe("Массив нормалей"),
});
const entityCruds = createCrudOperations(ModelEntities);
// => createMeshs, getMeshs, updateMeshs, deleteMeshs, listMeshs
Все операции сохраняют полную типовую информацию: IDE подсказывает обязательные и опциональные поля, а компилятор ловит ошибки на этапе сборки.
Атомарные и составные операции
- Атомарные операции напрямую обращаются к API конкретной 3D-программы (например,
createKeyframesдля Blender, Maya, Unreal). Их реализация специфична для каждой платформы. - Составные операции строятся из атомарных и не содержат платформозависимого кода. Например, создание IK-рига:
execute: async (params) => {
const ikChainResult = await tool.createIKChains.execute({...});
const ikControlResult = await tool.createRigControls.execute({
name: `${switchName}_IK_CTRL`,
shape: ikControlShape,
targetJointIds: [jointIds.last],
color: ikColor,
});
// ... создание констрейнтов
return { success: true, ikControlId: ikControlResult.id };
}
Генерация кода
Система автоматически создаёт реализации для новых платформ (Python, C++ и др.) на основе TypeScript-схем:
- Извлечение структуры из Zod-схем.
- Преобразование типов TypeScript в нативные типы платформы.
- Генерация шаблонов валидации и реализации.
Основные скрипты:
plugin-codegen.ts— главный генераторextract-schemas.ts— извлечение схем во временные JSON
Домены
Код организован по доменам, соответствующим рабочим процессам 3D-контента:
- core — базовые сущности и утилиты
- model — создание и редактирование мешей
- animation — ключевые кадры, кривые, клипы
- rig — скелеты, контроллеры, деформации
- rendering — материалы, источники света, настройки рендера
Каждый домен содержит три файла:
entity.ts— сущностиatomic.ts— атомарные операцииcompounded.ts— составные инструменты
Заключение
3D-MCP позволяет языковым моделям взаимодействовать с любым 3D-редактором через единый интерфейс. Благодаря разделению на атомарные и составные операции, добавление новой платформы требует реализации лишь 20% кода, а 80% работают «из коробки».
Что такое 3D Model Context Protocol (3D MCP)?
3D MCP — это универсальная реализация Model Context Protocol, предоставляющая единый TypeScript-интерфейс для больших языковых моделей (LLM) с целью взаимодействия с различными 3D-приложениями, такими как Blender, Maya и Unreal Engine.
Какие 3D-приложения поддерживает 3D MCP в настоящее время?
В настоящее время 3D MCP поддерживает Blender, Maya и Unreal Engine. Архитектура спроектирована таким образом, чтобы легко расширяться на другие 3D-приложения путем реализации платформенно-специфичных адаптеров для атомарных операций.
Могу ли я внести свой вклад в разработку 3D MCP?
Да, 3D MCP — это проект с открытым исходным кодом, и мы приветствуем вклад. Более подробную информацию о том, как внести свой вклад, можно найти в репозитории GitHub проекта.
Каковы ключевые преимущества использования 3D MCP?
3D MCP позволяет LLM управлять 3D-программным обеспечением с помощью единого согласованного API, упрощает создание 3D-контента за счет автоматизированных CRUD-операций и проверки типов, а также способствует разработке платформенно-независимых инструментов путем разделения атомарных и составных операций.
Как 3D MCP обеспечивает согласованность данных на разных 3D-платформах?
3D MCP использует подход, ориентированный на сущности, с четко определенными доменными сущностями и схемами Zod для обеспечения согласованного моделирования данных на разных 3D-платформах. Эта строгая типизация позволяет выявлять ошибки на этапе компиляции и предоставляет богатые метаданные для понимания ИИ.
Delete
Deletes the current selection. Additional optional type can be provided to filter the deletion
Parameters
1Set Parent Objects
Set parent for multiple objects
Parameters
2Get Children
Get all children of an object
Parameters
3Create Light
Create a light source (object) in the scene
Parameters
7Create Geometry
Creates a new geometry object. Starting point for every geometry creation. The geometry is built using a node graph. The node graph output is already added in the node graph, and its id is...
Parameters
1Start Edit Geometry
Starts editing the geometry of an object.
Parameters
1End Edit Geometry
Ends the current editing of the geometry of an object.
Add Node Mesh Cube
Adds a new mesh cube node to the current edited geometry.
Parameters
4SizearrayVertices_XintegerVertices_YintegerVertices_ZintegerAdd Node Mesh Cylinder
Adds a new mesh cylinder node to the current edited geometry.
Parameters
5DepthnumberRadiusnumberVerticesintegerFill_SegmentsintegerSide_SegmentsintegerAdd Node Mesh Uvsphere
Adds a new mesh sphere node to the current edited geometry.
Parameters
3RingsintegerRadiusnumberSegmentsintegerAdd Node Mesh Cone
Adds a new mesh cone node to the current edited geometry.
Parameters
6DepthnumberVerticesintegerRadius_TopnumberFill_SegmentsintegerRadius_BottomnumberAdd Node Set Position
Adds a new set position node to the current edited geometry.
Add Node Position Input
Adds a new position input node to the current edited geometry.
Add Node Math
Adds a new math node to the current edited geometry.
Parameters
1Add Node Separate Xyz
Adds a new separate XYZ node to the current edited geometry.
Add Node Combine Xyz
Adds a new combine XYZ node to the current edited geometry.
Set Node Property By Index
Sets an input default value of a node. For the available inputs and their type, use 'getNodeInputsOutputs'. Note that vectors are written Vector(x, y, z)
Parameters
3Get Node Types
Returns all available node types that can be added to a geometry
Get Node Inputs Outputs
Retrieves all input and output socket names for a node, and checks if input sockets can accept a default_value.
Parameters
1Add Nodes Batch
Adds a batch of nodes to the current edited geometry. The nodes are added in the order they are provided. the node format is {"type": <node_type>, "inputs": {<input_name>: <value>, ...}}
Parameters
1Connect Nodes Batch
Connects a batch of nodes in the current edited geometry. The connections are made in the order they are provided.
Parameters
1Get Camera View
Get a customizable view of the 3D scene from any camera angle.
Parameters
4Get Scene Graph
Get the scene graph of the current scene.
Источник: https://mcpmarket.com/server/3d-model-context-protocol
Комментарии
Комментариев пока нет. Будьте первым.