搅拌机ai-mcp

![License: Apache 2.0](./LICENSE.md) ![Python 3.11+](https://www.python.org/downloads/) ](https://github.com/PatrykIti/blender-ai-mcp/pkgs/container/blender-ai-mcp) ![CI Status](https://github.com/PatrykIti/blender-ai-mcp/actions) ](https://github.com/PatrykIti/blender-ai-mcp/stargazers) ](https://github.com/sponsors/PatrykIti)

Blender的生产型MCP服务器。

blender-ai-mcp 让Claude、ChatGPT、Codex和其他MCP客户端通过稳定的工具API控制Blender，而不是专门生成Python。其结果是为真实的建模工作提供了一个更安全、更小、更可靠的表面：目标优先的路由、精心策划的公共工具、确定性检查和不依赖于猜测的验证。

为什么存在

大多数“AI+Blender”设置仍然要求模型编写原始代码 bpy 脚本。这恰好打破了生产工作变得有趣的地方：

Blender API在不同版本之间漂移。
当活动对象、模式或选择错误时，上下文相关运算符会失败。
当出现问题时，原始脚本会给出微弱的反馈。
愿景可以描述结果，但不能被信任为最终权威。

blender-ai-mcp 采取相反的方法：将Blender控件视为产品表面，而不是代码生成噱头。

为什么使用MCP服务器而不是原始Python

稳定的合约胜过脚本合成。 该模型调用具有经过验证的参数的工具，而不是即兴编写Blender代码。
目标优先编排。 正常的指导课程从开始 router_set_goal(...)，因此系统在开始调用低级操作之前就知道模型试图构建什么。
公共面积小。 默认值 llm-guided profile公开了一个微小的、搜索优先的引导层，而不是用整个运行时清单淹没模型。
真相第一验证。 检查、测量和断言工具确定Blender中的实际情况。
安全执行边界。 Blender插件在Blender的主线程上执行操作，而MCP服务器处理路由、验证、发现和结构化响应。

产品法

商业理念在 TASK-113 很简单：

原子工具 是实现的基础。它们保持小而精确，并且大多隐藏在正常的公共表面之外。
宏工具 是有意义任务大小工作的首选LLM面层。
工作流工具 是有界的多步骤流程工具，具有明确的报告，而不是开放式的“做任何事情”端点。
目标优先编排 使会话固定在一个积极的意图上，而不是让模型在每次转弯时都重新发现上下文。
视觉辅助解读，而确定性测量和断言提供了最终的真值层。
可插拔的视觉运行时间 现在涵盖了本地MLX加上外部OpenRouter和Google AI Studio/GGemini提供程序路径，以及用于提示/模式/解析器行为的特定于模型系列的外部契约配置文件。

这就是将该项目从“通过MCP公开的Blender工具”转变为用于建模管道的可用AI控制产品的原因。

LLM引导公共表面

llm-guided 是默认的面向生产的曲面。它故意设计得很小，搜索优先，并围绕目标感知会话进行设计。

正常引导流量：

router_set_goal(...)
browse_workflows, search_tools，或 call_tool
使用分组/公共工具，如 check_scene, inspect_scene，或 configure_scene
通过检查加验证 scene_measure_* 和 scene_assert_*

提示规则：

使用prompt库资产 \_docs/\_PROMPTS/README.md 作为规范的指导操作说明
当客户流失时，预先添加 guided_session_start 作为通用搜索第一稳定器
如果工具在当前表面/相位上尚未直接可见，请使用 search_tools(...) 之前 call_tool(...)

当有界建模意图匹配时，默认的公共工作层应该是宏层：

macro_cutout_recess 用于凹槽、开口和切割器驱动的切口
macro_relative_layout 用于对齐/放置/接触间隙零件布局
macro_attach_part_to_surface 用于将一个零件放置在另一个物体的表面/主体上
macro_align_part_with_contact 对于几乎合身的鞋子，只需轻轻推一下即可修复
macro_place_symmetry_pair 用于在显式镜像平面周围放置/校正镜像对
macro_place_supported_pair 用于在一个共享支撑表面上放置/校正镜像对
macro_cleanup_part_intersections 无需自由碰撞求解的有界成对重叠清理
macro_adjust_relative_proportion 用于相关对象之间的有界比率修复
macro_adjust_segment_chain_arc 用于有序分段链上的有界弧调整
macro_finish_form 用于预设驱动斜面/细分/固化精加工
reference_images 有界视觉比较前的目标范围参考摄入量
reference_guided_creature_build 作为分阶段通用生物工作的本地即时资产 llm-guided
recommended_prompts 现在可以通过使用主动目标/会话上下文将面向生物的引导会话引导到提示路径
guided_reference_readiness 上 router_set_goal, router_get_status，并分阶段比较/迭代有效载荷，以便客户端可以查看参考驱动的阶段工作是否真正准备就绪
reference_compare_stage_checkpoint 用于在手动迭代工作期间与附加参考进行确定性多视图阶段比较
reference_iterate_stage_checkpoint 对于一个会话感知的分阶段校正循环，它会记住之前的焦点，当相同的校正重复时，可以升级为检查/验证，现在可以针对一个对象、多个对象、一个集合或完整的组装轮廓
阶段比较/迭代现在也暴露了确定性 silhouette_analysis 类型化指标 action_hints，仅供咨询 part_segmentation 除非明确启用单独的sidecar，否则占位符将保持禁用状态
scene_scope_graph 对于一个带有锚/核心/附件角色提示的显式只读结构范围工件
scene_relation_graph 对于从当前真值层导出的一个显式只读对关系工件
scene_view_diagnostics 对于一个显式的只读视图空间伪影，具有投影范围、帧覆盖范围、中心以及命名相机的可见/部分/遮挡/帧外判断，或 USER_PERSPECTIVE
这些空间图形/视图诊断工具现在是默认可见的一部分 llm-guided 支持集，使模型可以保持一个明确的3D方向层可用，而不是仅从名称、屏幕截图或部分循环有效载荷推断空间状态

当前引导引导引导曲面：

router_set_goal
router_get_status
browse_workflows
reference_images
scene_scope_graph
scene_relation_graph
scene_view_diagnostics
search_tools
call_tool
可选提示桥接工具 MCP_PROMPTS_AS_TOOLS_ENABLED=true:

- list_prompts - get_prompt

有提示能力的客户端应该更喜欢本机MCP提示。快速桥是一座仅适用于工具客户端的兼容层，可以对Streamable HTTP禁用已经使用本机提示组件的配置文件。

当前指导的实用程序准备路径：

引导/计划搜索现在可以到达：

- scene_get_viewport - scene_clean_scene

这些实用程序操作保持受限，不会重新打开整个遗留曲面
规范引导的发现包装器是 call_tool(name=..., arguments=...)
规范清理参数形状 llm-guided 是

keep_lights_and_cameras；旧的拆分标志仅用于兼容性不应作为有文件记录的公共表格使用

reference_images(action="attach", source_path=...) 每次通话有一个参考；

批处理形状现在会在引导恢复指导下失败，而不是原始模式噪声

collection_manage(action=..., collection_name=...) 保持规范

公共形态；遗产 name 只是一个狭义的兼容性别名

modeling_create_primitive(...) 仅限于 primitive_type,

radius/size, location, rotation，可选 name；不受支持快捷方式，如 scale, segments, rings, subdivisions，或原始时间 collection_name 现在，在这两方面都有可操作的指导，但都失败了直接路径和代理引导路径

构建目标仍应从以下方面开始 router_set_goal(...)，但截图/

视口/场景重置请求应使用引导的实用程序路径

如果只有在进入引导构建后才发现过时的场景状态

表面， scene_clean_scene(...) 也可以在那里作为有界回收舱；目标前的清理仍然是首选路径

需要恢复时，仍然允许进行构建阶段清理

上的当前公共别名 llm-guided:

内部工具	`llm-guided` 公共名称	公共参数更改
`scene_context`	`check_scene`	`action` -> `query`
`scene_inspect`	`inspect_scene`	`object_name` -> `target_object`
`scene_configure`	`configure_scene`	`settings` -> `config`
`workflow_catalog`	`browse_workflows`	`workflow_name` -> `name`, `query` -> `search_query`

为什么这很重要：

引导配置文件从一个紧凑的可见引导集开始，而不是

完整目录

分组/公共工具易于发现
隐藏的原子工具仍然可以作为基础设施使用，而不是作为默认的公共心智模型
在宏观表面更宽之前，专业家庭不会进入正常的引导进入层

原子基础和文件

根 README.md 是故意的不完整的工具目录。

详细的工具清单和原子族文档应保留在文档中，而不是在首页上。这是正确的长期结构 TASK-113.

根据您的需要使用这些文档：

工具分层策略

- 规范政策 atomic / macro / workflow、隐藏的原子工具、目标优先的使用和愿景/断言边界。

MCP服务器文档

- Surface配置文件、引导别名、版本化合同和运行时/平台指导。

MCP客户端配置示例

- 准备粘贴本地MCP客户端配置示例，用于指导/手动表面以及MLX、OpenRouter和Gemini视觉变体。

视觉层文档

- 运行时/后端、捕获包、参考图像、宏/工作流视觉集成说明，以及用于直接用户视图和固定相机透视捕获的仓库跟踪的真实视口评估包。

LLM指南v2

- 类型化空间智能层、紧凑关系状态和有界下一步切换的策略文档，用于指导操作。

空间智能研究简报

- LLM/VLM空间推理、多视图推理和几何感知规划的外部研究切换。

空间智能升级方案

- 研究驱动的场景图、符号关系表示法和支持几何库选择的升级建议。

可用工具摘要

- 完整的库存和分组/公共工具概述。

工具架构索引

- MCP表面下方面向维护人员的工具系列图。

如果您想查看服务器构建的原子族，请从这里开始：

推荐解释：

保持 /_docs/TOOLS/ 作为面向原子/分组架构图的维护者
保持 README.md 产品外观紧凑
保持 /_docs/AVAILABLE_TOOLS_SUMMARY.md 作为运行时清单

提供商备注

当前简短版本：

本地默认值： mlx_local 具有Qwen VL 4B类模型路径；当前回购验证基线为 mlx-community/Qwen3-VL-4B-Instruct-4bit
外部迭代比较候选： OpenRouter x-ai/grok-4.20-multi-agent
外部谷歌家族比较路径： OpenRouter托管的谷歌家族模型加上谷歌人工智能工作室/双子座现在通过解析共享相同的窄阶段比较合同 vision_contract_profile 路由

外部视觉运行时注意事项：

VISION_EXTERNAL_PROVIDER 选择传输/提供商分支
VISION_EXTERNAL_CONTRACT_PROFILE 可选地覆盖外部比较流的提示/模式/解析器契约
当未设置覆盖时，运行时会自动匹配Google系列型号ID，例如 gemma / gemini / learnlm，然后回退到提供程序默认值

每个提供商表的详细信息：

视觉层文档->提供者注释

建筑

系统被故意拆分：

MCP服务器(server/)：FastMCP表面、公共工具定义、转换、发现和响应契约。
路由器(server/router/)：目标解释、安全/纠正策略、工作流程匹配、会话上下文和指导执行行为。
搅拌机插件(blender_addon/)：实际 bpy 执行、RPC处理程序和Blender主线程安全操作调度。

通信通过TCP套接字上的JSON-RPC进行。

更多细节：

结构化合同基线

服务器正在将关键表面移向机器可读的有效载荷，而不是繁重的JSON字符串。

当前结构化合同基线包括：

macro_cutout_recess
macro_finish_form
macro_attach_part_to_surface
macro_align_part_with_contact
macro_place_supported_pair
macro_cleanup_part_intersections
macro_relative_layout
scene_create
scene_configure
mesh_select
mesh_select_targeted
mesh_inspect
scene_snapshot_state
scene_compare_snapshot
scene_measure_distance
scene_measure_dimensions
scene_measure_gap
scene_measure_alignment
scene_measure_overlap
scene_assert_contact
scene_assert_dimensions
scene_assert_containment
scene_assert_symmetry
scene_assert_proportion
router_set_goal
router_get_status
workflow_catalog

这对于自动化、审计和未来的宏/工作流组合非常重要。

接触真理语义学

对于弯曲或圆形形状的接触敏感检查，现在使用真值层区别：

当有界网格感知路径为

可用的

当网格感知路径不可用时，bbox回退语义

这意味着一对仍然可以显示bbox接触，而主要的测量关系残余 separated 如果真实网格表面仍然有可见的间隙。引导混合真相跟踪现在在面向操作员的情况下延续了这一区别摘要，而不是将其折叠为通用的“联系人通过/失败” 索赔。

当网格感知路径发现真正的重叠时，主要的测量关系也停留 overlapping，因此重叠拒绝 scene_assert_contact(...) 仍然它作为一个单独的真理条件起作用，而不是崩溃成简单的接触。

结构化澄清流程

引导表面支持将缺失的输入处理作为产品合同的一部分，而不是事后的想法。

模型第一澄清 是的默认值 router_set_goal(...) 上 llm-guided：缺少工作流参数将返回类型化的 needs_input 首先将有效载荷传输到外部模型。
键入回退有效载荷 保持相同的流在纯工具或兼容客户端上可用。
人为/本地澄清保留用于后续/回退策略，而不是工作流执行的默认第一步。
router_set_goal(...) 可以请求受限选项、布尔值、枚举或工作流确认。
partial answers 在后续的转折中幸存下来。
workflow_catalog 导入冲突重用相同的澄清模型。

指导交接合同

引导式界面现在将工作流回退视为显式类型的契约，而不是隐藏在散文中的阶段副作用。

router_set_goal(...) 回报 guided_handoff 在有界连续路径上，例如 continuation_mode="guided_manual_build" 和 continuation_mode="guided_utility".
guided_handoff 命名 target_phase, direct_tools, supporting_tools，以及 discovery_tools 下一步 llm-guided.
workflow_import_recommended 停留 False 在这些回退路径上，除非用户明确要求工作流导入/创建行为。
router_get_status(...) 保留活动 guided_handoff 会话中诊断，以便客户端可以恢复预期的继续路径。

服务器驱动的引导流状态

引导表面现在带有一个明确的机器可读表面 guided_flow_state 合同除 guided_handoff.

router_set_goal(...), router_get_status(...),

reference_compare_stage_checkpoint(...)，以及 reference_iterate_stage_checkpoint(...) 可以暴露 guided_flow_state 对于活跃的 llm-guided 会话

guided_flow_state 报告：

- flow_id - domain_profile - current_step - completed_steps - active_target_scope - spatial_scope_fingerprint - spatial_state_version - spatial_state_stale - last_spatial_check_version - spatial_refresh_required - required_checks - next_actions - blocked_families - allowed_families - allowed_roles - completed_roles - missing_roles - required_role_groups - required_prompts - preferred_prompts - step_status

当前的域覆盖是：

- generic - creature - building

早期的引导构建会话现在从阶梯式空间上下文开始

阶段，而不是立即暴露整个构建表面

scene_scope_graph(...) 在没有活动时绑定活动的引导目标范围

范围还存在；空间刷新检查必须继续使用已绑定的空间目标作用域，而不是重新绑定到不同的对象集

不相关的视图检查，例如

scene_view_diagnostics(target_object="Camera", ...) 不满足a 生物/建筑空间检查

如果为主动引导目标附加了参考图像，请将其视为

在决定第一个身体/头部/尾部质量之前的主要接地输入轮廓粗糙

使用完整的语义对象名称，例如 Body, Head, Tail,

ForeLeg_L，以及 HindLeg_R 而不是像这样不透明的缩写 ForeL / HindR，因为引导接缝/角色启发式算法在可读性方面更可靠名字

上 llm-guided，服务器现在可以对弱角色敏感名称发出警告

阻止明显不透明的占位符名称，例如 Sphere / Object 当他们用作语义零件名称

不要打电话 scene_scope_graph(...), scene_relation_graph(...)，或

scene_view_diagnostics(...) 没有明确的范围，并假设这意味着 “检查整个现场”

在主动引导空间门或空间刷新重新启动期间

这些空间助手应该被视为显式作用域工具，而不是全景探测器

那些固定的只读空间助手在上可见时仍可调用

llm-guided；指导性家庭封锁不得拒绝 scene_scope_graph(...), scene_relation_graph(...)，或 scene_view_diagnostics(...) 仅仅是因为当前的构建步骤 allowed_families 省略 spatial_context

在引导门之外，作用域/关系图构建器仍然需要

明确的 target_object, target_objects，或 collection_name；光秃秃的呼叫现在失败，而不是默默地返回空 scene 范围

默认占位符范围，如股票 Cube 或通用根

Collection 不再被视为有意义的指导目标/工作集自行绑定

但对于之前的“这个场景已经不是空的了吗？”引导决策，

搅拌机库存 Cube 加上库存相机/灯光助手仍然进入空场景主工作集引导路径

这个非空的决定是有意在启动后命名为轻：真实

具有默认基本体名称的多对象粗略分块，例如 Cube 或 Sphere 仍然算作现有几何体，而仅辅助对象的场景仍然可以进入 bootstrap_primary_workset

显式引导作用域现在从调用者意图而不是名称绑定

启发式，所以真实的对象命名为 Cube, Sphere，或 Sunflower 当操作员瞄准它们时，它们仍然可以成为活动的引导工作集

在材质场景更改后，例如 scene_clean_scene(...),

scene_duplicate_object(...), scene_rename_object(...), modeling_create_primitive(...), modeling_transform_object(...), modeling_join_objects(...), modeling_separate_object(...)，或有界附件/对齐宏，引导运行时可以标记空间层停止并重新武装所需的检查

相同的脏状态更新现在立即重新应用FastMCP可见性，

因此，客户一看到所需的空间支持工具 spatial_refresh_required 持续存在

在流式HTTP上，引导脏状态和可见性终结器必须完成

在主动工具响应返回之前；更改场景的路由同步工具状态将这些终结器推迟到MCP异步包装器，而不是调度分离会话状态写入

异步包装器和本机异步建模助手保持阻塞

同步工作线程上的路由器/RPC执行；只有引导式终结器运行在Streamable HTTP响应完成之前返回事件循环

异步脏宏助手，例如 macro_cutout_recess(...) 和

macro_finish_form(...) 使用等待的异步路由路径，以便可见性在Streamable HTTP响应完成之前重新应用

异步空间助手，例如 scene_scope_graph(...),

scene_relation_graph(...)，以及 scene_view_diagnostics(...) 路线他们 Blender支持的图形/诊断在记录之前读取事件循环引导式空间检查完成

异步引导身份终结器，如成功 scene_rename_object(...)

验证还可以在之前将Blender支持的场景查找排除在事件循环之外更新引导部件注册表

使用路由器执行报告的本机异步建模工具必须仍然

表面 guided_naming 通过活动MCP上下文发出警告；否则弱语义名称可能会失去其模型，面临更正提示可流式传输的HTTP

原生异步建模和清理终结器导出成功的场景

结构化突变 report.steps，而不是呈现的传统路线文本；多步校正的路由前缀为传统线路，不是可靠的来源用于指导脏状态或角色注册决策

异步引导角色注册在决赛后重新应用FastMCP可见性

先进的 guided_flow_state 坚持，所以 list_tools() 反映了 Streamable HTTP响应完成前的新引导步骤

异步公共工具变体必须保留原始公共文档字符串，

特别是对于可视化引导的空间和建模助手，其描述教授所需的范围参数、工作流顺序和参数约束

当路由器成功纠正错误时 modeling_transform_object(...) 呼叫

到另一个有效的对象名称、引导的空间脏状态和引导的角色后续使用最终建模返回的转换对象名称 step，而不是原始调用者提供的名称

引导式网格编辑工具，如 mesh_extrude_region(...),

mesh_loop_cut(...)，以及 mesh_bevel(...) 现在已映射到 secondary_parts 家庭，因此它们在空间上下文门期间被阻止并在成功编辑几何图形后重新进行空间检查

当其中一个所需的空间检查完成并推进制导装置时

流，服务器现在立即重新应用FastMCP可见性，而不是等待稍后的状态/搜索刷新

支持/对称感知关系对现在保持支持和对称

即使它们共享相同的注释 (from_object, to_object) 密钥为a 通用的主要目标对，因此后来的引导规划者仍然可以看到支持/对称语义，而不仅仅是通用边

包含所需生物接缝的关系图仍然增加了回退

primary_to_other 在请求的范围内为非接缝对象配对，因此未分类对象不会从混合引导诊断中消失

健康的支撑/对称对不再仅仅因为其

中心不同或它们不是字面上的接触对；仅 unsupported / asymmetric 支持/对称性判断在那里被视为失败

当 guided_flow_state.spatial_refresh_required == true，治疗

next_actions=["refresh_spatial_context"] 作为权威服务器状态，不是咨询性散文；焕然一新 scene_scope_graph(...) 反对已先绑定目标作用域，然后重新运行剩余的所需空间检查同一范围

scene_view_diagnostics(...) 仅在以下情况下计入导向空间门

它返回真实的可用视图空间证据；无头/不可用的探头保持只读，本身不满足所需的检查

如果阶段比较/迭代在当前指导下发现重要问题

角色/工作集切片仍然不完整，调控器现在可以保留会话在有界构建中继续，而不是过早升级到 inspect_validate

当未完成的阶段保持返回时

loop_disposition="continue_build"，坚持 guided_flow_state 保持在当前步骤中，不标记未完成的角色切片已完成；继续关注 missing_roles 在依赖后期之前可见性

这种不完整的阶段保持也适用于阶段迭代没有

correction_focus 或 action_hints；无行动比较结果不得推进具有所需缺失角色的指导构建 finish_or_stop

在流程到达后续步骤之后，例如 place_secondary_parts，the

服务器仍然可以在缺少的主质量作为其一部分时保持可用相同的有界工作集，而不是强制松鼠/建筑物运行立即放弃未完成的核心质量

对于生物遮挡接缝， intersecting 仍然可以接受

嵌入耳朵/头部或鼻子/头部位置，但 floating_gap 在头部/身体上，尾巴/身体，或四肢/身体仍然可以操作

如果所需的工具系列被流隐藏/阻挡，请检查

router_get_status().guided_flow_state，填写所列内容 required_checks，并遵循 next_actions 而不是猜测隐藏的工具名字进入 call_tool(...)

如果明确的指导目标停留在手动/无匹配路径上

模式建议工作流仍可以扩展；那里面还压抑着什么状态是较低置信度的启发式重新开放路径

现在，在引导曲面上进行精确的工具名称搜索，以返回

更紧凑、更小的结果集，而不是用完整的结果集淹没模型扩展有效载荷以实现简单查找

对于角色敏感的构建步骤，请处理 allowed_roles 和 missing_roles 作为

执行合同的一部分，而不是咨询性散文

内务管理/工作台操作，如 collection_manage(...) 应该留下来

可用于已创建的对象，即使它们的语义角色是在较早的步骤中注册

可以保留已注册主对象的有界细化

在会话进入下一步后可能；后续步骤不是旨在完全冻结所有早期的物质

使用 guided_register_part(object_name=..., role=...) 作为规范

告诉服务器一个对象代表什么语义部分的方法；可选的 guided_role=... 关于构建工具的提示只是为了方便

可选的 role_group=... 值必须与服务器的域角色映射匹配；

呼叫者无法重新分类 body_core, head_mass，或类似角色敏感突变呼叫 utility 或另一个家庭绕过电流导向相位门

guided_register_part(...) 现在验证命名的Blender对象

实际存在之前，它可以算作引导角色完成；拼写错误不自行创建已完成的角色

如果引导对象验证根本无法读取Blender场景，

guided_register_part(...) 现在显然失败了，而不是在指导下变异未经验证的对象名称的会话状态

传入的显式目标名称 scene_scope_graph(...) /范围构建

在引导之前，路径现在遵循相同的Blender真理验证规则范围可以绑定

那些可选 guided_role=... 提示仅在激活时自动注册

引导流已经存在；在主动引导流之外，它们不会产生自身持续的角色状态

失败的create调用现在对于引导角色状态也保持不变：

如果 modeling_create_primitive(...) 返回一个失败字符串，请求角色不会仅仅因为语义而自动注册 name 已供应

上 modeling_create_primitive(...), guided_role=... 现在还需要一个

显式语义 name；引导创建不允许自动生成Blender 名称将成为语义部分注册

当路由器预先准备纠正步骤时，例如 scene_set_mode(...),

成功的引导创建/转换调用仍会注册生成的角色反对最终建模步骤，而不是放弃便利性注册只是因为通话变得多步骤

引导式角色便利注册现在还可以处理有效的对象名称

包含撇号，例如 King's Crown，而不是截断存储对象名称

引导运行时成功解析还处理引号对象内的撇号

名称作为创建/转换/重命名/连接结果的对象名称的一部分，因此，成功后仍会运行过时状态标记和引导注册表同步突变

规范的配对名称，如 ForeLeg_L, ForeLeg_R，以及 ForeLegPair

现在将其视为强语义名称 foreleg_pair / hindleg_pair 而不是在更严格的命名策略下发出警告或阻止

上 modeling_create_primitive(...)，引导角色自动注册现在绑定

到Blender返回的实际创建的对象名称，因此角色状态保持不变即使Blender自动为默认名称编号，如 Cube.001 或使用不同的默认对象名称，例如 Suzanne

上 modeling_transform_object(...)，引导角色自动注册现在绑定

到最终路由步骤返回的实际转换对象名称，因此路由器纠正的对象身份仍然会重新进行空间检查和更新真正更改的对象的角色状态

成功的 scene_rename_object(...) 调用现在保留引导部件注册表

与重命名的Blender对象对齐，以便以后进行角色敏感的转换仍然可以恢复已注册的角色，而无需手动重新注册

成功的 scene_rename_object(...) 呼叫还重新启用了手臂引导的空间

检查，因为绑定的目标范围指纹是基于名称的

成功的 scene_duplicate_object(...) 呼叫还重新启用了手臂引导的空间

检查，因为重复会更改可见的工作集/范围关系事实

普通字符串突变结果失败，例如 Object 'Missing' not found

现在保持引导会话状态不变；它们不会重新武装空间仅仅因为包装器返回，就检查或重写引导角色注册一串

scene_clean_scene(...) 现在清除引导部件注册表并返回

引导流至 bootstrap_primary_workset 而不是携带完成在空旷的场景中向前移动

现在，在同一会话中启动不同的指导目标会重置指导部分

注册新流程，而不是继续执行已完成的角色从上一个对象

破坏性的身份/拓扑变化，如 modeling_join_objects(...)

或 modeling_separate_object(...) 现在放弃过时的引导部件注册；如果结果对象仍然计数，则显式重新注册它们朝向引导式角色完成

这些相同的破坏性拓扑变化也重新武装了引导的空间检查，

因为之前捕获的范围/视图事实在以下情况下不再可信对象被合并或拆分

对于宏观捕捉/视觉伪影， macro_attach_part_to_surface(...) 现在

在额外的网格表面轻推后刷新其动作后捕捉包，因此，附上的图片和真相摘要描述了最终的坐姿前轻推中间姿势

路由宏报告可以是 partial 并且仍然携带 error；MCP

适配器保留该结构化报告，包括 actions_taken, 修改对象、验证建议、捕获/真相数据，以及后续指导，而不是把它塞进一个失败的空信封里

如果在运行时配置中启用了可选的分段sidecar，但尚未启用

在当前比较路径上执行，现在分阶段比较/迭代响应报告 part_segmentation.status="unavailable" 而不是默默地呆着 disabled

如果服务器警告或阻止引导命名，请重命名或创建对象

使用建议的语义名称之一，而不是重试相同的弱名称缩写

引导命名和引导空间角色推理现在使用标记边界样式

匹配而不是原始子字符串匹配，因此以下名称 Heart 或 TruthBodyAnchorHead 不要成为偶然的语义耳朵/身体/头部角色

这 required prompt bundle 和 preferred prompt bundle 命名为

guided_flow_state 是提示的资产名称，而不是替代服务器驱动流；提示支持流，它们不会成为流

引导参考准备

参考驱动的分阶段工作现在有一个明确的准备就绪合同，而不是隐藏的排序假设。

router_set_goal(...) 和 router_get_status(...) 揭露 guided_reference_readiness.
有效载荷报告 attached_reference_count, pending_reference_count,

compare_ready, iterate_ready，加上机器可读 blocking_reason 和 next_action

reference_images(action="attach", source_path=...) 可以等待，直到导游

目标会话实际上已经准备就绪，然后自动采用

如果同一个进球已经有了活跃的裁判，并且在

needs_input，上演的裁判与已经活跃的进球分开参考，直到准备就绪返回

如果就绪会话仍然携带另一个目标的明确未决参考，

reference_images(action="list"| "remove"| "clear", ...) 现在治疗一致地合并可见集，而不是留下损坏的未决记录

reference_compare_stage_checkpoint(...) 和

reference_iterate_stage_checkpoint(...) 现在会话失败很快未准备好，并重复同样的操作 guided_reference_readiness 有效载荷

如果 reference_iterate_stage_checkpoint(...) 回报

loop_disposition="inspect_validate"，停止自由形式建模并切换到立即检查/测量/断言

如果它回来了 loop_disposition="continue_build" 当

guided_flow_state.missing_roles 仍然非空，继续当前角色切片；服务器有意将引导步骤保持在适当的位置即使比较结果本身已经产生，也要进入下一阶段没有可操作的纠正提示

router_set_goal(..., gate_proposal={...}) 可以接受可选型号-或

参考导出主动引导目标的门建议。服务器将其标准化为 active_gate_plan，开始每个门 pending，以及回报 gate_intake_result.policy_warnings 对于删除的隐藏工具名称，不支持的门类型，原始Blender/Python指令，不可用，需要目标时间摄入表面上的参考/感知证据，或客户提供的完工索赔，如 passed.

router_get_status(...), router_set_goal(...)，并上演

引用比较/迭代有效载荷可以公开 active_gate_planLLM reference_understanding、轮廓、分割、分类和VLM 检查点源可以提出或支持门，但场景/空间/网格和断言证据仍然是通过/失败状态的真相权威。

分阶段参考比较/迭代有效载荷还可以预测主动门计划

进入顶级 gate_statuses, completion_blockers, next_gate_actions，以及 recommended_bounded_tools，因此客户不需要从嵌套的平面形状推断出即时修复路径。

scene_relation_graph(...) 更新第一个确定性门切片

required_part, attachment_seam, support_contact，以及 symmetry_pair 有权威证据参考文献、状态原因、完成障碍，以及有界修复工具提示；后来引导的场景突变标记了受影响的人验证器支持的状态 stale 通过现有的空间污染路径。

主动门阻断器将引导视线/搜索范围缩小到现有区域

验证器和维修工具；一个失败的接缝闸门应该导致以下关系图形/测量/断言/宏修复工具，而不是广泛的目录或目标重置。

未解决的 completion_blockers 关于分阶段迭代响应，现在也推

loop_disposition="inspect_validate" 即使比较循环没有重复同样的视力只矫正焦点。

如果分阶段比较降级，但强确定性真理发现仍然存在

存在，使用相同的检查/测量/断言切换，而不是即兴创作另一个大型自由形式校正

错误阶段迭代切换到 inspect_validate 或

finish_or_stop 返回前也重新应用引导能见度

对于分阶段比较/迭代， goal_override 不再是会话

替代；改为使用主动引导式目标会话

对于集合或多对象分段捕捉，捕捉焦点现在落下

当没有明确的目标时，返回到组装好的目标范围的主要目标 target_object 已供应

确定性轮廓度量更倾向于目标/焦点捕捉

请求 target_view，而不是广义 context_wide 捕捉

reference_compare_current_view(..., persist_view=True, view_name=..., orbit_horizontal=..., zoom_factor=...) 保留捕获的用户视图，并执行以下操作

在紧凑视图期间，不要再次回放这些相同的视图调整诊断

会话诊断

引导/运行时有效负载现在公开了显式的MCP会话元数据：

router_set_goal(...) 包括 session_id 和 transport
router_get_status(...) 包括 session_id 和 transport
reference_compare_stage_checkpoint(...) 包括 session_id 和 transport
reference_iterate_stage_checkpoint(...) 包括 session_id 和 transport

当前运行时指南：

有状态的 streamable HTTP是长时间引导的推荐传输方式

运行和调试会话感知的引用/检查点流

最近的引导会话强化删除了已知的路由器记账路径

这可能会在路由工具期间破坏活动目标/参考会话状态执行

如果你调查未来的州损失事件，请进行比较 session_id 和

transport 首先要区分： - 传输/会话重新连接 - 应用程序级目标重置 - 正常的指导性准备障碍，如缺少目标或参考

服务器端采样助手基线

MCP服务器现在在活动请求中有一个有界的分析辅助层。

当前用例：

可选的 assistant_summary 在检查繁重的路径上，例如 scene_snapshot_state, scene_compare_snapshot, scene_get_hierarchy, scene_get_bounding_box，以及 scene_get_origin_info
有界的 repair_suggestion 上 router_set_goal, router_get_status，以及 workflow_catalog

显式辅助终端状态：

success
unavailable
masked_error
rejected_by_policy

规则很严格：助手可以帮助总结或建议，但他们不会覆盖场景真相或路由器策略。

版本化表面基线

公共表面演变明确地进行了版本控制：

表面轮廓	默认接触线
`legacy-manual`	`legacy-v1`
`legacy-flat`	`legacy-v1`
`llm-guided`	`llm-guided-v2`

兼容性说明：

llm-guided-v1 仍然可以选择作为回滚线
workflow_catalog, scene_context，以及 scene_inspect 参与引导式表面演化故事

代码模式决策

当前基准基线：

legacy-flat
llm-guided
code-mode-pilot

当前决定：

决定：保持 code-mode-pilot 作为实验性只读表面
不要将代码模式设置为写入繁重或破坏几何图形的Blender工作的默认路径

支持矩阵

搅拌机：已测试 搅拌机5.0 在E2E覆盖范围内；剩余插件最小值 搅拌机4.0+ 尽最大努力。
python: 3.11+
FastMCP任务运行时: fastmcp 3.2.4 + pydocket 0.19.x
代码模式沙箱额外: 毕丹蒂蒙蒂0.0.11
操作系统：macOS/Windows/Linux
记忆：路由器语义特征依赖于本地LaBSE模型和相关的向量基础设施

快速开始

1.安装Blender插件

下载 blender_ai_mcp.zip 从发布页面或者在本地构建 python scripts/build_addon.py.
打开Blender->编辑->首选项->附加组件。
点击 安装。.. 并选择zip文件。
启用插件。它在端口上启动本地Blender RPC服务器 8765.

2.在引导的配置文件上运行MCP服务器

推荐默认值：

ROUTER_ENABLED=true
MCP_SURFACE_PROFILE=llm-guided
地图 /tmp 如果您想要主机可见的图像/文件输出

Docker命令示例：

docker run -i --rm \
  -v /tmp:/tmp \
  -e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
  -e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
  -e ROUTER_ENABLED=true \
  -e MCP_SURFACE_PROFILE=llm-guided \
  -e BLENDER_RPC_HOST=host.docker.internal \
  ghcr.io/patrykiti/blender-ai-mcp:latest

docker run --rm \
  -p 8000:8000 \
  -v /tmp:/tmp \
  -e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
  -e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
  -e ROUTER_ENABLED=true \
  -e MCP_SURFACE_PROFILE=llm-guided \
  -e MCP_TRANSPORT_MODE=streamable \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=8000 \
  -e MCP_STREAMABLE_HTTP_PATH=/mcp \
  -e MCP_PROMPTS_AS_TOOLS_ENABLED=false \
  -e BLENDER_RPC_HOST=host.docker.internal \
  ghcr.io/patrykiti/blender-ai-mcp:latest

通用MCP客户端配置示例：

{
  "mcpServers": {
    "blender-ai-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/tmp:/tmp",
        "-e", "BLENDER_AI_TMP_INTERNAL_DIR=/tmp",
        "-e", "BLENDER_AI_TMP_EXTERNAL_DIR=/tmp",
        "-e", "ROUTER_ENABLED=true",
        "-e", "MCP_SURFACE_PROFILE=llm-guided",
        "-e", "BLENDER_RPC_HOST=host.docker.internal",
        "ghcr.io/patrykiti/blender-ai-mcp:latest"
      ]
    }
  }
}

网络注释：

macOS/Windows： 使用 host.docker.internal
Linux： 更喜欢 --network host 和 BLENDER_RPC_HOST=127.0.0.1
MCP_TRANSPORT_MODE=stdio 保持当前子进程/stdio MCP模式
MCP_TRANSPORT_MODE=streamable 启动有状态的流式HTTP MCP服务器
MCP_PROMPTS_AS_TOOLS_ENABLED=false 禁用与工具兼容的提示桥

为迅速有能力的客户；本地MCP提示仍然可用

对于更广泛的配置文件/配置示例，请使用：

MCP服务器文档
MCP客户端配置示例
.env.example 对于完整跟踪的运行时/config变量集

测试

单元测试：

PYTHONPATH=. poetry run pytest tests/unit/ -v

单位收款计数：

poetry run pytest tests/unit --collect-only

E2E测试：

python3 scripts/run_e2e_tests.py

E2E收集计数：

poetry run pytest tests/e2e --collect-only

预承诺：

poetry run pre-commit install --hook-type pre-commit --hook-type pre-push
poetry run pre-commit run --all-files

更多细节：

文档地图

贡献

阅读贡献.md 在打开PR之前。该仓库强制执行Clean Architecture边界、类型化Python、路由器元数据规则和预提交验证。

社区和支持

如果 blender-ai-mcp 在你的工作流程中很有用，考虑赞助它的长期发展。

赞助有助于为维护、文档、测试和更高级别的可靠性工作提供资金，这些工作使该仓库不同于原始Blender代码生成：目标优先的路由、精心策划的工具、确定性验证和生产成形的工作流支持。

成为赞助商

作者

帕特里克 Ciechanski

github：观察

许可证

该项目根据 Apache许可证2.0.

请参阅：

Blender AI MCP

快速接入

详细介绍