3D MCP
概述
3D-MCP 是模型上下文协议 ( MLM) 针对 3D 软件的通用实现。它为 LLM 创建了统一的 TypeScript 接口，以便 LLM 通过单一一致的 API 与 Blender、Maya、Unreal Engine 和其他 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 模式为验证、输入和文档提供了单一真实来源
- 强类型在编译时而不是运行时捕获错误
- 丰富的元数据使人工智能能够更好地理解领域对象
**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 类型转换为平台原生类型
- 验证生成：以目标语言创建参数验证
- 实现模板：提供特定于平台的代码模式
代码生成系统实现如下：
4. 域组织
该系统分为几个反映 3D 内容创建工作流程的域：
- 核心：所有领域使用的基础实体和操作
- 建模：网格创建、编辑和拓扑操作
- 动画：关键帧、曲线、剪辑和动画控制
- 索具：骨骼系统、控制和变形
- 渲染：材质、灯光和渲染设置
每个域遵循相同的组织模式：
域结构图
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 作为基础：每个实体通过
createCrudOperations实用程序自动接收一整套 CRUD 操作（创建、读取、更新、删除）：
// 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 软件