3D MCP

插件测试 TypeScript

概述

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

Related MCP server: MCP Base

核心理念和设计决策

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 类型转换为平台原生类型
验证生成：以目标语言创建参数验证
实现模板：提供特定于平台的代码模式

代码生成系统实现如下：

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 作为基础：每个实体通过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 软件

3D-MCP