Интеллектуальный 3D-моделирующий агент на основе MCP

Управление Blender с помощью AI-агента — 218 MCP-инструментов покрывают полный 3D-конвейер, плюс интеллектуальный слой на LangGraph: замкнутый цикл планирование→выполнение→наблюдение→рецензирование→перепланирование, версионируемые промпты, выбор инструментов с проверкой по схеме и воспроизводимый Benchmark.

🌏 English: README.en.md

Что демонстрирует этот проект · Архитектура · Результаты Benchmark · Быстрый старт · Документация

Обзор

Репозиторий состоит из двух уровней:

1. Базовый MCP-уровень (на основе вышестоящего RFingAdam/mcp-blender, eng-mcp-suite) — MCP-сервер, который предоставляет 218 инструментов Blender (моделирование, материалы, модификаторы, анимация, рендеринг, скульптинг, геометрические ноды, физика, AI-генерация 3D, конвейер контента MSFS) любому MCP-клиенту.

2. Интеллектуальный уровень агента (agent/ каталог, оригинальная работа этого репозитория) — 3D-агент на LangGraph: планирует задачи, выполняет через MCP-инструменты, собирает факты о сцене, проверяет критерии приёмки по одному (с обязательным предоставлением доказательств), минимальные исправления — в комплекте с версионированием промптов, контрактами структурированного вывода, журналами оценки и Benchmark на 16 задач.

Что демонстрирует этот проект

Полная инженерная практика — делает LLM-агентов надёжными, измеримыми и инженеризуемыми.

Архитектура

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

Уровень агента — это четвёртый процесс, который сам работает как MCP-клиент существующего MCP-сервера — никогда не перереализует ни один инструмент Blender:

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

Цикл агента

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

Надёжность обеспечивается кодом, а не полаганием на добросовестность промптов: проверка схемы + одна повторная попытка Tool Selection Repair, принудительное покрытие критериев, любая ошибка парсинга явно деградирует (записывается в состояние, предоставляется Reviewer — никогда не молча).

Демонстрация в реальном времени

Результаты Benchmark

Протестировано на реальном экземпляре Blender 4.x — агент выполнил все 16 задач из benchmarks/tasks.json (4 уровня сложности, от базового создания до комбинированного моделирования), каждая задача — с приёмкой на основе доказательств.

Все задачи комбинированного моделирования уровня L3–L4 (стол, дом, снеговик, булево отверстие, сосна, стул, чашка, робот) прошли приёмку по геометрическим доказательствам — например, 1012 вершин робота точно равны сумме вершин 6 кубов + 2 сфер.

Методологическое примечание: Claude в качестве агента выполнял через JSON-RPC-канал аддона (то есть тот же транспортный уровень, который использует MCP-сервер) на реальном Blender; пошаговые записи см. в eval_runs/ и docs/PHASE2_PROMPT_ENGINEERING.md. Benchmark также выявил реальный дефект аддона (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 (можно упаковать в ZIP с помощью python scripts/package_addon.py или просто создать симлинк на каталог).

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), добавь модификатор Subdivision Surface уровня 2.»

4. Запуск LangGraph-агента

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/сервер/аддон

• docs/AGENT_ARCHITECTURE.md — дизайн уровня агента (Фаза 1, на русском)

• docs/PHASE2_PROMPT_ENGINEERING.md — система промптов, схемы, методология оценки и Benchmark, реальные результаты, записи об обнаружениях (на русском)

• docs/MSFS_ROADMAP.md — конвейер контента MSFS

Дорожная карта

• Фаза 3 — Tool RAG: поиск кандидатов инструментов по задаче вместо текущей инъекции полного каталога из 218 инструментов; текущие метрики — это базовая линия для сравнения.

• Фаза 4 — визуальное рецензирование и память: мультимодальный Reviewer на основе существующего инструмента analyze_viewport; память между сессиями.

• Повторная упаковка самого агента как MCP-сервера (предоставление единого инструмента run_3d_task наружу) для вызова более высокоуровневыми клиентами.

Лицензия и благодарности

• Этот репозиторий: AGPL-3.0-or-later.

• Вышестоящая основа: RFingAdam/mcp-blender (входит в eng-mcp-suite) — MCP-сервер, плагин Blender и 218 инструментов взяты из вышестоящего проекта; интеллектуальный уровень агента (agent/), система оценки, Benchmark и документация агента — оригинальный вклад этого форка.

• Сам Blender остаётся под лицензией GPL, вызывается только во время выполнения и не распространяется с этим репозиторием.

LangGraph · MCP · Инженерия промптов · Система оценки.