Agente de modelado 3D inteligente basado en MCP

Controla Blender con un agente de IA: 218 herramientas MCP cubren todo el pipeline 3D, más una capa de agente inteligente LangGraph: planificar→ejecutar→observar→revisar→replanificar bucle cerrado, prompts versionados, selección de herramientas controlada por esquema y un benchmark reproducible.

🌏 English: README.en.md

Lo que demuestra este proyecto · Arquitectura · Resultados del benchmark · Inicio rápido · Documentación

Resumen

Este repositorio consta de dos capas:

1. Capa base MCP (basada en el upstream RFingAdam/mcp-blender, eng-mcp-suite) — un servidor MCP que expone 218 herramientas de Blender (modelado, materiales, modificadores, animación, renderizado, esculpido, nodos geométricos, física, generación 3D con IA, pipeline de contenido MSFS) a cualquier cliente MCP.

2. Capa de agente inteligente (directorio agent/, trabajo original de este repositorio) — un agente 3D basado en LangGraph: planifica tareas, ejecuta a través de herramientas MCP, recopila hechos de la escena, verifica los criterios de aceptación uno por uno (con evidencia obligatoria), repara de forma mínima — con prompts versionados, contratos de salida estructurados, registros de evaluación y un benchmark de 16 tareas.

Lo que demuestra este proyecto

Prácticas de ingeniería completas para hacer que los agentes LLM sean fiables, medibles y fáciles de ingeniar.

Arquitectura

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

La capa de agente es el cuarto proceso, que se ejecuta como un cliente MCP del servidor MCP existente — nunca reimplementa ninguna herramienta de Blender:

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

Bucle del agente

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

La fiabilidad se impone por código, no por la buena voluntad del prompt: validación de esquema + un reintento de reparación de selección de herramientas, cobertura de criterios obligatoria, y cualquier fallo de análisis se degrada explícitamente (se registra en el estado, se expone al revisor; nunca en silencio).

Demostración práctica

Resultados del benchmark

Probado en una instancia real de Blender 4.x: el agente ejecutó las 16 tareas de benchmarks/tasks.json (4 niveles de dificultad, desde creación básica hasta modelado combinado), con aceptación basada en evidencia para cada tarea.

Las tareas de modelado combinado de nivel L3-L4 (mesa, casa, muñeco de nieve, agujero booleano, pino, silla, taza de té, robot) superaron todas la aceptación con evidencia geométrica: por ejemplo, los 1012 vértices del robot son exactamente la suma de los vértices de 6 cubos + 2 esferas.

Nota metodológica: ejecutado por Claude como agente contra Blender real a través del canal JSON-RPC del addon (la misma capa de transporte que usa el servidor MCP); los registros por tarea están en eval_runs/ y docs/PHASE2_PROMPT_ENGINEERING.md. El benchmark también descubrió un defecto real del addon (scene_clear no podía limpiar objetos ocultos → conflicto de nombres duplicados), que se ha documentado en el registro de hallazgos: para eso existe el sistema de evaluación.

Inicio rápido

1. Instalación

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. Iniciar Blender

1. Instala el complemento: Blender → Editar → Preferencias → Complementos → Instalar… → selecciona addon/blender_mcp_addon (puedes empaquetarlo como ZIP con python scripts/package_addon.py, o enlazar el directorio directamente).

2. Habilita "MCP Server Addon".

3. En la vista 3D pulsa N → panel MCP Server → Start Server (puerto 9876 por defecto).

3. Usar como proveedor de herramientas MCP (cualquier cliente MCP)

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

Luego dile directamente al cliente: "Crea un cubo rojo en (2, 0, 0) y añade un modificador Subdivision Surface de nivel 2."

4. Ejecutar el agente LangGraph

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

Parámetros: --render (activa el renderizado de observación), --max-iterations, --prompt-version, --no-eval, -v. Métricas guardadas en: eval_runs/eval_runs.jsonl + eval_runs/records/.

5. Ejecutar el benchmark

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

Estructura del repositorio

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

Pruebas

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

Incluye pruebas de grafo de extremo a extremo con LLM falso: bucle de convergencia completo, ruta de recuperación de reparación de selección de herramientas y manejo explícito de fallos de análisis del revisor.

Documentación

• docs/tools.md — referencia completa de las 218 herramientas MCP

• docs/usage.md — ejemplos de uso de extremo a extremo

• docs/architecture.md — arquitectura MCP/servidor/addon

• docs/AGENT_ARCHITECTURE.md — diseño de la capa de agente (Fase 1, chino)

• docs/PHASE2_PROMPT_ENGINEERING.md — sistema de prompts, esquema, metodología de evaluación y benchmark, resultados reales, registro de hallazgos (chino)

• docs/MSFS_ROADMAP.md — pipeline de contenido MSFS

Hoja de ruta

• Fase 3 — Tool RAG: recuperar herramientas candidatas por tarea, en lugar de inyectar el catálogo completo de 218 herramientas; las métricas actuales sirven de línea base.

• Fase 4 — Revisión visual y memoria: un revisor multimodal basado en la herramienta existente analyze_viewport; memoria entre sesiones.

• Envolver el propio agente como un servidor MCP (exponiendo la herramienta única run_3d_task) para que lo consuman clientes de nivel superior.

Licencia y agradecimientos

• Este repositorio: AGPL-3.0-or-later.

• Base upstream: RFingAdam/mcp-blender (parte de eng-mcp-suite): el servidor MCP, el complemento de Blender y las 218 herramientas provienen del proyecto upstream; la capa de agente inteligente (agent/), el sistema de evaluación, el benchmark y la documentación del agente son contribuciones originales de este fork.

• El propio Blender sigue teniendo licencia GPL; solo se invoca en tiempo de ejecución y no se distribuye con este repositorio.

LangGraph · MCP · Ingeniería de prompts · Sistema de evaluación.