Blender Ai Mcp

When a bounded modeling intent matches, the default public working layer should be the macro layer:

- macro_cutout_recessfor recesses, openings, and cutter-driven cutouts
- macro_relative_layoutfor align/place/contact-gap part layout
- macro_attach_part_to_surfacefor seating one part onto another object's surface/body
- macro_align_part_with_contactfor minimal repair nudges on pairs that almost fit
- macro_place_symmetry_pairfor mirrored pair placement/correction around an explicit mirror plane
- macro_place_supported_pairfor mirrored pair placement/correction against one shared support surface
- macro_cleanup_part_intersectionsfor bounded pairwise overlap cleanup without free-form collision solving
- macro_adjust_relative_proportionfor bounded ratio repair between related objects
- macro_adjust_segment_chain_arcfor bounded arc adjustment on ordered segment chains
- macro_finish_formfor preset-driven bevel/subdivision/solidify finishing
- reference_imagesfor goal-scoped reference intake before bounded visual comparison
- reference_guided_creature_buildas a native prompt asset for staged generic creature work onllm-guided
- recommended_promptscan now steer creature-oriented guided sessions toward that prompt path by using active goal/session context
- guided_reference_readinessonrouter_set_goal,router_get_status, and staged reference compare/iterate payloads so clients can see whether reference-driven stage work is actually ready
- reference_compare_stage_checkpointfor deterministic multi-view stage comparison against attached references during manual iterative work
- reference_iterate_stage_checkpointfor a session-aware staged correction loop that remembers prior focus, can escalate into inspect/validate when the same correction repeats, and can now target one object, many objects, a collection, or the full assembled silhouette
- stage compare/iterate now also expose deterministicsilhouette_analysismetrics, typedaction_hints, and an advisory-onlypart_segmentationplaceholder that stays disabled unless a separate sidecar is explicitly enabled
- scene_scope_graphfor one explicit read-only structural scope artifact with anchor/core/accessory role hints
- scene_relation_graphfor one explicit read-only pair-relation artifact derived from the current truth layer
- scene_view_diagnosticsfor one explicit read-only view-space artifact with projected extent, frame coverage, centering, and visible/partial/occluded/off-frame verdicts for named cameras orUSER_PERSPECTIVE
- those spatial graph/view diagnostics tools are now part of the default visiblellm-guidedsupport set so the model can keep one explicit 3D orientation layer available instead of inferring spatial state only from names, screenshots, or partial loop payloads

- router_set_goal
- router_get_status
- browse_workflows
- reference_images
- scene_scope_graph
- scene_relation_graph
- scene_view_diagnostics
- search_tools
- call_tool
- optional prompt bridge tools whenMCP_PROMPTS_AS_TOOLS_ENABLED=true:

- list_prompts
- get_prompt

Prompt-capable clients should prefer native MCP prompts. The prompt bridge is a compatibility layer for tool-only clients and can be disabled for Streamable HTTP profiles that already consume native prompt components.

- bootstrap/planning search can now reach:

- scene_get_viewport
- scene_clean_scene

- the guided profile starts from a compact visible bootstrap set instead of the full catalog
- grouped/public tools stay easy to discover
- hidden atomic tools remain available as infrastructure, not as the default public mental model
- specialist families stay out of the normal guided entry layer until the macro surface is broader

The rootREADME.mdis intentionallynotthe full tool catalog anymore.

The detailed tool inventory and atomic family docs should stay in docs, not on the front page. That is the right long-term structure afterTASK-113.

Use these docs depending on what you need:

- Canonical policy foratomic / macro / workflow, hidden atomic tools, goal-first usage, and vision/assert boundaries.

- Surface profiles, guided aliases, versioned contracts, and runtime/platform guidance.

- Ready-to-paste local MCP client config examples for guided/manual surfaces plus MLX, OpenRouter, and Gemini vision variants.

- Runtime/backends, capture bundles, reference images, macro/workflow vision integration notes, and repo-tracked real viewport eval bundles for both direct user-view and fixed camera-perspective captures.

- Strategy doc for a typed spatial-intelligence layer, compact relation state, and bounded next-step handoffs for guided operation.

- External research handoff for LLM/VLM spatial reasoning, multi-view reasoning, and geometry-aware planning.

- Research-driven upgrade proposal for scene graphs, symbolic relation notation, and supporting geometry-library choices.

- Full inventory and grouped/public tool overview.

- Maintainer-facing map of the tool families underneath the MCP surface.

If you want to see the atomic families the server is built on, start here:

- keep/_docs/TOOLS/as the maintainer-facing atomic/grouped architecture map
- keepREADME.mdproduct-facing and compact
- keep/_docs/AVAILABLE_TOOLS_SUMMARY.mdas the runtime inventory

- Local default:mlx_localwith a Qwen VL 4B-class model path; current repo-validated baseline ismlx-community/Qwen3-VL-4B-Instruct-4bit
- External iterative compare candidate:OpenRouter withx-ai/grok-4.20-multi-agent
- External Google-family compare path:OpenRouter-hosted Google-family models plus Google AI Studio / Gemini now share the same narrow staged-compare contract through resolvedvision_contract_profilerouting

- VISION_EXTERNAL_PROVIDERselects the transport/provider branch
- VISION_EXTERNAL_CONTRACT_PROFILEoptionally overrides the prompt/schema/parser contract for external compare flows
- when the override is unset, the runtime auto-matches Google-family model ids such asgemma/gemini/learnlm, then falls back to provider defaults

- MCP server (server/): FastMCP surface, public tool definitions, transforms, discovery, and response contracts.
- Router (server/router/): goal interpretation, safety/correction policy, workflow matching, session context, and guided execution behavior.
- Blender addon (blender_addon/): actualbpyexecution, RPC handlers, and Blender main-thread-safe operation scheduling.

Communication happens through JSON-RPC over TCP sockets.

The server is moving critical surfaces toward machine-readable payloads instead of prose-heavy JSON strings.

Current structured-contract baseline includes:

- 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

That is important for automation, auditing, and future macro/workflow composition.

For contact-sensitive checks on curved or rounded forms, the truth layer now distinguishes:

- mesh-surface contact/gap semantics when a bounded mesh-aware path is available
- bbox fallback semantics when a mesh-aware path is not available

That means a pair can still show bbox contact while the main measured relation remainsseparatedif the real mesh surfaces still have a visible gap. Guided hybrid truth follow-up now carries that distinction forward in operator-facing summaries instead of collapsing it into a generic "contact passed/failed" claim.

When the mesh-aware path finds a real overlap, the main measured relation also staysoverlapping, so overlap rejection inscene_assert_contact(...)still works as a separate truth condition instead of collapsing into plain contact.

The guided surface supports missing-input handling as part of the product contract, not as an afterthought.

- Model-first clarificationis the default forrouter_set_goal(...)onllm-guided: missing workflow parameters return a typedneeds_inputpayload to the outer model first.
- Typed fallback payloadskeep the same flow usable on tool-only or compatibility clients.
- Human/native clarification is reserved for later/fallback policy rather than the default first step of workflow execution.
- router_set_goal(...)can ask for constrained choices, booleans, enums, or workflow confirmation.
- partial answerssurvive across follow-up turns.
- workflow_catalogimport conflicts reuse the same clarification model.

The guided surface now treats workflow fallback as an explicit typed contract instead of a phase side effect hidden in prose.

- router_set_goal(...)returnsguided_handoffon bounded continuation paths such ascontinuation_mode="guided_manual_build"andcontinuation_mode="guided_utility".
- guided_handoffnames thetarget_phase,direct_tools,supporting_tools, anddiscovery_toolsfor the next step onllm-guided.
- workflow_import_recommendedstaysFalseon these fallback paths unless the user explicitly asks for workflow import/create behavior.
- router_get_status(...)preserves the activeguided_handoffin session diagnostics so clients can recover the intended continuation path.

The guided surface now carries one explicit machine-readableguided_flow_statecontract in addition toguided_handoff.

- router_set_goal(...),router_get_status(...),reference_compare_stage_checkpoint(...), andreference_iterate_stage_checkpoint(...)can exposeguided_flow_statefor the activellm-guidedsession
- guided_flow_statereports:

- 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

Reference-driven staged work now has one explicit readiness contract instead of hidden ordering assumptions.

- router_set_goal(...)androuter_get_status(...)exposeguided_reference_readiness.
- the payload reportsattached_reference_count,pending_reference_count,compare_ready,iterate_ready, plus machine-readableblocking_reasonandnext_action
- reference_images(action="attach", source_path=...)can stay pending until the guided goal session is actually ready, then adopt automatically
- if the same goal already has active refs and new ones are staged duringneeds_input, the staged refs stay separate from the already-active goal references until readiness returns
- if a ready session still carries explicit pending refs for another goal,reference_images(action="list"| "remove"| "clear", ...)now treats that merged visible set consistently instead of leaving broken pending records
- reference_compare_stage_checkpoint(...)andreference_iterate_stage_checkpoint(...)now fail fast when the session is not ready, and echo the sameguided_reference_readinesspayload
- ifreference_iterate_stage_checkpoint(...)returnsloop_disposition="inspect_validate", stop free-form modeling and switch to inspect/measure/assert immediately
- if it returnsloop_disposition="continue_build"whileguided_flow_state.missing_rolesis still non-empty, continue the current role slice; the server intentionally keeps the guided step in place instead of advancing to the next stage, even when the compare result itself produced no actionable correction hints
- router_set_goal(..., gate_proposal={...})may accept an optional model- or reference-derived gate proposal for the active guided goal. The server normalizes it intoactive_gate_plan, starts every gate aspending, and returnsgate_intake_result.policy_warningsfor dropped hidden tool names, unsupported gate types, raw Blender/Python instructions, unavailable required reference/perception evidence on the goal-time intake surface, or client-supplied completion claims such aspassed.
- router_get_status(...),router_set_goal(...), and staged reference compare/iterate payloads can exposeactive_gate_plan; LLM,reference_understanding, silhouette, segmentation, classification, and VLM checkpoint sources may propose or support gates, but scene/spatial/mesh and assertion evidence remain the truth authority for pass/fail status.
- staged reference compare/iterate payloads also project the active gate plan into top-levelgate_statuses,completion_blockers,next_gate_actions, andrecommended_bounded_tools, so clients do not need to infer the immediate repair path from the nested plan shape.
- scene_relation_graph(...)updates the first deterministic gate slice forrequired_part,attachment_seam,support_contact, andsymmetry_pairwith authoritative evidence refs, status reasons, completion blockers, and bounded repair-tool hints; later guided scene mutations mark the affected verifier-backed statusesstalethrough the existing spatial dirtying path.
- active gate blockers narrow guided visibility/search toward existing verifier and repair tools; a failed seam gate should lead to relation graph/measure/assert/macro repair tools, not a broad catalog or goal reset.
- unresolvedcompletion_blockerson staged iterate responses now also pushloop_disposition="inspect_validate"even when the compare loop did not repeat the same vision-only correction focus.
- if staged compare degrades but strong deterministic truth findings still exist, use the same inspect/measure/assert handoff instead of improvising another large free-form correction
- error-stage iterate handoffs that move toinspect_validateorfinish_or_stopalso reapply guided visibility before returning
- for staged compare/iterate,goal_overrideis no longer a session substitute; use an active guided goal session instead
- for collection or multi-object staged captures, the capture focus now falls back to the assembled target scope's primary target when no explicittarget_objectis supplied
- deterministic silhouette metrics prefer the target/focus capture for the requestedtarget_view, not the broadcontext_widecapture
- reference_compare_current_view(..., persist_view=True, view_name=..., orbit_horizontal=..., zoom_factor=...)keeps the captured user view and does not replay those same view adjustments a second time during compact view diagnostics

Guided/runtime payloads now expose explicit MCP session metadata:

- router_set_goal(...)includessession_idandtransport
- router_get_status(...)includessession_idandtransport
- reference_compare_stage_checkpoint(...)includessession_idandtransport
- reference_iterate_stage_checkpoint(...)includessession_idandtransport

- statefulstreamableHTTP is the recommended transport for longer guided runs and for debugging session-aware reference / checkpoint flows
- recent guided-session hardening removed the known router bookkeeping path that could clobber active goal/reference session state during routed tool execution
- if you investigate a future state-loss incident, comparesession_idandtransportfirst to distinguish:

- transport/session reconnects
- application-level goal resets
- normal guided readiness blockers such as missing goal or references

Server-Side Sampling Assistants Baseline

The MCP server now has a bounded analytical assistant layer inside an active request.

- optionalassistant_summaryon inspection-heavy paths such asscene_snapshot_state,scene_compare_snapshot,scene_get_hierarchy,scene_get_bounding_box, andscene_get_origin_info
- boundedrepair_suggestiononrouter_set_goal,router_get_status, andworkflow_catalog

- success
- unavailable
- masked_error
- rejected_by_policy

The rule is strict: assistants may help summarize or suggest, but they do not override scene truth or router policy.

Public surface evolution is versioned explicitly:

- llm-guided-v1remains selectable as a rollback line
- workflow_catalog,scene_context, andscene_inspectparticipate in the guided surface evolution story

- Go decision: keepcode-mode-pilotas an experimental read-only surface
- Do not make Code Mode the default path for write-heavy or geometry-destructive Blender work

2. Run the MCP server on the guided profile

- ROUTER_ENABLED=true
- MCP_SURFACE_PROFILE=llm-guided
- map/tmpif you want host-visible image/file outputs

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

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

poetry run pytest tests/unit --collect-only

poetry run pytest tests/e2e --collect-only