3D-MCP模型上下文协议

@team-plask/3d-mcp
1 Stars 542 次浏览 team-plask 更新于 2026-08-23

一种通用的模型上下文协议实现，作为LLM和3D创意软件之间的语义层，通过统一的API为各种数字内容创作工具提供标准化的交互接口。

开发者工具娱乐与多媒体
该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

3D MCP

Plugin Tests TypeScript License

概述

3D-MCP 是为 3D 软件实现的 Model Context Protocol 的通用版本。它通过单一的一致 API，创建了一个统一的 TypeScript 接口，使 LLMs 可以与 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 内容创建系统：

  1. 实体优先设计：定义良好的领域实体构成了所有操作的基础，使得跨平台的数据建模保持一致。
  2. 类型安全的 CRUD 操作：自动生成具有完整类型验证的创建、读取、更新和删除操作。
  3. 原子操作层：一组最小化的特定于平台的实现来处理基本操作。
  4. 可组合工具架构：通过以平台无关的方式结合原子操作来构建复杂功能。

这种架构创造了一种依赖倒置，其中特定于平台的实现细节被隔离到原子操作中，而代码库的大部分内容则保持平台独立性。

┌─────────────────────────────────────────────────────────────────────────┐
│                             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,
    };
  }
})

这种架构提供了几个技术优势：

  1. 原子操作（约占系统的20%）：

    • 直接与平台API交互
    • 需要特定于平台的实现
    • 专注于单个实体操作（创建、读取、更新、删除）
    • 形成新平台所需的最小实现

  2. 复合操作（约占系统的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架构

系统实现了一种复杂的以实体为中心的方法，其中：

  1. 实体作为领域模型：每个领域（建模、动画、绑定）定义其核心实体，代表其基本概念。这些实体通过带有丰富类型信息的Zod模式实现。

  2. 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
}

  1. 实体复用与继承：在 core/entity.ts 中定义的核心实体被领域特定的实体扩展，促进了代码复用和跨领域的设计一致性。

  2. 受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

开发工作流

  1. 定义实体：在 src/tool/<domain>/entity.ts 中创建或扩展实体模式
  2. 生成CRUD：使用 createCrudOperations 生成原子操作
  3. 创建复合工具：从原子工具构建更高级别的操作
  4. 生成插件：运行代码生成器以创建特定于平台的实现

贡献

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

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

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

3D-MCP: 一个API掌控所有3D软件

查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。