3D MCP

플러그인 테스트 타입스크립트

개요

3D-MCP는 3D 소프트웨어용 모델 컨텍스트 프로토콜(Model Context Protocol) 의 범용 구현입니다. LLM이 단일 API를 통해 Blender, Maya, Unreal Engine 및 기타 3D 애플리케이션과 상호 작용할 수 있도록 통합된 TypeScript 인터페이스를 제공합니다.

지엑스피1

Related MCP server: MCP Base

핵심 철학 및 디자인 결정

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 유형을 플랫폼 기본 유형으로 변환합니다.
유효성 검사 생성 : 대상 언어에서 매개변수 유효성 검사를 생성합니다.
구현 템플릿 : 플랫폼별 코드 패턴을 제공합니다.

코드 생성 시스템은 다음에서 구현됩니다.

plugin-codegen.ts : 메인 코드 생성 스크립트
extract-schemas.ts : TypeScript 파일에서 Zod 스키마를 추출하여 임시 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: 모든 3D 소프트웨어를 제어하는 하나의 API

3D-MCP