mcp-3d-modeling-agent
README.md
<div align="center">
# 基于 MCP 的智能 3D 建模 Agent
<br/>
[](https://www.python.org/downloads/)
[](https://www.blender.org/)
[](https://modelcontextprotocol.io)
[](https://langchain-ai.github.io/langgraph/)
[](tests/)
[](LICENSE)
**用 AI Agent 操控 Blender——218 个 MCP 工具覆盖完整 3D 管线，外加一个 LangGraph Agent 智能层：规划→执行→观察→评审→重规划的闭环、版本化 Prompt、Schema 门控的工具选择，以及一套可复现的 Benchmark。**
> 🌏 English: [README.en.md](README.en.md)
[本项目展示了什么](#本项目展示了什么) ·
[架构](#架构) ·
[Benchmark 结果](#benchmark-结果) ·
[快速开始](#快速开始) ·
[文档](#文档)
</div>
---
## 概述
本仓库由两层组成：
1. **MCP 基础层** *（基于上游 [RFingAdam/mcp-blender](https://github.com/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](agent/graph.py) —— 六节点 LangGraph 状态机 + plan 级外循环 |
| **MCP 集成（客户端侧）** | [agent/tools/mcp_client.py](agent/tools/mcp_client.py) —— 通过 stdio 消费真实 MCP server：`tools/list` 动态发现、schema 缓存、串行化调用 |
| **规模化 Prompt 工程** | [agent/prompts/](agent/prompts/) —— 版本化 Prompt 模板（`planner/v1.md` 等）、严格 JSON 契约、**节点代码中零硬编码 Prompt 文本** |
| **可靠性机制** | jsonschema 门控工具选择 + 一次 **Tool Selection Repair** 重试；criteria 覆盖强制（漏评的验收项永远无法静默通过）；解析失败的显式处理 |
| **上下文管理** | [agent/context/builder.py](agent/context/builder.py) —— 每节点最小上下文注入（Planner 只拿任务+场景；Executor 拿步骤+工具+最近结果；Reviewer 拿验收标准+观察数据） |
| **评估方法论** | [agent/evaluation/](agent/evaluation/) —— 每次运行记录 11 项指标（工具失败数、schema 失败数、重选数、重规划数、耗时、token 用量……），JSON + JSONL 持久化 |
| **Benchmark 设计** | [benchmarks/](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](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](docs/PHASE2_PROMPT_ENGINEERING.md)。Benchmark 还发现了一个真实的 addon 缺陷（`scene_clear` 无法清除隐藏对象 → 重名对象冲突），已写入文档发现记录——这正是评估体系存在的意义。*
---
## 快速开始
### 1. 安装
```bash
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 客户端）
```json
{
"mcpServers": {
"blender": { "command": "mcp-blender", "args": ["--port", "9876"] }
}
}
```
然后直接对客户端说：*"创建一个红色立方体放在 (2, 0, 0)，加一个 2 级 Subdivision Surface 修改器。"*
### 4. 运行 LangGraph Agent
```bash
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
```bash
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 设计文档
```
---
## 测试
```bash
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](docs/tools.md) — 218 个 MCP 工具的完整参考
- [docs/usage.md](docs/usage.md) — 端到端使用示例
- [docs/architecture.md](docs/architecture.md) — MCP/server/addon 架构
- [docs/AGENT_ARCHITECTURE.md](docs/AGENT_ARCHITECTURE.md) — Agent 层设计（Phase 1，中文）
- [docs/PHASE2_PROMPT_ENGINEERING.md](docs/PHASE2_PROMPT_ENGINEERING.md) — Prompt 体系、Schema、评估与 Benchmark 方法论、实测结果、发现记录（中文）
- [docs/MSFS_ROADMAP.md](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](LICENSE)。
- **上游基础**：[RFingAdam/mcp-blender](https://github.com/RFingAdam/mcp-blender)（隶属 [eng-mcp-suite](https://github.com/RFingAdam/eng-mcp-suite)）——MCP server、Blender 插件与 218 个工具来自上游项目；**Agent 智能层（`agent/`）、评估系统、Benchmark 与 Agent 文档为本 fork 的原创贡献**。
- Blender 本体仍为 GPL 许可，仅运行时调用，不随本仓库分发。
<div align="center">
<sub> LangGraph · MCP · Prompt 工程 · 评估体系。</sub>
</div>
TDQS
B3/5.0
Scored across 218 tools
Disambiguation2/5
The set contains several near-duplicate tools that make agent selection hard: blender_refine_iteration and blender_ai_refine both describe the same render-evaluate-suggest loop, and blender_ai_list_backends overlaps heavily with blender_ai_probe_backends. Many workflows also have two parallel implementations (e.g., blender_scatter_on_surface vs blender_geonode_scatter_instances), so boundaries are often unclear even when individual descriptions are good.
Naming Consistency4/5
Most tools follow a clear blender_<domain>_<action> or blender_<domain>_<noun> snake_case pattern, which makes large chunks like blender_object_*, blender_mesh_*, and blender_msfs_* predictable. Deviations exist (blender_undo, blender_save, blender_silhouette_compare, blender_mesh_proportional_transform, blender_sculpt_to_retopo), but they are few compared to the 218-tool surface.
Tool Count1/5
218 tools is an extreme count for any MCP server, far beyond the threshold where a toolset becomes unwieldy. The surface tries to cover entire Blender plus MSFS and AI pipelines in one server, making discovery and selection expensive for agents.
Completeness4/5
The domain coverage is impressively broad: object/scene lifecycle, mesh editing, materials, animation, rendering, physics, rigging, sculpting, baking, geometry nodes, and MSFS-specific workflows are all present. Minor gaps exist (no material_delete, no constraint_remove, no individual object visibility toggle, no render samples/output settings), but agents can often work around them via blender_execute_script.
Maintenance
ActivitySlowing
ResponsivenessNo issues