MCP ベースのインテリジェント 3D モデリング Agent

AI Agent で Blender を操作——218 個の MCP ツールが 3D パイプライン全体をカバー。さらに LangGraph Agent インテリジェンス層を追加：計画→実行→観察→レビュー→再計画のクローズドループ、バージョン管理された Prompt、Schema ゲート付きツール選択、そして再現可能な Benchmark。

🌏 English: README.en.md

このプロジェクトが示すもの · アーキテクチャ · Benchmark 結果 · クイックスタート · ドキュメント

概要

本リポジトリは 2 つの層で構成されています：

1. MCP 基盤層 （上流の RFingAdam/mcp-blender に基づく、eng-mcp-suite） —— 任意の MCP クライアントに 218 個の Blender ツール（モデリング、マテリアル、モディファイア、アニメーション、レンダリング、スカルプト、ジオメトリノード、物理、AI 3D 生成、MSFS コンテンツパイプライン）を公開する MCP server。

2. Agent インテリジェンス層 （agent/ ディレクトリ、本フォークのオリジナル成果） —— LangGraph ベースの 3D Agent：タスクを計画し、MCP ツールで実行し、シーン事実を収集し、受け入れ基準を 1 件ずつ検証（証拠が必須）、最小限の修正で対応——Prompt のバージョン管理、構造化出力契約、評価ログ、16 タスクの Benchmark を完備。

このプロジェクトが示すもの

LLM Agent を信頼性・測定可能性・エンジニアリング可能性の高いものにするための、完全なエンジニアリング実践です。

アーキテクチャ

┌───────────────┐   MCP stdio    ┌────────────────┐   TCP JSON-RPC   ┌──────────────────┐
│  MCP client   │ ◄────────────► │  MCP server    │ ◄──────────────► │  Blender addon   │
│ (Claude Code) │                │  (Python 进程)  │   localhost:9876 │  (bpy.app.timers)│
└───────────────┘                └────────────────┘                  └──────────────────┘

Agent 層は 4 つ目のプロセスであり、既存の MCP server の MCP クライアントとして動作します——Blender ツールを再実装することは一切ありません：

用户 / LLM 客户端
  │
  ▼
★ LangGraph Agent（agent/）          ← 本项目的智能层
  │   MCP 客户端（stdio）—— 复用全部 218 个工具
  ▼
mcp-blender MCP server（上游，零修改）
  │
  ▼
Blender addon → bpy → Blender 场景

Agent ループ

START → Planner → Executor → Observer → Reviewer → Router ── 通过 ──► END
                                                       └─ 重规划 ──► RePlanner → Executor（循环）

信頼性は Prompt の自己申告ではなくコードで強制されます：schema 検証 + 1 回の Tool Selection Repair リトライ、criteria カバレッジ強制、解析失敗はすべて明示的にフォールバック（state に記録、Reviewer に公開——決して黙って無視しない）。

実測デモ

Benchmark 結果

実 Blender 4.x インスタンスで実測——Agent は benchmarks/tasks.json の全 16 タスク（4 つの難易度レベル、基本作成から複合モデリングまで）を実行し、各タスクで証拠ベースの受け入れ検証を実施。

L3–L4 レベルの複合モデリングタスク（テーブル、家、雪だるま、ブーリアン穴あけ、松の木、椅子、ティーカップ、ロボット）はすべて幾何学的証拠で受け入れ検証を通過——例えばロボットの 1012 頂点は 6 つの立方体 + 2 つの球体の頂点の合計と正確に一致。

方法論の注記：Claude が Agent として addon の JSON-RPC チャネル（MCP server が使用するのと同じトランスポート層）経由で実 Blender を実行；タスクごとの記録は eval_runs/ と docs/PHASE2_PROMPT_ENGINEERING.md を参照。Benchmark は実在する addon の欠陥（scene_clear が非表示オブジェクトをクリアできない → 同名オブジェクトの競合）も発見し、ドキュメントの検出記録に記載——これこそ評価システムが存在する意義です。

クイックスタート

1. インストール

git clone https://github.com/SekaiNoOwari77/mcp-3d-modeling-agent.git
cd mcp-3d-modeling-agent
pip install -e .                       # MCP server（基础层）
pip install -r agent/requirements.txt  # Agent 层（langgraph、mcp、httpx、jsonschema）

2. Blender の起動

1. アドオンをインストール：Blender → 編集 → プリファレンス → アドオン → インストール… → addon/blender_mcp_addon を選択（python scripts/package_addon.py で ZIP にパッケージ化するか、ディレクトリを直接シンボリックリンク可能）。

2. "MCP Server Addon" を有効化。

3. 3D ビューポートで N キー → MCP Server パネル → Start Server（デフォルトポート 9876）。

3. MCP ツールプロバイダーとして使用（任意の MCP クライアント）

{
  "mcpServers": {
    "blender": { "command": "mcp-blender", "args": ["--port", "9876"] }
  }
}

その後、クライアントに直接こう指示します："(2, 0, 0) に赤い立方体を作成し、レベル 2 の Subdivision Surface モディファイアを追加して。"

4. LangGraph Agent の実行

AGENT_LLM_MODEL=deepseek-chat \
AGENT_LLM_BASE_URL=https://api.deepseek.com/v1 \
AGENT_LLM_API_KEY=sk-... \
python -m agent.run "做一个低多边形松树：圆柱树干加三层圆锥树叶"

パラメータ：--render（観察レンダリングを有効化）、--max-iterations、--prompt-version、--no-eval、-v。 指標の保存先：eval_runs/eval_runs.jsonl + eval_runs/records/。

5. Benchmark の実行

python -m benchmarks.runner                   # 全部 16 个任务
python -m benchmarks.runner --levels 1,2      # 按难度级别
python -m benchmarks.runner --tags regression # Phase-1 回归任务

リポジトリ構造

src/mcp_blender/            MCP server：218 个工具定义 + Blender TCP 客户端      （上游）
addon/blender_mcp_addon/    Blender 插件：socket 服务器、handlers、AI 后端       （上游）
agent/                      ★ Agent 智能层（原创）
├── graph.py                LangGraph 组装（6 节点 + plan 级循环）
├── state.py                Plan / PlanStep / Criterion / ReviewVerdict 数据结构
├── config.py               env 驱动的配置
├── execution.py            任务执行入口（CLI 与 benchmark 共用）
├── llm.py                  OpenAI 兼容 LLM 客户端，带 token 用量追踪
├── nodes/                  planner / executor / observer / reviewer / replanner / router
├── prompts/                版本化 Prompt 模板（planner/v1.md 等）
├── context/                每节点上下文构建器
├── evaluation/             EvalLogger：11 项指标，JSON + JSONL 记录
└── tools/mcp_client.py     MCP 客户端：子进程生命周期、目录缓存、串行调用
benchmarks/                 16 任务 benchmark 套件 + runner + 传输 shim
tests/                      基础层测试 + tests/agent/（单元 + 假 LLM 端到端循环）
docs/                       工具参考、使用示例、架构、Agent 设计文档

テスト

pytest tests/agent -q                    # Agent 层：44 个测试
PYTHONPATH=src pytest tests/ --ignore=tests/blender_integration_test.py  # 基础层：84 个测试

フェイク LLM によるエンドツーエンドグラフテストを含む：完全な収束ループ、Tool Selection Repair の復旧パス、Reviewer の解析失敗の明示的処理。

ドキュメント

• docs/tools.md — 218 個の MCP ツールの完全リファレンス

• docs/usage.md — エンドツーエンドの使用例

• docs/architecture.md — MCP/server/addon アーキテクチャ

• docs/AGENT_ARCHITECTURE.md — Agent 層の設計（Phase 1、中国語）

• docs/PHASE2_PROMPT_ENGINEERING.md — Prompt 体系、Schema、評価と Benchmark の方法論、実測結果、検出記録（中国語）

• docs/MSFS_ROADMAP.md — MSFS コンテンツパイプライン

Roadmap

• Phase 3 — Tool RAG：タスクに応じて候補ツールを検索し、現在の全 218 ツールカタログ注入方式を置き換え；現在の指標がその比較ベースラインとなる。

• Phase 4 — ビジュアルレビューとメモリ：既存の analyze_viewport ツールに基づくマルチモーダル Reviewer；セッションをまたぐメモリ。

• Agent 自体を MCP server として再ラップ（外部に run_3d_task 単一ツールを公開）、上位クライアントから呼び出し可能にする。

ライセンスと謝辞

• 本リポジトリ：AGPL-3.0-or-later。

• 上流基盤：RFingAdam/mcp-blender（eng-mcp-suite 所属）——MCP server、Blender アドオン、218 個のツールは上流プロジェクト由来；Agent インテリジェンス層（agent/）、評価システム、Benchmark、Agent ドキュメントは本フォークのオリジナル貢献。

• Blender 本体は引き続き GPL ライセンスであり、実行時に呼び出されるのみで、本リポジトリでは配布されません。

LangGraph · MCP · Prompt エンジニアリング · 評価体系。