3D MCP
개요
3D-MCP는 3D 소프트웨어용 모델 컨텍스트 프로토콜(Model Context Protocol) 의 범용 구현입니다. LLM이 단일 API를 통해 Blender, Maya, Unreal Engine 및 기타 3D 애플리케이션과 상호 작용할 수 있도록 통합된 TypeScript 인터페이스를 제공합니다.
지엑스피1
핵심 철학 및 디자인 결정
3D-MCP는 3D 콘텐츠 제작을 위한 통합 시스템을 함께 구축하는 4가지 상호 연결된 아키텍처 원칙을 기반으로 합니다.
- 엔터티 우선 설계 : 명확하게 정의된 도메인 엔터티는 모든 작업의 기반을 형성하여 플랫폼 전반에 걸쳐 일관된 데이터 모델링을 가능하게 합니다.
- 유형 안전 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 │ │
│ └─────────────────┘ └─────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
왜 이러한 디자인 결정을 했을까?
Entity-First Design 이 선택된 이유는 다음과 같습니다.
- 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
});
엔터티 스키마는 다음을 제공합니다.
- 스키마 검증 : 자세한 오류 메시지를 포함한 런타임 매개변수 검사
- 유형 정보 : IDE 지원을 위한 완전한 TypeScript 유형
- 문서 : 설명이 포함된 자체 문서화 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: 모든 3D 소프트웨어를 제어하는 하나의 API