<div align="center">

基于 MCP 的智能 3D 建模 Agent

<br/>

用 AI Agent 操控 Blender——218 个 MCP 工具覆盖完整 3D 管线，外加一个 LangGraph Agent 智能层：规划→执行→观察→评审→重规划的闭环、版本化 Prompt、Schema 门控的工具选择，以及一套可复现的 Benchmark。

🌏 English: README.en.md

本项目展示了什么 · 架构 · Benchmark 结果 · 快速开始 · 文档

</div>

---

概述

本仓库由两层组成：

1. MCP 基础层 （基于上游 RFingAdam/mcp-blender，eng-mcp-suite） —— 一个 MCP server，把 218 个 Blender 工具（建模、材质、修改器、动画、渲染、雕刻、几何节点、物理、AI 3D 生成、MSFS 内容管线）暴露给任意 MCP 客户端。
2. Agent 智能层 （agent/ 目录，本仓库原创工作） —— 基于 LangGraph 的 3D Agent：规划任务、通过 MCP 工具执行、采集场景事实、逐条验证验收标准（必须给出证据）、最小化修复——配套 Prompt 版本化、结构化输出契约、评估日志和 16 任务 Benchmark。

---

本项目展示了什么

完整的工程实践——让 LLM Agent 变得可靠、可度量、可工程化。

能力	对应代码
Agent 架构设计	agent/graph.py —— 六节点 LangGraph 状态机 + plan 级外循环
MCP 集成（客户端侧）	agent/tools/mcp_client.py —— 通过 stdio 消费真实 MCP server：tools/list 动态发现、schema 缓存、串行化调用
规模化 Prompt 工程	agent/prompts/ —— 版本化 Prompt 模板（planner/v1.md 等）、严格 JSON 契约、节点代码中零硬编码 Prompt 文本
可靠性机制	jsonschema 门控工具选择 + 一次 Tool Selection Repair 重试；criteria 覆盖强制（漏评的验收项永远无法静默通过）；解析失败的显式处理
上下文管理	agent/context/builder.py —— 每节点最小上下文注入（Planner 只拿任务+场景；Executor 拿步骤+工具+最近结果；Reviewer 拿验收标准+观察数据）
评估方法论	agent/evaluation/ —— 每次运行记录 11 项指标（工具失败数、schema 失败数、重选数、重规划数、耗时、token 用量……），JSON + JSONL 持久化
Benchmark 设计	benchmarks/ —— 16 个任务、4 个难度级别、聚合指标报告、真实 Blender 实测结果
测试	128 个测试全部通过：单元测试、JSON Schema 校验、Router 决策矩阵、假 LLM 端到端闭环测试

---

架构

┌───────────────┐   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（循环）

节点	职责
Planner	只管 WHAT：目标 + 约束 + 步骤 + 验收标准（success_criteria）。绝不选择工具。
Executor	负责 HOW：基于运行时 tools/list 目录为每一步选择 MCP 工具；参数经 jsonschema 校验；优先级：结构化工具 > 结构化组合 > execute_script 兜底；最少工具原则。
Observer	采集确定性场景事实（场景信息、对象清单、网格统计）——Reviewer 的证据来源。
Reviewer	逐条验证每个验收标准并要求证据；"声称通过但无证据"会被代码纠正；漏评的标准显式判为未通过。
RePlanner	最小修复：只重规划未通过的标准；已验证的工作绝不重做。
Router	确定性路由：通过或达到迭代上限 → 结束；否则 → 重规划。

可靠性由代码强制而非依赖 Prompt 自觉：schema 校验 + 一次 Tool Selection Repair 重试、criteria 覆盖强制、任何解析失败都显式降级（记录进 state、暴露给 Reviewer——绝不静默）。

实测演示

Agent 思考与决策过程	Blender 中的生成结果

---

Benchmark 结果

在真实 Blender 4.x 实例上实测——Agent 执行了 benchmarks/tasks.json 中全部 16 个任务（4 个难度级别，从基础创建到组合建模），每个任务进行基于证据的验收。

指标	结果
任务成功率	16/16（100%）
工具调用成功率	69/69（100%）
Schema 失败率	0/69
平均工具调用数 / 任务	4.31（L1≈2.3 → L4≈6.5）
平均重规划数 / 任务	0.19
平均工具耗时 / 任务	0.95 s

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 许可，仅运行时调用，不随本仓库分发。

<div align="center">

_{LangGraph · MCP · Prompt 工程 · 评估体系。}

</div>