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
});

Related MCP server: MCP Base

Основная философия и проектные решения

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 в собственные типы платформы.
Генерация проверки : создает проверку параметров на целевых языках.
Шаблоны реализации : предоставляют шаблоны кода, специфичные для платформы.

Система кодогенерации реализована в:

plugin-codegen.ts : Основной скрипт генерации кода
extract-schemas.ts : извлекает схемы Zod из файлов TypeScript во временные файлы JSON.

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-программным обеспечением

3D-MCP