MCP 기반 지능형 3D 모델링 Agent

AI Agent로 Blender 제어——218개 MCP 도구가 전체 3D 파이프라인을 커버하고, 여기에 LangGraph Agent 지능 계층이 더해집니다: 계획→실행→관찰→검토→재계획의 폐쇄 루프, 버전 관리되는 Prompt, Schema 게이트 기반 도구 선택, 그리고 재현 가능한 Benchmark.

🌏 English: README.en.md

이 프로젝트가 보여주는 것 · 아키텍처 · Benchmark 결과 · 빠른 시작 · 문서

개요

본 저장소는 두 개의 계층으로 구성됩니다:

1. MCP 기반 계층 (상위 프로젝트 RFingAdam/mcp-blender, eng-mcp-suite 기반) —— 218개의 Blender 도구(모델링, 머티리얼, 모디파이어, 애니메이션, 렌더링, 조각, 지오메트리 노드, 물리, AI 3D 생성, MSFS 콘텐츠 파이프라인)를 모든 MCP 클라이언트에 노출하는 MCP server.

2. Agent 지능 계층 (agent/ 디렉토리, 본 저장소의 독자적 작업) —— LangGraph 기반 3D Agent: 작업 계획, MCP 도구를 통한 실행, 씬 사실 수집, 수용 기준을 항목별로 검증(증거 필수), 최소 수정——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 계층은 네 번째 프로세스로, 기존 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 문서는 본 fork의 독자적 기여.

• Blender 본체는 여전히 GPL 라이선스이며, 런타임 호출만 할 뿐 본 저장소에 배포되지 않습니다.

LangGraph · MCP · Prompt 엔지니어링 · 평가 체계.