MCP-basierter intelligenter 3D-Modellierungs-Agent

Blender mit einem KI-Agenten steuern – 218 MCP-Tools decken die komplette 3D-Pipeline ab, plus eine intelligente LangGraph-Agent-Schicht: Planen→Ausführen→Beobachten→Bewerten→Neuplanen als geschlossener Kreislauf, versionierte Prompts, Schema-gesteuerte Tool-Auswahl und ein reproduzierbares Benchmark.

🌏 English: README.en.md

Was dieses Projekt zeigt · Architektur · Benchmark-Ergebnisse · Schnellstart · Dokumentation

Überblick

Dieses Repository besteht aus zwei Ebenen:

1. MCP-Basisebene (basierend auf dem Upstream-Projekt RFingAdam/mcp-blender, eng-mcp-suite) —— Ein MCP-Server, der 218 Blender-Tools (Modellierung, Materialien, Modifier, Animation, Rendering, Sculpting, Geometry Nodes, Physik, KI-3D-Generierung, MSFS-Content-Pipeline) für beliebige MCP-Clients bereitstellt.

2. Intelligente Agent-Ebene (agent/-Verzeichnis, originäre Arbeit dieses Repositories) —— Ein auf LangGraph basierender 3D-Agent: plant Aufgaben, führt sie über MCP-Tools aus, erfasst Szenenfakten, verifiziert Akzeptanzkriterien einzeln (mit Nachweispflicht), repariert minimal – mit versionierten Prompts, strukturierten Ausgabekontrakten, Evaluations-Logs und einem 16-Aufgaben-Benchmark.

Was dieses Projekt zeigt

Vollständige Engineering-Praxis – um LLM-Agenten zuverlässig, messbar und ingenieurstechnisch beherrschbar zu machen.

Architektur

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

Die Agent-Ebene ist der vierte Prozess – sie läuft selbst als MCP-Client eines bestehenden MCP-Servers und implementiert nie Blender-Tools neu:

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

Agent-Schleife

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

Zuverlässigkeit wird durch Code erzwungen statt durch Prompt-Disziplin: Schema-Validierung + ein Tool-Selection-Repair-Wiederholungsversuch, Pflichtabdeckung der Kriterien, jede Parsing-Fehlschläge werden explizit degradiert (im State protokolliert, dem Reviewer ausgesetzt – niemals stillschweigend).

Live-Demonstration

Benchmark-Ergebnisse

Getestet auf echten Blender-4.x-Instanzen – der Agent führte alle 16 Aufgaben aus benchmarks/tasks.json aus (4 Schwierigkeitsgrade, von grundlegender Erstellung bis kombinierter Modellierung), jede Aufgabe mit evidenzbasierter Abnahme.

Alle kombinierten Modellierungsaufgaben der Stufen L3–L4 (Tisch, Haus, Schneemann, boolesches Lochen, Kiefer, Stuhl, Teetasse, Roboter) bestanden die geometrische Beweisabnahme – z. B. sind die 1012 Vertices des Roboters exakt gleich der Summe der Vertices von 6 Würfeln + 2 Kugeln.

Methodik-Hinweis: Ausgeführt von Claude als Agent über den JSON-RPC-Kanal des Addons (d. h. dieselbe Transportschicht, die der MCP-Server verwendet) gegen echtes Blender; aufgabenspezifische Protokolle finden sich in eval_runs/ und docs/PHASE2_PROMPT_ENGINEERING.md. Das Benchmark deckte außerdem einen echten Addon-Defekt auf (scene_clear kann versteckte Objekte nicht löschen → Namenskonflikte bei doppelten Objekten), der im Dokumentations-Befund protokolliert wurde – genau dafür existiert das Evaluationssystem.

Schnellstart

1. Installation

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 starten

1. Plugin installieren: Blender → Bearbeiten → Einstellungen → Add-ons → Installieren… → addon/blender_mcp_addon auswählen (kann mit python scripts/package_addon.py als ZIP gepackt oder direkt als Verzeichnis verlinkt werden).

2. „MCP Server Addon" aktivieren.

3. Im 3D-Viewport N drücken → MCP Server-Panel → Start Server (Standardport 9876).

3. Als MCP-Tool-Anbieter verwenden (beliebiger MCP-Client)

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

Dann einfach zum Client sagen: „Erstelle einen roten Würfel bei (2, 0, 0) und füge einen Subdivision-Surface-Modifier mit Stufe 2 hinzu."

4. LangGraph-Agent ausführen

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

Parameter: --render (Beobachtungs-Rendering aktivieren), --max-iterations, --prompt-version, --no-eval, -v. Metriken werden gespeichert: eval_runs/eval_runs.jsonl + eval_runs/records/.

5. Benchmark ausführen

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

Repository-Struktur

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 设计文档

Tests

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

Enthält End-to-End-Graphtests mit Fake-LLM: vollständiger Konvergenzkreislauf, Tool-Selection-Repair-Wiederherstellungspfad, explizite Behandlung von Reviewer-Parsing-Fehlern.

Dokumentation

• docs/tools.md — Vollständige Referenz der 218 MCP-Tools

• docs/usage.md — End-to-End-Nutzungsbeispiele

• docs/architecture.md — MCP/Server/Addon-Architektur

• docs/AGENT_ARCHITECTURE.md — Agent-Ebenen-Design (Phase 1, Chinesisch)

• docs/PHASE2_PROMPT_ENGINEERING.md — Prompt-System, Schema, Evaluations- und Benchmark-Methodik, Testergebnisse, Befundprotokoll (Chinesisch)

• docs/MSFS_ROADMAP.md — MSFS-Content-Pipeline

Roadmap

• Phase 3 — Tool-RAG: Kandidaten-Tools pro Aufgabe abrufen, als Ersatz für die aktuelle Injektion des vollständigen 218-Tool-Verzeichnisses; die aktuellen Metriken dienen als Vergleichsbasis.

• Phase 4 — Visuelle Bewertung und Gedächtnis: Multimodaler Reviewer basierend auf dem bestehenden analyze_viewport-Tool; sitzungsübergreifendes Gedächtnis.

• Den Agenten selbst erneut als MCP-Server verpacken (ein einzelnes run_3d_task-Tool nach außen exponieren), damit übergeordnete Clients ihn aufrufen können.

Lizenz und Danksagungen

• Dieses Repository: AGPL-3.0-or-later.

• Upstream-Basis: RFingAdam/mcp-blender (gehört zu eng-mcp-suite) – MCP-Server, Blender-Plugin und die 218 Tools stammen aus dem Upstream-Projekt; die intelligente Agent-Ebene (agent/), das Evaluationssystem, das Benchmark und die Agent-Dokumentation sind originäre Beiträge dieses Forks.

• Blender selbst bleibt unter GPL-Lizenz, wird nur zur Laufzeit aufgerufen und nicht mit diesem Repository verteilt.

LangGraph · MCP · Prompt-Engineering · Evaluationssystem.