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软件*