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

核心理念和设计决策

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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Tools

View all tools

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

Related Resources

Reddit Discussion about this server

Related MCP Servers

MCP Toolbox
ai-zerolab
-
security
A
license
-
quality
A comprehensive toolkit that enhances LLM capabilities through the Model Context Protocol, allowing LLMs to interact with external services including command-line operations, file management, Figma integration, and audio processing.
Last updated -
26
Apache 2.0
MCP Base
jsmiff
-
security
F
license
-
quality
A generic Model Context Protocol framework for building AI-powered applications that provides standardized ways to create MCP servers and clients for integrating LLMs with support for Ollama and Supabase.
Last updated -
Unity MCP Server
CoplayDev
-
security
A
license
-
quality
A bridge enabling seamless communication between Unity and Large Language Models via the Model Context Protocol, allowing developers to automate workflows, manipulate assets, and control the Unity Editor programmatically.
Last updated -
3,363
MIT License
Model Context Protocol (MCP) - UOR Implementationofficial
UOR-Foundation
-
security
F
license
-
quality
A GitHub-based implementation of the Model Context Protocol that enables LLMs to access and manipulate data in a Universal Object Reference (UOR) framework, providing standardized interfaces for object management with decentralized storage.
Last updated -

View all related MCP servers

3D-MCP

3D MCP

概述

核心理念和设计决策

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

技术架构

1.以实体为中心的 CRUD 架构

实体架构图

2. 复合工具架构

工具组合流程

3. 代码生成管道

4. 域组织

域结构图

5.以实体为中心的 CRUD 架构

入门

开发工作流程

贡献

Tools

Related Resources

Related MCP Servers

MCP Toolbox

MCP Base

Unity MCP Server

Model Context Protocol (MCP) - UOR Implementationofficial

Appeared in Searches

New MCP Servers

MCP directory API