3D MCP

概述

3D-MCP是模型上下文协议 3D软件。它为LLM创建了一个统一的TypeScript接口，以便通过单个一致的API与Blender、Maya、虚幻引擎和其他3D应用程序进行交互。

// 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内容创建的统一系统：

实体优先设计：定义良好的域实体构成了所有操作的基础，实现了跨平台的一致数据建模
类型安全的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      │     │    
│  └─────────────────┘  └─────────────────┘  └──────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────┘

为什么要做出这些设计决策？

实体优先设计 之所以被选中，是因为：

3D应用程序使用不同的对象模型，但共享核心概念（网格、材质、动画）
Zod模式为验证、类型和文档提供了单一的真实来源
强类型在编译时而不是运行时捕获错误
丰富的元数据使AI能够更好地理解领域对象

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                │  │
│  └──────────────────────────┘  └─────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

复合工具架构的关键文件：

compounded.ts：复合建模工具
compounded.ts：复合动画工具
compounded.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：将TypeScript文件中的Zod模式提取到临时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//entity.ts
生成CRUD：使用 createCrudOperations 生成原子操作
创建复合工具：从原子工具构建更高级别的操作
生成插件：运行代码生成器以创建特定于平台的实现

贡献

3D-MCP中的架构决策使其具有独特的可扩展性：

添加新实体：定义新实体并自动获取CRUD操作
添加新的复合工具：合并现有的原子操作以创建新功能
添加新平台：在新插件中实现原子工具接口

有关如何贡献的更多详细信息，请参阅我们的贡献指南。

______________________________________________________________________

*3D-MCP:一个API来管理所有3D软件*

3 D

快速接入

详细介绍