3D MCP
概要
3D-MCPは、3Dソフトウェア向けのモデルコンテキストプロトコル（Model Context Protocol）のユニバーサル実装です。LLMがBlender、Maya、Unreal Engine、その他の3Dアプリケーションと単一の一貫性のあるAPIを介して連携するための、統一されたTypeScriptインターフェースを作成します。
// 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 は、相互に関連する 4 つのアーキテクチャ原則に基づいて構築されており、これらが組み合わさって 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スキーマは検証、型付け、ドキュメント化のための唯一の真実のソースを提供します
- 強い型付けは実行時ではなくコンパイル時にエラーをキャッチします
- 豊富なメタデータにより、ドメインオブジェクトの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ソフトウェアを制御する1つのAPI