Blender AI MCP

blender-ai-mcp

Un servidor MCP con forma de producción para Blender.

blender-ai-mcp permite que Claude, ChatGPT, Codex y otros clientes MCP controlen Blender a través de una API de herramientas estable en lugar de generación ad-hoc de Python. El resultado es una superficie más segura, más pequeña y más fiable para trabajo de modelado real: enrutamiento orientado a objetivos, herramientas públicas seleccionadas, inspección determinista y verificación que no depende de suposiciones.

Por Qué Existe Esto

La mayoría de las configuraciones de "IA + Blender" todavía piden al modelo que escriba scripts bpy en bruto. Eso se rompe exactamente donde el trabajo de producción se pone interesante:

1. Las APIs de Blender cambian entre versiones.
2. Los operadores sensibles al contexto fallan cuando el objeto activo, el modo o la selección son incorrectos.
3. Los scripts en bruto dan una retroalimentación débil cuando algo sale mal.
4. La visión puede describir un resultado, pero no se puede confiar en ella como autoridad final.

blender-ai-mcp adopta el enfoque opuesto: tratar el control de Blender como una superficie de producto, no como una proeza de generación de código.

Por Qué Este Servidor MCP en Lugar de Python en Bruto

• Contratos estables sobre síntesis de scripts. El modelo llama a herramientas con parámetros validados en lugar de improvisar código de Blender.
• Orquestación orientada a objetivos. Las sesiones guiadas normales comienzan desde router_set_goal(...), para que el sistema sepa qué está intentando construir el modelo antes de empezar a llamar a acciones de bajo nivel.
• Superficie pública pequeña. El perfil llm-guided predeterminado expone una capa de arranque diminuta y orientada a la búsqueda en lugar de inundar al modelo con todo el inventario del runtime.
• Verificación basada en la verdad. Las herramientas de inspección, medición y aserción determinan qué es realmente cierto en Blender.
• Límites de ejecución seguros. El addon de Blender ejecuta operaciones en el hilo principal de Blender mientras el servidor MCP maneja el enrutamiento, la validación, el descubrimiento y las respuestas estructuradas.

El Enfoque de Producto

La idea de negocio formalizada en TASK-113 es simple:

• Las herramientas atómicas son el sustrato de implementación. Se mantienen pequeñas, precisas y mayormente ocultas de la superficie pública normal.
• Las herramientas macro son la capa preferida orientada a LLM para trabajo significativo del tamaño de una tarea.
• Las herramientas de flujo de trabajo son herramientas de proceso de múltiples pasos acotadas con informes explícitos, no endpoints abiertos de "haz lo que sea".
• La orquestación orientada a objetivos mantiene las sesiones ancladas a una intención activa en lugar de hacer que el modelo redescubra el contexto en cada turno.
• La visión asiste en la interpretación, mientras que la medición determinista y las aserciones proporcionan la capa de verdad final.
• Los runtimes de visión conectables ahora cubren MLX local más rutas externas de OpenRouter y Google AI Studio / Gemini, con perfiles de contrato externos específicos por familia de modelos para el comportamiento de prompt/esquema/parser.

Esto es lo que convierte el proyecto de "herramientas de Blender expuestas a través de MCP" en un producto de control de IA utilizable para pipelines de modelado.

Superficie Pública Guiada por LLM

llm-guided es la superficie predeterminada orientada a producción. Es intencionalmente pequeña, orientada a la búsqueda y diseñada alrededor de sesiones conscientes de objetivos.

Flujo guiado normal:

1. router_set_goal(...)
2. browse_workflows, search_tools o call_tool
3. usar herramientas agrupadas/públicas como check_scene, inspect_scene o configure_scene
4. verificar con inspección más scene_measure_* y scene_assert_*

Regla de prompting:

• usar los recursos de la biblioteca de prompts en _docs/_PROMPTS/README.md como las instrucciones operativas guiadas canónicas
• cuando un cliente se desvía, anteponer guided_session_start como estabilizador genérico orientado a la búsqueda
• si una herramienta no está ya directamente visible en la superficie/fase actual, usar search_tools(...) antes de call_tool(...)

Cuando una intención de modelado acotada coincide, la capa de trabajo pública predeterminada debería ser la capa macro:

• macro_cutout_recess para huecos, aberturas y recortes impulsados por cortadores
• macro_relative_layout para disposición de piezas con alineación/colocación/hueco de contacto
• macro_attach_part_to_surface para asentar una pieza sobre la superficie/cuerpo de otro objeto
• macro_align_part_with_contact para ajustes de reparación mínimos en pares que casi encajan
• macro_place_symmetry_pair para colocación/corrección de pares reflejados alrededor de un plano de espejo explícito
• macro_place_supported_pair para colocación/corrección de pares reflejados contra una superficie de soporte compartida
• macro_cleanup_part_intersections para limpieza acotada de solapamientos por pares sin resolución de colisiones de forma libre
• macro_adjust_relative_proportion para reparación acotada de proporciones entre objetos relacionados
• macro_adjust_segment_chain_arc para ajuste acotado de arcos en cadenas de segmentos ordenados
• macro_finish_form para acabado con bisel/subdivisión/solidificar impulsado por ajustes preestablecidos
• reference_images para ingesta de referencias con alcance de objetivo antes de comparación visual acotada
• reference_guided_creature_build como recurso de prompt nativo para trabajo genérico de criaturas por etapas en llm-guided
• recommended_prompts ahora puede dirigir sesiones guiadas orientadas a criaturas hacia esa ruta de prompt usando contexto activo de objetivo/sesión
• guided_reference_readiness en router_set_goal, router_get_status y payloads de comparación/iteración de referencias por etapas para que los clientes puedan ver si el trabajo por etapas impulsado por referencias está realmente listo
• reference_compare_stage_checkpoint para comparación determinista de etapas multi-vista contra referencias adjuntas durante trabajo iterativo manual
• reference_iterate_stage_checkpoint para un bucle de corrección por etapas consciente de la sesión que recuerda el enfoque previo, puede escalar a inspección/validación cuando la misma corrección se repite, y ahora puede apuntar a un objeto, muchos objetos, una colección o la silueta ensamblada completa
• la comparación/iteración de etapas ahora también expone métricas deterministas silhouette_analysis, action_hints tipados y un marcador de posición part_segmentation solo de asesoramiento que permanece deshabilitado a menos que se habilite explícitamente un sidecar separado
• scene_scope_graph para un artefacto estructural explícito de solo lectura con pistas de rol de ancla/núcleo/accesorio
• scene_relation_graph para un artefacto explícito de relación de pares de solo lectura derivado de la capa de verdad actual
• scene_view_diagnostics para un artefacto explícito de espacio de vista de solo lectura con extensión proyectada, cobertura de encuadre, centrado y veredictos visible/parcial/ocluido/fuera de encuadre para cámaras nombradas o USER_PERSPECTIVE
• esas herramientas de diagnóstico de grafo espacial/vista ahora forman parte del conjunto de soporte llm-guided visible predeterminado para que el modelo pueda mantener una capa explícita de orientación 3D disponible en lugar de inferir el estado espacial solo a partir de nombres, capturas de pantalla o payloads de bucle parciales

Superficie de arranque guiada actual:

• router_set_goal
• router_get_status
• browse_workflows
• reference_images
• scene_scope_graph
• scene_relation_graph
• scene_view_diagnostics
• search_tools
• call_tool
• herramientas de puente de prompt opcionales cuando MCP_PROMPTS_AS_TOOLS_ENABLED=true:
  • list_prompts
  • get_prompt

Los clientes capaces de prompts deberían preferir los prompts MCP nativos. El puente de prompts es una capa de compatibilidad para clientes solo de herramientas y se puede deshabilitar para perfiles Streamable HTTP que ya consumen componentes de prompt nativos.

Ruta de preparación de utilidades guiadas actual:

• la búsqueda de arranque/planificación ahora puede alcanzar:
  • scene_get_viewport
  • scene_clean_scene
• estas acciones de utilidad permanecen acotadas y no reabren la superficie heredada completa
• el envoltorio canónico de descubrimiento guiado es call_tool(name=..., arguments=...)
• la forma canónica del argumento de limpieza en llm-guided es keep_lights_and_cameras; los flags divididos antiguos son solo de compatibilidad y no deberían usarse como la forma pública documentada
• reference_images(action="attach", source_path=...) es una referencia por llamada; las formas tipo lote ahora fallan con guía de recuperación guiada en lugar de ruido de esquema en bruto
• collection_manage(action=..., collection_name=...) sigue siendo la forma pública canónica; el name heredado es solo un alias de compatibilidad estrecho
• modeling_create_primitive(...) sigue limitado a primitive_type, radius/size, location, rotation y name opcional; los atajos no soportados como scale, segments, rings, subdivisions o collection_name en tiempo primitivo ahora fallan con guía accionable tanto en rutas guiadas directas como proxy
• los objetivos de construcción deberían seguir comenzando desde router_set_goal(...), pero las solicitudes de captura de pantalla / viewport / restablecimiento de escena deberían usar la ruta de utilidades guiadas en su lugar
• si el estado de escena obsoleto se descubre solo después de entrar en la superficie de construcción guiada, scene_clean_scene(...) también está disponible allí como una vía de recuperación acotada; la limpieza antes del objetivo sigue siendo la ruta preferida
• la limpieza en fase de construcción todavía está permitida cuando se necesita recuperación

Alias públicos actuales en llm-guided:

Herramienta interna	Nombre público llm-guided	Cambios de argumentos públicos
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

Por qué importa:

• el perfil guiado comienza desde un conjunto de arranque visible compacto en lugar del catálogo completo
• las herramientas agrupadas/públicas siguen siendo fáciles de descubrir
• las herramientas atómicas ocultas permanecen disponibles como infraestructura, no como el modelo mental público predeterminado
• las familias especializadas se mantienen fuera de la capa de entrada guiada normal hasta que la superficie macro sea más amplia

Fundamentos Atómicos y Documentación

El README.md raíz intencionalmente ya no es el catálogo completo de herramientas.

El inventario detallado de herramientas y la documentación de familias atómicas deberían permanecer en docs, no en la portada. Esa es la estructura correcta a largo plazo después de TASK-113.

Usa estos docs según lo que necesites:

• Política de Capas de Herramientas
  • Política canónica para atomic / macro / workflow, herramientas atómicas ocultas, uso orientado a objetivos y límites de visión/aserción.
• Documentación del Servidor MCP
  • Perfiles de superficie, alias guiados, contratos versionados y guía de runtime/plataforma.
• Ejemplos de Configuración de Cliente MCP
  • Ejemplos de configuración de cliente MCP local listos para pegar para superficies guiadas/manuales más variantes de visión MLX, OpenRouter y Gemini.
• Documentación de la Capa de Visión
  • Runtimes/backends, paquetes de captura, imágenes de referencia, notas de integración de visión macro/flujo de trabajo y paquetes de evaluación de viewport reales rastreados en el repositorio tanto para vista de usuario directa como para capturas de perspectiva de cámara fija.
• Guía LLM v2
  • Documento de estrategia para una capa de inteligencia espacial tipada, estado de relaciones compacto y traspasos de siguiente paso acotados para operación guiada.
• Informe Breve de Investigación de Inteligencia Espacial
  • Traspaso de investigación externa para razonamiento espacial LLM/VLM, razonamiento multi-vista y planificación consciente de geometría.
• Propuesta de Mejora de Inteligencia Espacial
  • Propuesta de mejora impulsada por investigación para grafos de escena, notación de relaciones simbólicas y opciones de bibliotecas de geometría de soporte.
• Resumen de Herramientas Disponibles
  • Inventario completo y visión general de herramientas agrupadas/públicas.
• Índice de Arquitectura de Herramientas
  • Mapa orientado a mantenedores de las familias de herramientas debajo de la superficie MCP.

Si quieres ver las familias atómicas sobre las que está construido el servidor, empieza aquí:

• Arquitectura de Herramientas de Escena
• Arquitectura de Herramientas de Modelado
• Arquitectura de Herramientas de Malla
• Arquitectura de Herramientas Mega

Interpretación recomendada:

• mantener /_docs/TOOLS/ como el mapa de arquitectura atómica/agrupada orientado a mantenedores
• mantener README.md orientado al producto y compacto
• mantener /_docs/AVAILABLE_TOOLS_SUMMARY.md como el inventario del runtime

Notas del Proveedor

Versión corta actual:

• Valor predeterminado local: mlx_local con una ruta de modelo de clase Qwen VL 4B; la línea base validada actual del repositorio es mlx-community/Qwen3-VL-4B-Instruct-4bit
• Candidato de comparación iterativa externa: OpenRouter con x-ai/grok-4.20-multi-agent
• Ruta de comparación externa de la familia Google: Los modelos de la familia Google alojados en OpenRouter, junto con Google AI Studio / Gemini, ahora comparten el mismo contrato de comparación por etapas restringido a través del enrutamiento resuelto de vision_contract_profile

Nota sobre el runtime de visión externa:

• VISION_EXTERNAL_PROVIDER selecciona la rama de transporte/proveedor
• VISION_EXTERNAL_CONTRACT_PROFILE opcionalmente anula el contrato de prompt/esquema/parser para flujos de comparación externa
• cuando la anulación no está definida, el runtime empareja automáticamente IDs de modelos de la familia Google como gemma / gemini / learnlm, y luego recurre a los valores predeterminados del proveedor

Tabla detallada por proveedor:

• Documentación de la capa de visión -> Notas del proveedor

Arquitectura

El sistema está dividido a propósito:

• Servidor MCP (server/): Superficie FastMCP, definiciones de herramientas públicas, transformaciones, descubrimiento y contratos de respuesta.
• Enrutador (server/router/): interpretación de objetivos, política de seguridad/corrección, coincidencia de flujos de trabajo, contexto de sesión y comportamiento de ejecución guiada.
• Complemento de Blender (blender_addon/): ejecución real de bpy, manejadores RPC y programación de operaciones seguras para el hilo principal de Blender.

La comunicación ocurre mediante JSON-RPC sobre sockets TCP.

Más detalles:

• ARCHITECTURE.md
• Documentación del enrutador
• Límites de responsabilidad del runtime
• Documentación del complemento

Línea base del contrato estructurado

El servidor está moviendo superficies críticas hacia cargas útiles legibles por máquina en lugar de cadenas JSON con mucho texto.

La línea base actual del contrato estructurado incluye:

• 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

Eso es importante para la automatización, la auditoría y la futura composición de macros/flujos de trabajo.

Semántica de la verdad de contacto

Para verificaciones sensibles al contacto en formas curvas o redondeadas, la capa de verdad ahora distingue:

• semántica de contacto/separación de superficie de malla cuando hay una ruta acotada con conocimiento de malla disponible
• semántica de respaldo de bbox cuando una ruta con conocimiento de malla no está disponible

Eso significa que un par puede mostrar contacto de bbox mientras la relación medida principal permanece como separated si las superficies de malla reales aún tienen una separación visible. El seguimiento guiado de verdad híbrida ahora lleva esa distinción en los resúmenes orientados al operador en lugar de colapsarla en una afirmación genérica de "contacto aprobado/fallido".

Cuando la ruta con conocimiento de malla encuentra una superposición real, la relación medida principal también permanece como overlapping, por lo que el rechazo por superposición en scene_assert_contact(...) aún funciona como una condición de verdad separada en lugar de colapsar en contacto simple.

Flujo de aclaración estructurado

La superficie guiada admite el manejo de entradas faltantes como parte del contrato del producto, no como una ocurrencia tardía.

• La aclaración primero con el modelo es el valor predeterminado para router_set_goal(...) en llm-guided: los parámetros de flujo de trabajo faltantes devuelven una carga útil tipada de needs_input al modelo externo primero.
• Cargas útiles de respaldo tipadas mantienen el mismo flujo utilizable en clientes solo de herramientas o de compatibilidad.
• La aclaración humana/nativa está reservada para políticas posteriores/de respaldo en lugar del primer paso predeterminado de la ejecución del flujo de trabajo.
• router_set_goal(...) puede solicitar opciones restringidas, booleanos, enumeraciones o confirmación del flujo de trabajo.
• partial answers sobreviven entre turnos de seguimiento.
• Los conflictos de importación de workflow_catalog reutilizan el mismo modelo de aclaración.

Contrato de transferencia guiada

La superficie guiada ahora trata el respaldo del flujo de trabajo como un contrato tipado explícito en lugar de un efecto secundario de fase oculto en texto.

• router_set_goal(...) devuelve guided_handoff en rutas de continuación acotadas como continuation_mode="guided_manual_build" y continuation_mode="guided_utility".
• guided_handoff nombra el target_phase, direct_tools, supporting_tools y discovery_tools para el siguiente paso en llm-guided.
• workflow_import_recommended permanece como False en estas rutas de respaldo a menos que el usuario solicite explícitamente el comportamiento de importación/creación del flujo de trabajo.
• router_get_status(...) preserva el guided_handoff activo en los diagnósticos de sesión para que los clientes puedan recuperar la ruta de continuación prevista.

Estado del flujo guiado controlado por el servidor

La superficie guiada ahora lleva un contrato explícito legible por máquina de guided_flow_state además de guided_handoff.

• router_set_goal(...), router_get_status(...), reference_compare_stage_checkpoint(...) y reference_iterate_stage_checkpoint(...) pueden exponer guided_flow_state para la sesión activa de llm-guided
• guided_flow_state informa:
  • 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
• las superposiciones de dominio actuales son:
  • generic
  • creature
  • building
• las sesiones tempranas de construcción guiada ahora comienzan desde una fase de contexto espacial escalonada por pasos en lugar de exponer toda la superficie de construcción de inmediato
• scene_scope_graph(...) vincula el alcance objetivo guiado activo cuando no existe ningún alcance activo todavía; las comprobaciones de actualización espacial deben seguir usando ese alcance objetivo ya vinculado en lugar de re-vincular a un conjunto de objetos diferente
• las comprobaciones de vista no relacionadas, como scene_view_diagnostics(target_object="Camera", ...), no satisfacen por sí solas una comprobación espacial de criatura/edificio
• si hay imágenes de referencia adjuntas para el objetivo guiado activo, trátalas como la entrada de fundamentación principal antes de decidir las primeras masas de cuerpo/cabeza/cola y el silueta aproximada
• usa nombres de objetos semánticos completos como Body, Head, Tail, ForeLeg_L y HindLeg_R en lugar de abreviaturas opacas como ForeL / HindR, porque las heurísticas guiadas de costura/rol son más confiables con nombres legibles
• en llm-guided, el servidor ahora puede advertir sobre nombres débiles sensibles al rol y bloquear nombres de marcador claramente opacos como Sphere / Object cuando se usan como nombres de partes semánticas
• no llames a scene_scope_graph(...), scene_relation_graph(...) o scene_view_diagnostics(...) sin un alcance explícito y asumas que eso significa "inspeccionar toda la escena"
• durante una compuerta espacial guiada activa o un re-armado de actualización espacial, los tres ayudantes espaciales deben tratarse como herramientas de alcance explícito, no como sondas de toda la escena
• esos ayudantes espaciales de solo lectura fijados siguen siendo invocables mientras estén visibles en llm-guided; el bloqueo de familia guiada no debe rechazar scene_scope_graph(...), scene_relation_graph(...) o scene_view_diagnostics(...) simplemente porque el allowed_families del paso de construcción actual omite spatial_context
• fuera de esa compuerta guiada, los constructores de gráficos de alcance/relación aún requieren un target_object, target_objects o collection_name explícito; una llamada desnuda ahora falla en lugar de devolver silenciosamente un alcance scene vacío
• los alcances de marcador predeterminados como un Cube estándar o la raíz genérica Collection ya no se tratan como vinculaciones significativas de objetivo/conjunto de trabajo guiado por sí solos
• pero para la decisión de arranque anterior de "¿esta escena ya no está vacía?", el Cube estándar de Blender más los ayudantes estándar de cámara/luz aún ingresan a la ruta de arranque del conjunto de trabajo primario de escena vacía
• esta decisión de no vacío es intencionalmente ligera en nombres después del inicio: los bloqueos aproximados reales de múltiples objetos con nombres de primitivas predeterminados como Cube o Sphere aún cuentan como geometría existente, mientras que las escenas solo de ayudantes aún pueden ingresar a bootstrap_primary_workset
• los alcances guiados explícitos ahora se vinculan desde la intención del llamador en lugar de heurísticas de nombres, por lo que los objetos reales nombrados como Cube, Sphere o Sunflower aún pueden convertirse en el conjunto de trabajo guiado activo cuando el operador los apunta
• después de cambios de escena de material como scene_clean_scene(...), scene_duplicate_object(...), scene_rename_object(...), modeling_create_primitive(...), modeling_transform_object(...), modeling_join_objects(...), modeling_separate_object(...) o macros acotadas de adjunto/alineación, el runtime guiado puede marcar la capa espacial como obsoleta y re-armar las comprobaciones requeridas
• esa misma actualización de estado sucio ahora reaplica la visibilidad de FastMCP inmediatamente, por lo que los clientes ven las herramientas de soporte espacial requeridas tan pronto como spatial_refresh_required se persiste
• en Streamable HTTP, los finalizadores de estado sucio y visibilidad guiados deben completarse antes de que la respuesta de la herramienta activa regrese; las herramientas síncronas enrutadas que mutan el estado de la escena difieren esos finalizadores al envoltorio asíncrono de MCP en lugar de programar escrituras de estado de sesión separadas
• los envoltorios asíncronos y los ayudantes de modelado asíncronos nativos mantienen la ejecución de RPC/enrutador síncrono bloqueante en un hilo de trabajo; solo los finalizadores guiados se ejecutan de vuelta en el bucle de eventos antes de que la respuesta de Streamable HTTP se complete
• los ayudantes de macros sucias asíncronas como macro_cutout_recess(...) y macro_finish_form(...) usan la ruta de ruta asíncrona esperada para que la visibilidad se reaplique antes de que la respuesta de Streamable HTTP se complete
• los ayudantes espaciales asíncronos como scene_scope_graph(...), scene_relation_graph(...) y scene_view_diagnostics(...) enrutan sus lecturas de gráficos/diagnósticos respaldados por Blender fuera del bucle de eventos antes de registrar la finalización de la comprobación espacial guiada
• los finalizadores de identidad guiada asíncronos como la validación exitosa de scene_rename_object(...) también mantienen las búsquedas de escena respaldadas por Blender fuera del bucle de eventos antes de actualizar el registro de partes guiado
• las herramientas de modelado asíncronas nativas que consumen un informe de ejecución del enrutador aún deben mostrar advertencias de guided_naming a través del contexto MCP activo; de lo contrario, los nombres semánticos débiles pueden perder sus pistas de corrección orientadas al modelo en Streamable HTTP
• los finalizadores de modelado y limpieza asíncronos nativos derivan mutaciones de escena exitosas de report.steps estructurado, no del texto de ruta heredado renderizado; las rutas corregidas de múltiples pasos prefijan líneas heredadas y no son una fuente confiable para decisiones de estado sucio guiado o registro de roles
• el registro de roles guiado asíncrono reaplica la visibilidad de FastMCP después de que el guided_flow_state avanzado final se persiste, por lo que list_tools() refleja el nuevo paso guiado antes de que la respuesta de Streamable HTTP se complete
• las variantes de herramientas públicas asíncronas deben preservar los docstrings públicos originales, especialmente para ayudantes espaciales y de modelado guiados visibles cuyas descripciones enseñan argumentos de alcance requeridos, orden de flujo de trabajo y restricciones de argumentos
• cuando el enrutador corrige una llamada exitosa de modeling_transform_object(...) a otro nombre de objeto válido, el estado sucio espacial guiado y el seguimiento de roles guiado usan el nombre de objeto transformado devuelto por el paso de modelado final, no el nombre original proporcionado por el llamador
• las herramientas de edición de malla guiadas como mesh_extrude_region(...), mesh_loop_cut(...) y mesh_bevel(...) ahora se asignan a la familia secondary_parts, por lo que se bloquean durante las compuertas de contexto espacial y re-armar las comprobaciones espaciales después de ediciones de geometría exitosas
• cuando una de esas comprobaciones espaciales requeridas se completa y avanza el flujo guiado, el servidor ahora reaplica la visibilidad de FastMCP inmediatamente en lugar de esperar una actualización de estado/búsqueda posterior
• los pares de relación de soporte/simetría ahora preservan las anotaciones de soporte y simetría incluso cuando comparten la misma clave (from_object, to_object) que un par de objetivo primario genérico, por lo que los planificadores guiados posteriores aún ven semánticas de soporte/simetría en lugar de solo un borde genérico
• los gráficos de relación que incluyen costuras de criatura requeridas aún agregan pares de respaldo primary_to_other para objetos no de costura en el alcance solicitado, por lo que los objetos no clasificados no desaparecen de los diagnósticos guiados mixtos
• los pares de soporte/simetría saludables ya no cuentan como fallidos solo porque sus centros difieren o no son pares de contacto literales; solo los veredictos de soporte/simetría unsupported / asymmetric cuentan como fallas allí
• cuando guided_flow_state.spatial_refresh_required == true, trata next_actions=["refresh_spatial_context"] como estado de servidor autoritativo, no como prosa de asesoramiento; actualiza con scene_scope_graph(...) contra el alcance objetivo ya vinculado primero, luego vuelve a ejecutar las comprobaciones espaciales requeridas restantes en ese mismo alcance
• scene_view_diagnostics(...) solo cuenta para la compuerta espacial guiada cuando devuelve evidencia real de espacio de vista disponible; una sonda sin cabeza/no disponible permanece de solo lectura y no satisface la comprobación requerida por sí sola
• si la comparación/iteración de etapas encuentra problemas importantes mientras la porción de rol/conjunto de trabajo guiado actual aún está incompleta, el gobernador ahora puede mantener la sesión en continuación de construcción acotada en lugar de escalar demasiado temprano a inspect_validate
• cuando esa retención de etapa incompleta devuelve loop_disposition="continue_build", el guided_flow_state persistido permanece en el mismo paso actual y no marca la porción de rol incompleta como completada; sigue siguiendo missing_roles antes de confiar en la visibilidad de etapas posteriores
• esta retención de etapa incompleta también se aplica cuando la iteración de etapas no tiene correction_focus o action_hints; un resultado de comparación sin acción no debe avanzar una construcción guiada con roles faltantes requeridos a finish_or_stop
• después de que el flujo alcanza un paso posterior como place_secondary_parts, el servidor aún puede mantener las masas primarias faltantes disponibles cuando son parte del mismo conjunto de trabajo acotado, en lugar de forzar una ejecución de ardilla/edificio a abandonar una masa central incompleta inmediatamente
• para costuras de bloqueo de criatura, intersecting aún puede ser aceptable para la colocación de oreja/cabeza o hocico/cabeza incrustadas, pero floating_gap en cabeza/cuerpo, cola/cuerpo o extremidad/cuerpo sigue siendo accionable
• si una familia de herramientas necesaria está oculta/bloqueada por flujo, inspecciona router_get_status().guided_flow_state, completa los required_checks listados y sigue next_actions en lugar de adivinar nombres de herramientas ocultas en call_tool(...)
• si un objetivo guiado explícito permaneció en una ruta manual/sin coincidencia, un flujo de trabajo sugerido por patrón fuerte aún puede expandirse; lo que permanece suprimido en ese estado es la ruta de reapertura heurística de menor confianza
• las búsquedas de nombres de herramientas exactas en la superficie guiada ahora están formadas para devolver un conjunto de resultados más ajustado y más pequeño en lugar de inundar el modelo con una carga útil expandida completa para búsquedas simples
• para pasos de construcción sensibles al rol, trata allowed_roles y missing_roles como parte del contrato de ejecución, no como prosa de asesoramiento
• las operaciones de mantenimiento/conjunto de trabajo como collection_manage(...) deben permanecer disponibles para objetos ya creados incluso cuando su rol semántico se registró en un paso anterior
• el refinamiento acotado de un objeto primario ya registrado puede seguir siendo posible después de que la sesión avance al siguiente paso; los pasos posteriores no están destinados a congelar todas las masas anteriores por completo
• usa guided_register_part(object_name=..., role=...) como la forma canónica de decirle al servidor qué parte semántica representa un objeto; las sugerencias opcionales de guided_role=... en las herramientas de construcción son solo de conveniencia
• los valores opcionales de role_group=... deben coincidir con el mapa de roles de dominio del servidor; los llamadores no pueden reclasificar body_core, head_mass o llamadas mutantes similares sensibles al rol como utility u otra familia para eludir la compuerta de fase guiada actual
• guided_register_part(...) ahora valida que el objeto de Blender nombrado realmente exista antes de que pueda contar para la finalización de roles guiados; los errores tipográficos no crean roles completados por sí solos
• si la validación de objetos guiados no puede leer la escena de Blender en absoluto, guided_register_part(...) ahora falla claramente en lugar de mutar el estado de sesión guiado desde un nombre de objeto no verificado
• los nombres de objetivo explícitos pasados a scene_scope_graph(...) / rutas de construcción de alcance ahora siguen la misma regla de validación de verdad de Blender antes de que el alcance guiado pueda vincularse
• esas sugerencias opcionales de guided_role=... solo se auto-registran cuando ya existe un flujo guiado activo; fuera de un flujo guiado activo no crean estado de rol persistente por sí solos
• una llamada de creación fallida ahora permanece no mutante para el estado de rol guiado también: si modeling_create_primitive(...) devuelve una cadena de falla, el rol solicitado no se auto-registra solo porque se proporcionó un name semántico
• en modeling_create_primitive(...), guided_role=... ahora también requiere un name semántico explícito; la creación guiada no permite Blender auto-generado nombres que se convierten en registros de partes semánticas
• cuando el enrutador antepone pasos correctivos como scene_set_mode(...), las llamadas exitosas de creación/transformación guiadas aún registran el rol resultante contra el paso de modelado final en lugar de descartar el registro de conveniencia solo porque la llamada se volvió de varios pasos
• el registro de conveniencia de rol guiado ahora también maneja nombres de objeto válidos que contienen apóstrofes, como King's Crown, en lugar de truncar el nombre de objeto almacenado
• el análisis de éxito en tiempo de ejecución guiado también trata los apóstrofes dentro de nombres de objeto entre comillas como parte del nombre del objeto para los resultados de creación/transformación/renombrado/unión, de modo que el marcado de estado obsoleto y la sincronización del registro guiado aún se ejecutan después de mutaciones exitosas
• los nombres de pares canónicos como ForeLeg_L, ForeLeg_R y ForeLegPair ahora cuentan como nombres semánticos fuertes para foreleg_pair / hindleg_pair en lugar de advertir o bloquear bajo la política de nombres más estricta
• en modeling_create_primitive(...), el auto-registro de rol guiado ahora se vincula al nombre de objeto realmente creado devuelto por Blender, de modo que el estado del rol permanece alineado incluso cuando Blender auto-numera un nombre predeterminado como Cube.001 o usa un nombre de objeto predeterminado diferente como Suzanne
• en modeling_transform_object(...), el auto-registro de rol guiado ahora se vincula al nombre de objeto transformado real devuelto por el paso enrutado final, de modo que la identidad de objeto corregida por el enrutador aún rearma las comprobaciones espaciales y actualiza el estado del rol para el objeto que realmente cambió
• las llamadas exitosas de scene_rename_object(...) ahora mantienen el registro de partes guiado alineado con el objeto de Blender renombrado, de modo que las transformaciones sensibles al rol posteriores aún recuperan el rol registrado sin re-registro manual
• las llamadas exitosas de scene_rename_object(...) también rearman las comprobaciones espaciales guiadas, porque la huella de alcance objetivo vinculada se basa en el nombre
• las llamadas exitosas de scene_duplicate_object(...) también rearman las comprobaciones espaciales guiadas, porque la duplicación cambia los hechos visibles de relación entre conjunto de trabajo y alcance
• los resultados de mutación de cadena simple fallidos como Object 'Missing' not found ahora permanecen no mutantes para el estado de sesión guiado; no rearman comprobaciones espaciales ni reescriben el registro de rol guiado solo porque el envoltorio devolvió una cadena
• scene_clean_scene(...) ahora limpia el registro de partes guiado y devuelve el flujo guiado a bootstrap_primary_workset en lugar de arrastrar partes completadas hacia adelante en una escena vacía
• iniciar un objetivo guiado diferente en la misma sesión ahora restablece el registro de partes guiado para ese nuevo flujo en lugar de arrastrar roles completados desde el objeto anterior
• los cambios destructivos de identidad/topología como modeling_join_objects(...) o modeling_separate_object(...) ahora eliminan los registros de partes guiados obsoletos; vuelva a registrar explícitamente el/los objeto(s) resultante(s) si aún deben contar para la finalización del rol guiado
• esos mismos cambios destructivos de topología también rearman las comprobaciones espaciales guiadas, porque los hechos de alcance/vista capturados previamente ya no son confiables después de que los objetos se fusionaron o dividieron
• para artefactos de captura/visión de macros, macro_attach_part_to_surface(...) ahora actualiza su paquete de captura posterior a la acción después del empujón adicional de superficie de malla, de modo que las imágenes adjuntas y el resumen de verdad describen la pose final asentada en lugar de la pose intermedia previa al empujón
• los informes de macros enrutados pueden ser partial y aún llevar un error; los adaptadores MCP preservan ese informe estructurado, incluyendo actions_taken, objetos modificados, recomendaciones de verificación, datos de captura/verdad y orientación de seguimiento, en lugar de forzarlo a un sobre vacío de error
• si el sidecar de segmentación opcional está habilitado en la configuración de tiempo de ejecución pero aún no se ha ejecutado en la ruta de comparación actual, las respuestas de comparación/iteración por etapas ahora informan part_segmentation.status="unavailable" en lugar de permanecer silenciosamente en disabled
• si el servidor advierte o bloquea el nombre guiado, renombre o cree el objeto usando uno de los nombres semánticos sugeridos en lugar de reintentar la misma abreviatura débil
• el nombre guiado y la inferencia de rol espacial guiado ahora usan coincidencias de estilo de límite de token en lugar de coincidencias de subcadena crudas, de modo que nombres como Heart o TruthBodyAnchorHead no se conviertan en roles semánticos accidentales de oreja/cuerpo/cabeza
• los required prompt bundle y preferred prompt bundle nombrados en guided_flow_state son nombres de activos de prompt, no un reemplazo para el flujo impulsado por el servidor; los prompts apoyan el flujo, no se convierten en el flujo

Preparación de Referencias Guiadas

El trabajo por etapas guiado por referencias ahora tiene un contrato de preparación explícito en lugar de suposiciones de orden ocultas.

• router_set_goal(...) y router_get_status(...) exponen guided_reference_readiness.
• el payload reporta attached_reference_count, pending_reference_count, compare_ready, iterate_ready, además de blocking_reason y next_action legibles por máquina
• reference_images(action="attach", source_path=...) puede permanecer pendiente hasta que la sesión de objetivo guiado esté realmente lista, y luego adoptarse automáticamente
• si el mismo objetivo ya tiene referencias activas y se preparan nuevas durante needs_input, las referencias preparadas permanecen separadas de las referencias de objetivo ya activas hasta que la preparación regrese
• si una sesión lista aún tiene referencias pendientes explícitas para otro objetivo, reference_images(action="list"| "remove"| "clear", ...) ahora trata ese conjunto visible fusionado de manera consistente en lugar de dejar registros pendientes rotos
• reference_compare_stage_checkpoint(...) y reference_iterate_stage_checkpoint(...) ahora fallan rápidamente cuando la sesión no está lista, y devuelven el mismo payload guided_reference_readiness
• si reference_iterate_stage_checkpoint(...) devuelve loop_disposition="inspect_validate", detén el modelado de forma libre y cambia a inspect/measure/assert inmediatamente
• si devuelve loop_disposition="continue_build" mientras guided_flow_state.missing_roles aún no está vacío, continúa con el segmento de rol actual; el servidor mantiene intencionalmente el paso guiado en su lugar en lugar de avanzar a la siguiente etapa, incluso cuando el resultado de la comparación no produjo sugerencias de corrección accionables
• router_set_goal(..., gate_proposal={...}) puede aceptar una propuesta de compuerta opcional derivada del modelo o de referencias para el objetivo guiado activo. El servidor la normaliza en active_gate_plan, inicia cada compuerta como pending y devuelve gate_intake_result.policy_warnings para nombres de herramientas ocultas descartadas, tipos de compuerta no admitidos, instrucciones crudas de Blender/Python, evidencia de referencia/percepción requerida no disponible en la superficie de ingreso en el momento del objetivo, o afirmaciones de finalización proporcionadas por el cliente, como passed.
• router_get_status(...), router_set_goal(...) y los payloads de comparación/iteración de referencias preparadas pueden exponer active_gate_plan; las fuentes de puntos de control LLM, reference_understanding, silueta, segmentación, clasificación y VLM pueden proponer o respaldar compuertas, pero la evidencia de escena/espacial/malla y de afirmación sigue siendo la autoridad de verdad para el estado de aprobado/fallido.
• los payloads de comparación/iteración de referencias preparadas también proyectan el plan de compuertas activo en los niveles superiores gate_statuses, completion_blockers, next_gate_actions y recommended_bounded_tools, para que los clientes no necesiten inferir la ruta de reparación inmediata a partir de la forma anidada del plan.
• scene_relation_graph(...) actualiza el primer segmento de compuerta determinista para required_part, attachment_seam, support_contact y symmetry_pair con referencias de evidencia autorizadas, razones de estado, bloqueadores de finalización y sugerencias limitadas de herramientas de reparación; las mutaciones posteriores de la escena guiada marcan los estados respaldados por verificadores afectados como stale a través de la ruta de ensuciamiento espacial existente.
• los bloqueadores de compuertas activos reducen la visibilidad/búsqueda guiada hacia las herramientas de verificación y reparación existentes; una compuerta de costura fallida debería llevar a herramientas de reparación de relation graph/measure/assert/macro, no a un catálogo amplio o a un reinicio del objetivo.
• los completion_blockers no resueltos en las respuestas de iteración preparadas ahora también empujan loop_disposition="inspect_validate" incluso cuando el bucle de comparación no repitió el mismo enfoque de corrección solo visual.
• si la comparación preparada se degrada pero aún existen hallazgos de verdad deterministas sólidos, usa el mismo traspaso de inspect/measure/assert en lugar de improvisar otra corrección grande de forma libre
• los traspasos de iteración en etapa de error que se mueven a inspect_validate o finish_or_stop también reaplican la visibilidad guiada antes de regresar
• para comparación/iteración preparada, goal_override ya no es un sustituto de sesión; usa una sesión de objetivo guiado activa en su lugar
• para capturas preparadas de colección o de múltiples objetos, el enfoque de captura ahora recae en el objetivo principal del alcance de destino ensamblado cuando no se proporciona un target_object explícito
• las métricas de silueta deterministas prefieren la captura de objetivo/enfoque para el target_view solicitado, no la captura amplia de context_wide
• reference_compare_current_view(..., persist_view=True, view_name=..., orbit_horizontal=..., zoom_factor=...) mantiene la vista de usuario capturada y no reproduce esos mismos ajustes de vista una segunda vez durante los diagnósticos de vista compacta

Diagnósticos de Sesión

Los payloads guiados/de tiempo de ejecución ahora exponen metadatos explícitos de sesión MCP:

• router_set_goal(...) incluye session_id y transport
• router_get_status(...) incluye session_id y transport
• reference_compare_stage_checkpoint(...) incluye session_id y transport
• reference_iterate_stage_checkpoint(...) incluye session_id y transport

Guía actual del tiempo de ejecución:

• el HTTP stateful streamable es el transporte recomendado para ejecuciones guiadas más largas y para depurar flujos de referencia / punto de control conscientes de la sesión
• el reciente endurecimiento de la sesión guiada eliminó la ruta conocida de contabilidad del enrutador que podía sobrescribir el estado de la sesión de objetivo/referencia activa durante la ejecución de herramientas enrutadas
• si investigas un incidente futuro de pérdida de estado, compara primero session_id y transport para distinguir:
  • reconexiones de transporte/sesión
  • reinicios de objetivo a nivel de aplicación
  • bloqueadores normales de preparación guiada, como objetivo o referencias faltantes

Línea Base de Asistentes de Muestreo del Lado del Servidor

El servidor MCP ahora tiene una capa de asistente analítico acotada dentro de una solicitud activa.

Casos de uso actuales:

• assistant_summary opcional en rutas con mucha inspección, como scene_snapshot_state, scene_compare_snapshot, scene_get_hierarchy, scene_get_bounding_box y scene_get_origin_info
• repair_suggestion acotado en router_set_goal, router_get_status y workflow_catalog

Estados terminales explícitos del asistente:

• success
• unavailable
• masked_error
• rejected_by_policy

La regla es estricta: los asistentes pueden ayudar a resumir o sugerir, pero no anulan la verdad de la escena ni la política del enrutador.

Línea Base de Superficie Versionada

La evolución de la superficie pública está versionada explícitamente:

Perfil de superficie	Línea de contrato predeterminada
legacy-manual	legacy-v1
legacy-flat	legacy-v1
llm-guided	llm-guided-v2

Nota de compatibilidad:

• llm-guided-v1 sigue siendo seleccionable como línea de reversión
• workflow_catalog, scene_context y scene_inspect participan en la historia de evolución de superficie guiada

Decisión del Modo Código

Líneas base de benchmark actuales:

• legacy-flat
• llm-guided
• code-mode-pilot

Decisión actual:

• Decisión de Go: mantener code-mode-pilot como una superficie experimental de solo lectura
• No hacer del Modo Código la ruta predeterminada para trabajos de Blender con muchas escrituras o destructivos para la geometría

Matriz de Soporte

• Blender: probado en Blender 5.0 en la cobertura E2E; el mínimo del addon sigue siendo Blender 4.0+ sobre una base de mejor esfuerzo.
• Python: 3.11+
• Runtime de tareas FastMCP: fastmcp 3.2.4 + pydocket 0.19.x
• Extra de sandbox del Modo Código: pydantic-monty 0.0.11
• SO: macOS / Windows / Linux
• Memoria: las características semánticas del enrutador dependen de un modelo LaBSE local y de la infraestructura vectorial relacionada

Inicio Rápido

1. Instala el addon de Blender

1. Descarga blender_ai_mcp.zip desde la página de Releases o constrúyelo localmente con python scripts/build_addon.py.
2. Abre Blender -> Editar -> Preferencias -> Complementos.
3. Haz clic en Instalar... y selecciona el archivo zip.
4. Habilita el addon. Inicia el servidor RPC local de Blender en el puerto 8765.

2. Ejecuta el servidor MCP en el perfil guiado

Valores predeterminados recomendados:

• ROUTER_ENABLED=true
• MCP_SURFACE_PROFILE=llm-guided
• mapea /tmp si quieres salidas de imagen/archivo visibles para el host

Ejemplo de comando 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

Ejemplo de configuración genérica de cliente 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"
      ]
    }
  }
}

Notas de red:

• macOS / Windows: usa host.docker.internal
• Linux: prefiere --network host con BLENDER_RPC_HOST=127.0.0.1
• MCP_TRANSPORT_MODE=stdio mantiene el modo MCP actual de subproceso/stdio
• MCP_TRANSPORT_MODE=streamable inicia un servidor MCP HTTP Streamable con estado
• MCP_PROMPTS_AS_TOOLS_ENABLED=false desactiva el puente de prompts compatible con herramientas para clientes capaces de prompts; los prompts nativos de MCP siguen disponibles

Para ejemplos más amplios de perfil/configuración, usa:

• Documentación del servidor MCP
• Ejemplos de configuración de cliente MCP
• .env.example para el conjunto completo de variables de runtime/configuración rastreadas

Pruebas

Pruebas unitarias:

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

Recuento de colección de unidades:

poetry run pytest tests/unit --collect-only

Pruebas E2E:

python3 scripts/run_e2e_tests.py

Recuento de colección E2E:

poetry run pytest tests/e2e --collect-only

Pre-commit:

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

Más detalles:

• Documentación de pruebas
• Documentación de desarrollo

Mapa de Documentación

• Arquitectura
• Documentación del servidor MCP
• Documentación de la capa de visión
• Documentación del enrutador
• Límites de responsabilidad del enrutador
• Documentación del addon
• Guía LLM v2
• Resumen de investigación de inteligencia espacial
• Propuesta de actualización de inteligencia espacial
• Resumen de herramientas disponibles
• Índice de arquitectura de herramientas
• Prompts
• Tareas

Contribuciones

Lee CONTRIBUTING.md antes de abrir un PR. El repositorio aplica límites de Arquitectura Limpia, Python tipado, reglas de metadatos del enrutador y validación de pre-commit.

Comunidad y Soporte

Si blender-ai-mcp es útil en tu flujo de trabajo, considera patrocinar su desarrollo a largo plazo.

El patrocinio ayuda a financiar el mantenimiento, la documentación, las pruebas y el trabajo de confiabilidad de alto nivel que hace que este repositorio sea diferente de la generación de código de Blender en bruto: enrutamiento orientado a objetivos, herramientas seleccionadas, verificación determinista y soporte de flujos de trabajo con forma de producción.

Conviértete en patrocinador

• SUPPORT.md
• SECURITY.md
• CODE_OF_CONDUCT.md
• Patrocinadores de GitHub
• Cómprame un café

Autor

Patryk Ciechański

• GitHub: PatrykIti

Licencia

Este proyecto está licenciado bajo la Apache License 2.0.

Ver:

• LICENSE.md
• NOTICE