3D МКП
Обзор
3D-MCP — это универсальная реализация Model Context Protocol для 3D-программного обеспечения. Она создает унифицированный интерфейс TypeScript для LLM, позволяющий им взаимодействовать с Blender, Maya, Unreal Engine и другими 3D-приложениями через единый согласованный 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 построен на четырех взаимосвязанных архитектурных принципах, которые вместе создают единую систему для создания 3D-контента:
- Проектирование Entity-First : четко определенные сущности предметной области формируют основу всех операций, обеспечивая единообразное моделирование данных на разных платформах.
- Типобезопасные CRUD-операции : автоматическая генерация операций создания, чтения, обновления, удаления с полной проверкой типов.
- Уровень атомарных операций : минимальный набор платформенно-специфичных реализаций, которые обрабатывают основные операции.
- Компонуемая архитектура инструментов : сложная функциональность, созданная путем объединения атомарных операций платформенно-независимым способом.
Такая архитектура создает инверсию зависимостей, при которой детали реализации, специфичные для платформы, изолируются до атомарных операций, в то время как большая часть кодовой базы остается независимой от платформы.
┌─────────────────────────────────────────────────────────────────────────┐
│ 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 был выбран по следующим причинам:
- 3D-приложения используют разные объектные модели, но общие основные концепции (сетки, материалы, анимация)
- Схемы Zod предоставляют единый источник истины для проверки, типизации и документирования.
- Строгая типизация выявляет ошибки во время компиляции, а не во время выполнения
- Богатые метаданные позволяют ИИ лучше понимать объекты домена
Операции CRUD как основа, потому что:
- Они четко соответствуют тому, что 3D-приложениям необходимо делать с сущностями.
- Стандартизированные шаблоны снижают когнитивные издержки
- Автоматическая генерация устраняет повторяющийся код с помощью
createCrudOperations - Каждая сущность автоматически получает одинаковый согласованный интерфейс.
Разделение атомарного и составного инструмента по следующим причинам:
- Только атомарные инструменты требуют реализации на конкретной платформе (~20% кодовой базы)
- Составные инструменты работают на всех платформах без изменений (~80% кодовой базы)
- Новым платформам необходимо реализовать только атомарные операции, чтобы получить всю функциональность
- Поддерживаемая архитектура с четким разделением задач
Техническая Архитектура
1. Архитектура CRUD, ориентированная на сущности
Основой системы является богатая система типов доменных сущностей, которая генерирует операции 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
});
Схемы сущностей обеспечивают:
- Проверка схемы : проверка параметров во время выполнения с подробными сообщениями об ошибках
- Информация о типе : Полные типы TypeScript для помощи IDE
- Документация : Самодокументируемый API с описаниями
- Генерация кода : шаблоны для платформенно-специфических реализаций
Схема архитектуры сущности
┌──────────────────────────────────────────────────────────────┐
│ 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. Архитектура составного инструмента
Система создает четкое разделение между атомарными и составными операциями:
// 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,
};
}
})
Такая архитектура обеспечивает ряд технических преимуществ:
- Атомарные операции (~20% системы):
- Напрямую взаимодействуйте с API платформы
- Нужны реализации для конкретных платформ
- Сосредоточьтесь на операциях с отдельными сущностями (создание, чтение, обновление, удаление)
- Форма минимальной реализации, необходимой для новых платформ
- Сложные операции (~80% системы):
- Построен полностью из атомных операций
- Никакого платформенно-специфического кода
- Реализовать концепции доменов более высокого уровня
- Работает на любой платформе без модификации
Поток композиции инструмента
┌─────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └──────────────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Ключевые файлы для архитектуры составного инструмента:
- composited.ts: Инструменты моделирования составных частей
- composited.ts: Инструменты для создания составной анимации
- composited.ts: Инструменты для комбинированного такелажа
3. Конвейер генерации кода
Система автоматически генерирует реализации для конкретных платформ из определений TypeScript:
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
│ Entity Schemas │ │ Schema │ │ Platform-Specific Code │
│ & Tools (TS) │ ──> │ Extraction (TS) │ ──> │ (Python/C++/etc.) │
└─────────────────┘ └────────────────────┘ └─────────────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────────────┐
│ Type │ │ Parameter │ │ Implementation │
│ Definitions │ │ Validation │ │ Templates │
└─────────────────┘ └────────────────────┘ └─────────────────────────┘
Ключевые аспекты системы генерации:
- Извлечение сущностей : анализирует схемы Zod для понимания структуры сущностей.
- Сопоставление параметров : преобразует типы TypeScript в собственные типы платформы.
- Генерация проверки : создает проверку параметров на целевых языках.
- Шаблоны реализации : предоставляют шаблоны кода, специфичные для платформы.
Система кодогенерации реализована в:
4. Организация домена
Система организована по доменам, которые отражают рабочие процессы создания 3D-контента:
- Ядро : базовые сущности и операции, используемые во всех доменах.
- Моделирование : создание сетки, редактирование и топологические операции
- Анимация : ключевые кадры, кривые, клипы и управление анимацией
- Оснастка : скелетные системы, элементы управления и деформации
- Рендеринг : материалы, освещение и настройки рендеринга
Каждый домен следует одной и той же организационной схеме:
entity.ts : Определения сущностей, специфичные для доменаatomic.ts : Атомарные операции для доменных сущностейcompounded.ts : высокоуровневые операции, созданные на основе атомарных инструментов
Диаграмма структуры домена
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. Архитектура CRUD, ориентированная на сущности
Система реализует сложный подход, ориентированный на сущности, где:
- Сущности как модели доменов : каждый домен (моделирование, анимация, оснастка) определяет свои основные сущности, которые представляют его фундаментальные концепции. Они реализованы как схемы Zod с богатой информацией о типах.
- CRUD как основа : каждая сущность автоматически получает полный набор операций CRUD (создание, чтение, обновление, удаление) через утилиту
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
}
- Повторное использование и наследование сущностей : основные сущности, определенные в
core/entity.ts расширяются сущностями, специфичными для домена, что способствует повторному использованию кода и единообразному проектированию во всех доменах. - Архитектура, вдохновленная DDD : система следует принципам проектирования на основе предметной области, организуя код вокруг сущностей и агрегатов предметной области, а не технических проблем.
Такая архитектура обеспечивает несколько ключевых преимуществ:
- Согласованность : все сущности имеют одинаковые шаблоны для основных операций.
- Сокращенный шаблон : операции CRUD генерируются автоматически
- Четкая организация : инструменты организованы вокруг доменных сущностей.
- Разделение задач : каждый домен управляет своими собственными сущностями, используя при этом общие шаблоны.
Сочетание расширенных моделей сущностей с автоматическими операциями CRUD создает надежную основу, которая упрощает разработку, сохраняя при этом гибкость для операций, специфичных для предметной области.
Начиная
# Install dependencies
bun install
# Run the server
bun run index.ts
# Extract schemas and generate plugins
bun run packages/scripts/plugin-codegen.ts
Рабочий процесс разработки
- Определение сущностей : создание или расширение схем сущностей в
src/tool/<domain>/entity.ts - Генерация CRUD : использование
createCrudOperations для генерации атомарных операций. - Создание составных инструментов : создание высокоуровневых операций из атомарных инструментов.
- Генерация плагинов : запуск генератора кода для создания реализаций для конкретных платформ.
Внося вклад
Архитектурные решения 3D-MCP делают его уникально расширяемым:
- Добавить новые сущности : определить новые сущности и автоматически получить операции CRUD
- Добавить новые составные инструменты : объединить существующие атомарные операции для создания новых функций.
- Добавить новые платформы : реализовать интерфейсы атомарных инструментов в новом плагине.
Более подробную информацию о том, как внести свой вклад, можно найти в нашем руководстве по внесению вклада.
3D-MCP: единый API для управления всем 3D-программным обеспечением