Blender AI MCP

Servidor MCP modular + Addon do Blender para Modelagem 3D orientada por IA.

Documentação

blender-ai-mcp

Um servidor MCP com formato de produção para Blender.

blender-ai-mcp permite que Claude, ChatGPT, Codex e outros clientes MCP controlem o Blender por meio de uma API de ferramentas estável, em vez de geração ad-hoc de Python. O resultado é uma superfície mais segura, menor e mais confiável para trabalho real de modelagem: roteamento orientado a objetivos, ferramentas públicas selecionadas, inspeção determinística e verificação que não depende de suposições.

Por Que Isso Existe

A maioria das configurações de "IA + Blender" ainda pede ao modelo para escrever scripts bpy brutos. Isso quebra exatamente onde o trabalho de produção fica interessante:

As APIs do Blender mudam entre versões.
Operadores sensíveis ao contexto falham quando o objeto ativo, o modo ou a seleção estão errados.
Scripts brutos dão feedback fraco quando algo dá errado.
A visão pode descrever um resultado, mas não pode ser confiável como autoridade final.

blender-ai-mcp adota a abordagem oposta: tratar o controle do Blender como uma superfície de produto, não como um truque de geração de código.

Por Que Este Servidor MCP em Vez de Python Bruto

Contratos estáveis em vez de síntese de scripts. O modelo chama ferramentas com parâmetros validados em vez de improvisar código Blender.
Orquestração orientada a objetivos. Sessões guiadas normais começam a partir de router_set_goal(...), para que o sistema saiba o que o modelo está tentando construir antes de começar a chamar ações de baixo nível.
Superfície pública pequena. O perfil padrão llm-guided expõe uma camada de bootstrap mínima e focada em busca, em vez de inundar o modelo com todo o inventário de runtime.
Verificação baseada na verdade. Ferramentas de inspeção, medição e asserção determinam o que é realmente verdadeiro no Blender.
Limites de execução seguros. O addon do Blender executa operações na thread principal do Blender enquanto o servidor MCP lida com roteamento, validação, descoberta e respostas estruturadas.

A Abordagem de Produto

A ideia de negócio formalizada em TASK-113 é simples:

Ferramentas atômicas são o substrato de implementação. Elas permanecem pequenas, precisas e, em sua maioria, ocultas da superfície pública normal.
Ferramentas macro são a camada preferida voltada para LLM para trabalho significativo em escala de tarefa.
Ferramentas de fluxo de trabalho são ferramentas de processo de múltiplas etapas limitadas, com relatórios explícitos, não endpoints abertos de "faça qualquer coisa".
Orquestração orientada a objetivos mantém as sessões ancoradas a uma intenção ativa, em vez de fazer o modelo redescobrir o contexto a cada turno.
A visão auxilia na interpretação, enquanto medição determinística e asserções fornecem a camada final de verdade.
Runtimes de visão plugáveis agora cobrem MLX local, além de caminhos externos de OpenRouter e Google AI Studio / Gemini, com perfis de contrato externo específicos por família de modelo para comportamento de prompt/esquema/parser.

Isso é o que transforma o projeto de "ferramentas Blender expostas via MCP" em um produto utilizável de controle de IA para pipelines de modelagem.

Superfície Pública Guiada por LLM

llm-guided é a superfície padrão orientada à produção. Ela é intencionalmente pequena, focada em busca e projetada para sessões conscientes de objetivos.

Fluxo guiado normal:

router_set_goal(...)
browse_workflows, search_tools ou call_tool
use ferramentas agrupadas/públicas como check_scene, inspect_scene ou configure_scene
verifique com inspeção mais scene_measure_* e scene_assert_*

Regra de prompting:

use os ativos da biblioteca de prompts em _docs/_PROMPTS/README.md como as instruções canônicas de operação guiada
quando um cliente se desviar, anteponha guided_session_start como estabilizador genérico de busca-primeiro
se uma ferramenta não estiver diretamente visível na superfície/fase atual, use search_tools(...) antes de call_tool(...)

Quando uma intenção de modelagem limitada corresponder, a camada de trabalho pública padrão deve ser a camada macro:

macro_cutout_recess para rebaixos, aberturas e recortes guiados por cortadores
macro_relative_layout para layout de peças com alinhar/posicionar/folga de contato
macro_attach_part_to_surface para assentar uma peça sobre a superfície/corpo de outro objeto
macro_align_part_with_contact para ajustes mínimos de reparo em pares que quase se encaixam
macro_place_symmetry_pair para posicionamento/correção de pares espelhados em torno de um plano de espelho explícito
macro_place_supported_pair para posicionamento/correção de pares espelhados contra uma superfície de suporte compartilhada
macro_cleanup_part_intersections para limpeza limitada de sobreposição entre pares, sem resolução de colisão de forma livre
macro_adjust_relative_proportion para reparo limitado de proporção entre objetos relacionados
macro_adjust_segment_chain_arc para ajuste limitado de arco em cadeias de segmentos ordenados
macro_finish_form para acabamento orientado por predefinições de chanfro/subdivisão/solidificar
reference_images para ingestão de referências com escopo de objetivo antes de comparação visual limitada
reference_guided_creature_build como ativo de prompt nativo para trabalho genérico de criaturas em etapas em llm-guided
recommended_prompts agora pode direcionar sessões guiadas orientadas a criaturas para esse caminho de prompt usando contexto ativo de objetivo/sessão
guided_reference_readiness em router_set_goal, router_get_status e cargas de comparação/iteração de referência em etapas, para que os clientes possam ver se o trabalho em etapas orientado por referência está realmente pronto
reference_compare_stage_checkpoint para comparação determinística de estágios em múltiplas vistas contra referências anexadas durante trabalho iterativo manual
reference_iterate_stage_checkpoint para um loop de correção em etapas consciente da sessão que lembra o foco anterior, pode escalar para inspecionar/validar quando a mesma correção se repete, e agora pode mirar um objeto, muitos objetos, uma coleção ou a silhueta completa montada
a comparação/iteração de estágios agora também expõe métricas determinísticas silhouette_analysis, action_hints tipados e um placeholder part_segmentation somente consultivo que permanece desabilitado a menos que um sidecar separado seja explicitamente habilitado
scene_scope_graph para um artefato explícito de escopo estrutural somente leitura com dicas de papel de âncora/núcleo/acessório
scene_relation_graph para um artefato explícito de relação entre pares somente leitura derivado da camada de verdade atual
scene_view_diagnostics para um artefato explícito de espaço de vista somente leitura com extensão projetada, cobertura de quadro, centralização e vereditos visível/parcial/ocluso/fora do quadro para câmeras nomeadas ou USER_PERSPECTIVE
essas ferramentas de diagnóstico de grafo espacial/vista agora fazem parte do conjunto de suporte padrão visível llm-guided, para que o modelo possa manter uma camada explícita de orientação 3D disponível em vez de inferir estado espacial apenas de nomes, capturas de tela ou cargas de loop parciais

Superfície de bootstrap guiada atual:

router_set_goal
router_get_status
browse_workflows
reference_images
scene_scope_graph
scene_relation_graph
scene_view_diagnostics
search_tools
call_tool
ferramentas opcionais de ponte de prompt quando MCP_PROMPTS_AS_TOOLS_ENABLED=true:
- list_prompts
- get_prompt

Clientes capazes de prompts devem preferir prompts MCP nativos. A ponte de prompt é uma camada de compatibilidade para clientes somente de ferramentas e pode ser desabilitada para perfis Streamable HTTP que já consomem componentes de prompt nativos.

Caminho de preparação de utilitários guiados atual:

a busca de bootstrap/planejamento agora pode alcançar:
- scene_get_viewport
- scene_clean_scene
essas ações de utilitário permanecem limitadas e não reabrem a superfície legada completa
o wrapper canônico de descoberta guiada é call_tool(name=..., arguments=...)
a forma canônica do argumento de limpeza em llm-guided é keep_lights_and_cameras; flags divididas antigas são somente compatibilidade e não devem ser usadas como a forma pública documentada
reference_images(action="attach", source_path=...) é uma referência por chamada; formas semelhantes a lote agora falham com orientação de recuperação guiada em vez de ruído bruto de esquema
collection_manage(action=..., collection_name=...) permanece a forma pública canônica; name legado é apenas um alias estreito de compatibilidade
modeling_create_primitive(...) permanece limitado a primitive_type, radius/size, location, rotation e name opcional; atalhos não suportados como scale, segments, rings, subdivisions ou collection_name em tempo primitivo agora falham com orientação acionável em caminhos guiados diretos e por proxy
metas de construção ainda devem começar de router_set_goal(...), mas solicitações de captura de tela / viewport / redefinição de cena devem usar o caminho de utilitário guiado
se o estado de cena desatualizado for descoberto somente após entrar na superfície de construção guiada, scene_clean_scene(...) também está disponível lá como uma saída de recuperação limitada; limpeza antes do objetivo ainda é o caminho preferido
limpeza na fase de construção ainda é permitida quando a recuperação é necessária

Aliases públicos atuais em llm-guided:

Ferramenta interna	Nome público `llm-guided`	Mudanças de argumento público
`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 que isso importa:

o perfil guiado começa com um conjunto de bootstrap visível e compacto, em vez do catálogo completo
ferramentas agrupadas/públicas permanecem fáceis de descobrir
ferramentas atômicas ocultas permanecem disponíveis como infraestrutura, não como o modelo mental público padrão
famílias especialistas permanecem fora da camada de entrada guiada normal até que a superfície macro seja mais ampla

Fundamentos Atômicos e Documentação

O README.md raiz intencionalmente não é mais o catálogo completo de ferramentas.

O inventário detalhado de ferramentas e a documentação das famílias atômicas devem permanecer na documentação, não na página inicial. Essa é a estrutura correta de longo prazo após TASK-113.

Use estes documentos dependendo do que você precisa:

Política de Camadas de Ferramentas
- Política canônica para atomic / macro / workflow, ferramentas atômicas ocultas, uso orientado a objetivos e limites de visão/asserção.
Documentação do Servidor MCP
- Perfis de superfície, aliases guiados, contratos versionados e orientação de runtime/plataforma.
Exemplos de Configuração de Cliente MCP
- Exemplos prontos para colar de configuração de cliente MCP local para superfícies guiadas/manuais, além de variantes de visão MLX, OpenRouter e Gemini.
Documentação da Camada de Visão
- Runtimes/backends, pacotes de captura, imagens de referência, notas de integração de visão em macro/fluxo de trabalho e pacotes de avaliação de viewport real rastreados no repositório para capturas diretas da visão do usuário e de perspectiva fixa de câmera.
Guia LLM v2
- Documento de estratégia para uma camada de inteligência espacial tipada, estado de relação compacto e handoffs de próxima etapa limitados para operação guiada.
Brief de Pesquisa de Inteligência Espacial
- Handoff de pesquisa externa para raciocínio espacial LLM/VLM, raciocínio multi-vista e planejamento consciente de geometria.
Proposta de Atualização de Inteligência Espacial
- Proposta de atualização orientada por pesquisa para grafos de cena, notação simbólica de relação e escolhas de biblioteca de geometria de suporte.
Resumo de Ferramentas Disponíveis
- Inventário completo e visão geral de ferramentas agrupadas/públicas.
Índice de Arquitetura de Ferramentas
- Mapa voltado a mantenedores das famílias de ferramentas sob a superfície MCP.

Se você quiser ver as famílias atômicas sobre as quais o servidor é construído, comece aqui:

Interpretação recomendada:

mantenha /_docs/TOOLS/ como o mapa de arquitetura atômica/agrupada voltado a mantenedores
mantenha README.md voltado ao produto e compacto
mantenha /_docs/AVAILABLE_TOOLS_SUMMARY.md como o inventário de runtime

Notas de Provedor

Versão curta atual:

Padrão local: mlx_local com um caminho de modelo da classe Qwen VL 4B; a linha de base validada no repositório atual é mlx-community/Qwen3-VL-4B-Instruct-4bit
Candidato externo de comparação iterativa: OpenRouter com x-ai/grok-4.20-multi-agent
Caminho de comparação externo da família Google: modelos da família Google hospedados no OpenRouter, além do Google AI Studio / Gemini, agora compartilham o mesmo contrato estreito de comparação em etapas por meio do roteamento resolvido vision_contract_profile

Observação do runtime de visão externa:

VISION_EXTERNAL_PROVIDER seleciona o ramo de transporte/provedor
VISION_EXTERNAL_CONTRACT_PROFILE opcionalmente substitui o contrato de prompt/esquema/parser para fluxos de comparação externa
quando a substituição não está definida, o runtime corresponde automaticamente a IDs de modelos da família Google, como gemma / gemini / learnlm, e então recorre aos padrões do provedor

Tabela detalhada por provedor:

Docs da Camada de Visão -> Notas do Provedor

Arquitetura

O sistema é dividido de propósito:

Servidor MCP (server/): superfície FastMCP, definições de ferramentas públicas, transformações, descoberta e contratos de resposta.
Roteador (server/router/): interpretação de objetivos, política de segurança/correção, correspondência de fluxos de trabalho, contexto de sessão e comportamento de execução guiada.
Addon do Blender (blender_addon/): execução real de bpy, manipuladores RPC e agendamento de operações seguras para a thread principal do Blender.

A comunicação ocorre via JSON-RPC sobre soquetes TCP.

Mais detalhes:

Linha de Base do Contrato Estruturado

O servidor está movendo superfícies críticas para cargas úteis legíveis por máquina em vez de strings JSON com muito texto.

A linha de base atual do contrato estruturado inclui:

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

Isso é importante para automação, auditoria e futura composição de macros/fluxos de trabalho.

Semântica de Verdade de Contato

Para verificações sensíveis a contato em formas curvas ou arredondadas, a camada de verdade agora distingue:

semântica de contato/lacuna de superfície de malha quando um caminho limitado com consciência de malha está disponível
semântica de fallback de bbox quando um caminho com consciência de malha não está disponível

Isso significa que um par ainda pode mostrar contato de bbox enquanto a relação medida principal permanece separated se as superfícies reais da malha ainda tiverem uma lacuna visível. O acompanhamento guiado de verdade híbrida agora carrega essa distinção nos resumos voltados ao operador em vez de colapsá-la em uma afirmação genérica de "contato aprovado/reprovado".

Quando o caminho com consciência de malha encontra uma sobreposição real, a relação medida principal também permanece overlapping, então a rejeição de sobreposição em scene_assert_contact(...) ainda funciona como uma condição de verdade separada em vez de colapsar em contato simples.

Fluxo de Esclarecimento Estruturado

A superfície guiada suporta o tratamento de entradas ausentes como parte do contrato do produto, não como uma reflexão tardia.

Esclarecimento modelo-primeiro é o padrão para router_set_goal(...) em llm-guided: parâmetros de fluxo de trabalho ausentes retornam uma carga útil tipada needs_input para o modelo externo primeiro.
Cargas úteis de fallback tipadas mantêm o mesmo fluxo utilizável em clientes somente de ferramentas ou de compatibilidade.
Esclarecimento humano/nativo é reservado para política posterior/fallback em vez do primeiro passo padrão da execução do fluxo de trabalho.
router_set_goal(...) pode solicitar escolhas restritas, booleanos, enums ou confirmação de fluxo de trabalho.
partial answers sobrevivem entre turnos de acompanhamento.
Conflitos de importação de workflow_catalog reutilizam o mesmo modelo de esclarecimento.

Contrato de Transferência Guiada

A superfície guiada agora trata o fallback de fluxo de trabalho como um contrato tipado explícito em vez de um efeito colateral de fase oculto em texto.

router_set_goal(...) retorna guided_handoff em caminhos de continuação limitados, como continuation_mode="guided_manual_build" e continuation_mode="guided_utility".
guided_handoff nomeia o target_phase, direct_tools, supporting_tools e discovery_tools para o próximo passo em llm-guided.
workflow_import_recommended permanece False nesses caminhos de fallback, a menos que o usuário solicite explicitamente o comportamento de importação/criação de fluxo de trabalho.
router_get_status(...) preserva o guided_handoff ativo nos diagnósticos de sessão para que os clientes possam recuperar o caminho de continuação pretendido.

Estado de Fluxo Guiado Controlado pelo Servidor

A superfície guiada agora carrega um contrato explícito legível por máquina guided_flow_state além de guided_handoff.

router_set_goal(...), router_get_status(...), reference_compare_stage_checkpoint(...) e reference_iterate_stage_checkpoint(...) podem expor guided_flow_state para a sessão ativa de llm-guided
guided_flow_state relata:
- 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
as sobreposições de domínio atuais são:
- generic
- creature
- building
as sessões iniciais de construção guiada agora começam a partir de uma fase de contexto espacial com etapas limitadas, em vez de expor toda a superfície de construção imediatamente
scene_scope_graph(...) vincula o escopo de destino guiado ativo quando nenhum escopo ativo existe ainda; as verificações de atualização espacial devem continuar usando esse escopo de destino já vinculado, em vez de revincular a um conjunto diferente de objetos
verificações de visão não relacionadas, como scene_view_diagnostics(target_object="Camera", ...), não satisfazem por si só uma verificação espacial de criatura/construção
se imagens de referência estiverem anexadas para o objetivo guiado ativo, trate-as como a entrada de fundamentação primária antes de decidir as primeiras massas de corpo/cabeça/cauda e a silhueta aproximada
use nomes de objetos semânticos completos, como Body, Head, Tail, ForeLeg_L e HindLeg_R, em vez de abreviações opacas como ForeL / HindR, porque as heurísticas guiadas de junção/papel são mais confiáveis com nomes legíveis
em llm-guided, o servidor agora pode alertar sobre nomes fracos sensíveis ao papel e bloquear nomes de espaço reservado claramente opacos, como Sphere / Object, quando eles são usados como nomes de partes semânticas
não chame scene_scope_graph(...), scene_relation_graph(...) ou scene_view_diagnostics(...) sem um escopo explícito e presuma que isso significa "inspecionar toda a cena"
durante uma porta espacial guiada ativa ou um rearmamento de atualização espacial, todos os três desses auxiliares espaciais devem ser tratados como ferramentas de escopo explícito, não como sondas de cena inteira
esses auxiliares espaciais somente leitura fixados permanecem chamáveis enquanto visíveis em llm-guided; o bloqueio da família guiada não deve rejeitar scene_scope_graph(...), scene_relation_graph(...) ou scene_view_diagnostics(...) simplesmente porque o allowed_families da etapa de construção atual omite spatial_context
fora dessa porta guiada, os construtores de gráficos de escopo/relação ainda exigem um target_object, target_objects ou collection_name explícito; uma chamada simples agora falha em vez de retornar silenciosamente um escopo scene vazio
escopos de espaço reservado padrão, como um Cube padrão ou a raiz genérica Collection, não são mais tratados como vinculações significativas de destino/conjunto de trabalho guiado por si só
mas para a decisão anterior de inicialização "esta cena já não está vazia?", o Cube padrão do Blender, mais os auxiliares padrão de câmera/luz, ainda entram no caminho de inicialização do conjunto de trabalho primário de cena vazia
essa decisão de não vazio é intencionalmente leve em nomes após a inicialização: blockouts aproximados reais de múltiplos objetos com nomes de primitivas padrão, como Cube ou Sphere, ainda contam como geometria existente, enquanto cenas somente com auxiliares ainda podem entrar em bootstrap_primary_workset
escopos guiados explícitos agora se vinculam a partir da intenção do chamador, em vez de heurísticas de nome, então objetos reais nomeados como Cube, Sphere ou Sunflower ainda podem se tornar o conjunto de trabalho guiado ativo quando o operador os direciona
após mudanças materiais na cena, como scene_clean_scene(...), scene_duplicate_object(...), scene_rename_object(...), modeling_create_primitive(...), modeling_transform_object(...), modeling_join_objects(...), modeling_separate_object(...) ou macros limitadas de anexação/alinhamento, o runtime guiado pode marcar a camada espacial como obsoleta e rearmar as verificações necessárias
essa mesma atualização de estado sujo agora reaplica a visibilidade FastMCP imediatamente, para que os clientes vejam as ferramentas de suporte espacial necessárias assim que spatial_refresh_required for persistido
em Streamable HTTP, os finalizadores de estado sujo e visibilidade guiados devem ser concluídos antes que a resposta da ferramenta ativa retorne; ferramentas síncronas roteadas que mutam o estado da cena adiam esses finalizadores para o wrapper assíncrono MCP, em vez de agendar gravações de estado de sessão destacadas
wrappers assíncronos e auxiliares de modelagem assíncrona nativos mantêm o roteador/RPC síncrono bloqueante em uma thread de trabalho; apenas os finalizadores guiados são executados de volta no loop de eventos antes que a resposta Streamable HTTP seja concluída
auxiliares de macro suja assíncronos, como macro_cutout_recess(...) e macro_finish_form(...), usam o caminho de rota assíncrona aguardado para que a visibilidade seja reaplicada antes que a resposta Streamable HTTP seja concluída
auxiliares espaciais assíncronos, como scene_scope_graph(...), scene_relation_graph(...) e scene_view_diagnostics(...), roteiam suas leituras de gráfico/diagnóstico apoiadas pelo Blender para fora do loop de eventos antes de registrar a conclusão da verificação espacial guiada
finalizadores de identidade guiada assíncronos, como a validação bem-sucedida de scene_rename_object(...), também mantêm as buscas de cena apoiadas pelo Blender fora do loop de eventos antes de atualizar o registro de partes guiado
ferramentas de modelagem assíncrona nativas que consomem um relatório de execução do roteador ainda devem exibir avisos de guided_naming através do contexto MCP ativo; caso contrário, nomes semânticos fracos podem perder suas dicas de correção voltadas ao modelo em Streamable HTTP
finalizadores de modelagem e limpeza assíncrona nativa derivam mutações de cena bem-sucedidas de report.steps estruturado, não do texto de rota legado renderizado; rotas corrigidas em várias etapas prefixam linhas legadas e não são uma fonte confiável para decisões de estado sujo guiado ou registro de papel
o registro de papel guiado assíncrono reaplica a visibilidade FastMCP após o guided_flow_state avançado final ser persistido, para que list_tools() reflita a nova etapa guiada antes que a resposta Streamable HTTP seja concluída
variantes de ferramentas públicas assíncronas devem preservar os docstrings públicos originais, especialmente para auxiliares espaciais e de modelagem guiados visíveis cujas descrições ensinam argumentos de escopo necessários, ordem de fluxo de trabalho e restrições de argumentos
quando o roteador corrige uma chamada bem-sucedida de modeling_transform_object(...) para outro nome de objeto válido, o estado sujo espacial guiado e o acompanhamento de papel guiado usam o nome de objeto transformado retornado pela etapa de modelagem final, não o nome original fornecido pelo chamador
ferramentas de edição de malha guiadas, como mesh_extrude_region(...), mesh_loop_cut(...) e mesh_bevel(...), agora são mapeadas para a família secondary_parts, então são bloqueadas durante portas de contexto espacial e rearmam verificações espaciais após edições de geometria bem-sucedidas
quando uma dessas verificações espaciais necessárias é concluída e avança o fluxo guiado, o servidor agora reaplica a visibilidade FastMCP imediatamente, em vez de esperar por uma atualização posterior de status/pesquisa
pares de relação com suporte/simetria agora preservam anotações de suporte e simetria mesmo quando compartilham a mesma chave (from_object, to_object) que um par primário-alvo genérico, para que planejadores guiados posteriores ainda vejam semânticas de suporte/simetria em vez de apenas uma aresta genérica
gráficos de relação que incluem junções de criatura necessárias ainda adicionam pares de fallback primary_to_other para objetos não-junção no escopo solicitado, para que objetos não classificados não desapareçam de diagnósticos guiados mistos
pares saudáveis de suporte/simetria não contam mais como falhos apenas porque seus centros diferem ou não são pares de contato literais; apenas vereditos de suporte/simetria unsupported / asymmetric contam como falhas lá
quando guided_flow_state.spatial_refresh_required == true, trate next_actions=["refresh_spatial_context"] como estado de servidor autoritativo, não prosa consultiva; atualize com scene_scope_graph(...) contra o escopo de destino já vinculado primeiro, depois execute novamente as verificações espaciais necessárias restantes nesse mesmo escopo
scene_view_diagnostics(...) só conta para a porta espacial guiada quando retorna evidência real de espaço de visão disponível; uma sonda headless/indisponível permanece somente leitura e não satisfaz a verificação necessária por si só
se a comparação/iteração de estágio encontrar problemas importantes enquanto a fatia de papel/conjunto de trabalho guiada atual ainda estiver incompleta, o governador agora pode manter a sessão em continuação de construção limitada em vez de escalar cedo demais para inspect_validate
quando essa retenção de estágio incompleto retorna loop_disposition="continue_build", o guided_flow_state persistido permanece na mesma etapa atual e não marca a fatia de papel inacabada como concluída; continue seguindo missing_roles antes de confiar na visibilidade de estágios posteriores
essa retenção de estágio incompleto também se aplica quando a iteração de estágio não tem correction_focus ou action_hints; um resultado de comparação sem ação não deve avançar uma construção guiada com papéis necessários ausentes para finish_or_stop
depois que o fluxo atinge uma etapa posterior, como place_secondary_parts, o servidor ainda pode manter massas primárias ausentes disponíveis quando elas fazem parte do mesmo conjunto de trabalho limitado, em vez de forçar uma execução de esquilo/construção a abandonar uma massa central inacabada imediatamente
para junções de blockout de criatura, intersecting ainda pode ser aceitável para posicionamento de orelha/cabeça ou focinho/cabeça embutidos, mas floating_gap em cabeça/corpo, cauda/corpo ou membro/corpo permanece acionável
se uma família de ferramentas necessária estiver oculta/bloqueada pelo fluxo, inspecione router_get_status().guided_flow_state, complete os required_checks listados e siga next_actions em vez de adivinhar nomes de ferramentas ocultas em call_tool(...)
se um objetivo guiado explícito permaneceu em um caminho manual/sem correspondência, um fluxo de trabalho forte sugerido por padrão ainda pode se expandir; o que permanece suprimido nesse estado é o caminho de reabertura heurística de menor confiança
pesquisas exatas de nomes de ferramentas na superfície guiada agora são moldadas para retornar um conjunto de resultados mais restrito e menor, em vez de inundar o modelo com uma carga expandida completa para consultas simples
para etapas de construção sensíveis ao papel, trate allowed_roles e missing_roles como parte do contrato de execução, não como prosa consultiva
operações de manutenção/conjunto de trabalho, como collection_manage(...), devem permanecer disponíveis para objetos já criados, mesmo quando seu papel semântico foi registrado em uma etapa anterior
o refinamento limitado de um objeto primário já registrado pode permanecer possível depois que a sessão avança para a próxima etapa; etapas posteriores não pretendem congelar completamente todas as massas anteriores
use guided_register_part(object_name=..., role=...) como a maneira canônica de dizer ao servidor qual parte semântica um objeto representa; dicas opcionais de guided_role=... em ferramentas de construção são apenas por conveniência
valores opcionais de role_group=... devem corresponder ao mapa de papéis de domínio do servidor; chamadores não podem reclassificar body_core, head_mass ou chamadas mutantes semelhantes sensíveis ao papel como utility ou outra família para contornar a porta de fase guiada atual
guided_register_part(...) agora valida que o objeto Blender nomeado realmente existe antes que possa contar para a conclusão de papel guiado; erros de digitação não criam papéis concluídos por si só
se a validação de objeto guiado não puder ler a cena Blender de forma alguma, guided_register_part(...) agora falha claramente em vez de mutar o estado de sessão guiado a partir de um nome de objeto não verificado
nomes de destino explícitos passados para scene_scope_graph(...) / caminhos de construção de escopo agora seguem a mesma regra de validação de verdade do Blender antes que o escopo guiado possa se vincular
essas dicas opcionais de guided_role=... só auto-registram quando um fluxo guiado ativo já existe; fora de um fluxo guiado ativo, elas não criam estado de papel persistente por si só
uma chamada de criação falha agora permanece não mutante para o estado de papel guiado também: se modeling_create_primitive(...) retorna uma string de falha, o papel solicitado não é auto-registrado apenas porque um name semântico foi fornecido
em modeling_create_primitive(...), guided_role=... agora também exige um name semântico explícito; a criação guiada não permite Blender auto-gerado
nomes passam a ser registros de parte semântica
quando o roteador antepõe etapas corretivas como scene_set_mode(...), chamadas guiadas bem-sucedidas de criação/transformação ainda registram a função resultante na etapa final de modelagem, em vez de descartar o registro de conveniência apenas porque a chamada se tornou multi-etapa
o registro de conveniência de função guiada agora também lida com nomes de objeto válidos contendo apóstrofos, como King's Crown, em vez de truncar o nome do objeto armazenado
a análise de sucesso em tempo de execução guiada também trata apóstrofos dentro de nomes de objeto entre aspas como parte do nome do objeto para resultados de criação/transformação/renomeação/união, para que a marcação de estado obsoleto e a sincronização do registro guiado ainda sejam executadas após mutações bem-sucedidas
nomes de pares canônicos como ForeLeg_L, ForeLeg_R e ForeLegPair agora contam como nomes semânticos fortes para foreleg_pair / hindleg_pair em vez de avisar ou bloquear sob a política de nomenclatura mais rígida
em modeling_create_primitive(...), o registro automático de função guiada agora vincula ao nome real do objeto criado retornado pelo Blender, para que o estado da função permaneça alinhado mesmo quando o Blender numera automaticamente um nome padrão como Cube.001 ou usa um nome de objeto padrão diferente, como Suzanne
em modeling_transform_object(...), o registro automático de função guiada agora vincula ao nome real do objeto transformado retornado pela etapa roteada final, para que a identidade do objeto corrigida pelo roteador ainda reative as verificações espaciais e atualize o estado da função para o objeto que realmente mudou
chamadas bem-sucedidas de scene_rename_object(...) agora mantêm o registro de parte guiada alinhado com o objeto renomeado do Blender, para que transformações posteriores sensíveis à função ainda recuperem a função registrada sem re-registro manual
chamadas bem-sucedidas de scene_rename_object(...) também reativam as verificações espaciais guiadas, porque a impressão digital do escopo de destino vinculado é baseada em nome
chamadas bem-sucedidas de scene_duplicate_object(...) também reativam as verificações espaciais guiadas, porque a duplicação altera os fatos visíveis de relação workset/escopo
resultados de mutação de string simples com falha, como Object 'Missing' not found, agora permanecem não mutantes para o estado de sessão guiada; eles não reativam verificações espaciais nem reescrevem o registro de função guiada apenas porque o wrapper retornou uma string
scene_clean_scene(...) agora limpa o registro de parte guiada e retorna o fluxo guiado para bootstrap_primary_workset em vez de carregar partes concluídas adiante em uma cena vazia
iniciar um objetivo guiado diferente na mesma sessão agora redefine o registro de parte guiada para esse novo fluxo, em vez de carregar funções concluídas adiante do objeto anterior
mudanças destrutivas de identidade/topologia, como modeling_join_objects(...) ou modeling_separate_object(...), agora descartam registros de parte guiada obsoletos; re-registre o(s) objeto(s) resultante(s) explicitamente se eles ainda devem contar para a conclusão da função guiada
essas mesmas mudanças destrutivas de topologia também reativam as verificações espaciais guiadas, porque fatos de escopo/visão capturados anteriormente não são mais confiáveis após objetos serem mesclados ou divididos
para artefatos de captura/visão de macro, macro_attach_part_to_surface(...) agora atualiza seu pacote de captura pós-ação após o ajuste extra da superfície da malha, para que imagens anexadas e resumo de verdade descrevam a pose final assentada em vez da pose intermediária pré-ajuste
relatórios de macro roteados podem ser partial e ainda carregar um error; os adaptadores MCP preservam esse relatório estruturado, incluindo actions_taken, objetos modificados, recomendações de verificação, dados de captura/verdade e orientação de acompanhamento, em vez de coagí-lo em um envelope vazio de falha
se o sidecar de segmentação opcional estiver habilitado na configuração de tempo de execução, mas ainda não executado no caminho de comparação atual, respostas de comparação/iteração encenadas agora relatam part_segmentation.status="unavailable" em vez de permanecerem silenciosamente disabled
se o servidor avisar ou bloquear na nomenclatura guiada, renomeie ou crie o objeto usando um dos nomes semânticos sugeridos em vez de tentar novamente a mesma abreviação fraca
a inferência de nomenclatura guiada e de função espacial guiada agora usa correspondências de estilo de limite de token em vez de correspondências brutas de substring, para que nomes como Heart ou TruthBodyAnchorHead não se tornem funções semânticas acidentais de orelha/corpo/cabeça
o required prompt bundle e o preferred prompt bundle nomeados em guided_flow_state são nomes de ativos de prompt, não um substituto para o fluxo orientado pelo servidor; prompts apoiam o fluxo, eles não se tornam o fluxo

Prontidão de Referência Guiada

O trabalho em etapas orientado por referência agora possui um contrato explícito de prontidão, em vez de suposições ocultas de ordenação.

router_set_goal(...) e router_get_status(...) expõem guided_reference_readiness.
o payload relata attached_reference_count, pending_reference_count, compare_ready, iterate_ready, além de blocking_reason e next_action legíveis por máquina
reference_images(action="attach", source_path=...) pode permanecer pendente até que a sessão de meta guiada esteja realmente pronta e, então, adotar automaticamente
se o mesmo objetivo já tiver referências ativas e novas forem preparadas durante needs_input, as referências preparadas permanecem separadas das referências de objetivo já ativas até que a prontidão retorne
se uma sessão pronta ainda carregar referências pendentes explícitas para outro objetivo, reference_images(action="list"| "remove"| "clear", ...) agora trata esse conjunto visível mesclado de forma consistente, em vez de deixar registros pendentes quebrados
reference_compare_stage_checkpoint(...) e reference_iterate_stage_checkpoint(...) agora falham rapidamente quando a sessão não está pronta e ecoam o mesmo payload de guided_reference_readiness
se reference_iterate_stage_checkpoint(...) retornar loop_disposition="inspect_validate", pare a modelagem de forma livre e mude para inspecionar/medir/afirmar imediatamente
se retornar loop_disposition="continue_build" enquanto guided_flow_state.missing_roles ainda não estiver vazio, continue a fatia de função atual; o servidor mantém intencionalmente a etapa guiada no lugar em vez de avançar para o próximo estágio, mesmo quando o próprio resultado da comparação não produziu dicas acionáveis de correção
router_set_goal(..., gate_proposal={...}) pode aceitar uma proposta opcional de portão derivada de modelo ou referência para o objetivo guiado ativo. O servidor a normaliza em active_gate_plan, inicia cada portão como pending e retorna gate_intake_result.policy_warnings para nomes de ferramentas ocultas descartados, tipos de portão não suportados, instruções brutas de Blender/Python, evidências de referência/percepção obrigatórias indisponíveis na superfície de captura no momento do objetivo ou alegações de conclusão fornecidas pelo cliente, como passed.
router_get_status(...), router_set_goal(...) e payloads preparados de comparação/iteração de referência podem expor active_gate_plan; LLM, reference_understanding, silhueta, segmentação, classificação e fontes de checkpoint VLM podem propor ou apoiar portões, mas evidências de cena/espacial/malha e afirmação permanecem como autoridade de verdade para o status de aprovação/reprovação.
payloads preparados de comparação/iteração de referência também projetam o plano de portão ativo nos gate_statuses, completion_blockers, next_gate_actions e recommended_bounded_tools de nível superior, para que os clientes não precisem inferir o caminho imediato de reparo a partir da forma aninhada do plano.
scene_relation_graph(...) atualiza a primeira fatia determinística de portão para required_part, attachment_seam, support_contact e symmetry_pair com referências de evidência autoritativas, motivos de status, bloqueadores de conclusão e dicas limitadas de ferramentas de reparo; mutações guiadas posteriores da cena marcam os status com suporte de verificador afetados como stale por meio do caminho existente de sujeira espacial.
bloqueadores de portão ativos restringem a visibilidade/busca guiada em direção a ferramentas existentes de verificador e reparo; um portão de costura reprovado deve levar a ferramentas de reparo de grafo de relação/medida/afirmação/macro, não a um catálogo amplo ou reinício de objetivo.
completion_blockers não resolvido em respostas preparadas de iteração agora também envia loop_disposition="inspect_validate" mesmo quando o loop de comparação não repetiu o mesmo foco de correção apenas por visão.
se a comparação preparada degradar, mas ainda existirem achados fortes de verdade determinística, use o mesmo encaminhamento de inspecionar/medir/afirmar em vez de improvisar outra correção grande de forma livre
encaminhamentos de iteração em estágio de erro que movem para inspect_validate ou finish_or_stop também reaplicam a visibilidade guiada antes de retornar
para comparação/iteração preparada, goal_override não é mais um substituto de sessão; use uma sessão de objetivo guiado ativa
para capturas preparadas de coleção ou multiobjeto, o foco de captura agora recai sobre o alvo principal do escopo de destino montado quando nenhum target_object explícito é fornecido
métricas determinísticas de silhueta preferem a captura de alvo/foco para o target_view solicitado, não a captura ampla de context_wide
reference_compare_current_view(..., persist_view=True, view_name=..., orbit_horizontal=..., zoom_factor=...) mantém a visão de usuário capturada e não reproduz esses mesmos ajustes de visão uma segunda vez durante diagnósticos compactos de visão

Diagnósticos de Sessão

Payloads guiados/em tempo de execução agora expõem metadados explícitos de sessão MCP:

router_set_goal(...) inclui session_id e transport
router_get_status(...) inclui session_id e transport
reference_compare_stage_checkpoint(...) inclui session_id e transport
reference_iterate_stage_checkpoint(...) inclui session_id e transport

Orientação atual em tempo de execução:

streamable HTTP com estado é o transporte recomendado para execuções guiadas mais longas e para depurar fluxos de referência/checkpoint cientes de sessão
o endurecimento recente de sessão guiada removeu o caminho conhecido de contabilidade do roteador que podia sobrescrever o estado de sessão de objetivo/referência ativo durante a execução de ferramentas roteadas
se você investigar um incidente futuro de perda de estado, compare session_id e transport primeiro para distinguir:
- reconexões de transporte/sessão
- reinícios de objetivo em nível de aplicação
- bloqueadores normais de prontidão guiada, como objetivo ou referências ausentes

Linha de Base de Assistentes de Amostragem no Lado do Servidor

O servidor MCP agora tem uma camada limitada de assistente analítico dentro de uma solicitação ativa.

Casos de uso atuais:

assistant_summary opcional em caminhos com muita inspeção, como scene_snapshot_state, scene_compare_snapshot, scene_get_hierarchy, scene_get_bounding_box e scene_get_origin_info
repair_suggestion limitado em router_set_goal, router_get_status e workflow_catalog

Estados terminais explícitos do assistente:

success
unavailable
masked_error
rejected_by_policy

A regra é estrita: assistentes podem ajudar a resumir ou sugerir, mas não substituem a verdade da cena ou a política do roteador.

Linha de Base de Superfície Versionada

A evolução da superfície pública é versionada explicitamente:

Perfil de superfície	Linha de contrato padrão
`legacy-manual`	`legacy-v1`
`legacy-flat`	`legacy-v1`
`llm-guided`	`llm-guided-v2`

Nota de compatibilidade:

llm-guided-v1 permanece selecionável como linha de reversão
workflow_catalog, scene_context e scene_inspect participam da história de evolução de superfície guiada

Decisão do Modo de Código

Linhas de base atuais de benchmark:

legacy-flat
llm-guided
code-mode-pilot

Decisão atual:

Decisão Go: manter code-mode-pilot como uma superfície experimental somente leitura
Não tornar o Modo de Código o caminho padrão para trabalho de Blender com muitas gravações ou destrutivo para geometria

Matriz de Suporte

Blender: testado no Blender 5.0 na cobertura E2E; o mínimo do addon permanece Blender 4.0+ na base de melhor esforço.
Python: 3.11+
Tempo de execução de tarefas FastMCP: fastmcp 3.2.4 + pydocket 0.19.x
Extra do sandbox do Modo de Código: pydantic-monty 0.0.11
SO: macOS / Windows / Linux
Memória: recursos semânticos do roteador dependem de um modelo local LaBSE e infraestrutura vetorial relacionada

Início Rápido

1. Instale o addon do Blender

Baixe blender_ai_mcp.zip da página de Releases ou compile-o localmente com python scripts/build_addon.py.
Abra o Blender -> Editar -> Preferências -> Add-ons.
Clique em Instalar... e selecione o arquivo zip.
Ative o addon. Ele inicia o servidor RPC local do Blender na porta 8765.

2. Execute o servidor MCP no perfil guiado

Padrões recomendados:

ROUTER_ENABLED=true
MCP_SURFACE_PROFILE=llm-guided
mapeie /tmp se quiser saídas de imagem/arquivo visíveis ao host

Exemplo 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

Exemplo de configuração 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 rede:

macOS / Windows: use host.docker.internal
Linux: prefira --network host com BLENDER_RPC_HOST=127.0.0.1
MCP_TRANSPORT_MODE=stdio mantém o modo MCP atual de subprocesso/stdio
MCP_TRANSPORT_MODE=streamable inicia um servidor MCP HTTP Streamable com estado
MCP_PROMPTS_AS_TOOLS_ENABLED=false desativa a ponte de prompt compatível com ferramentas para clientes com capacidade de prompt; prompts MCP nativos permanecem disponíveis

Para exemplos mais amplos de perfil/configuração, use:

Documentação do Servidor MCP
Exemplos de Configuração de Cliente MCP
.env.example para o conjunto completo de variáveis de configuração/tempo de execução rastreadas

Testes

Testes de unidade:

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

Contagem de coleção de unidade:

poetry run pytest tests/unit --collect-only

Testes E2E:

python3 scripts/run_e2e_tests.py

Contagem de coleção E2E:

poetry run pytest tests/e2e --collect-only

Pré-commit:

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

Mais detalhes:

Mapa de Documentação

Contribuindo

Leia CONTRIBUTING.md antes de abrir um PR. O repositório aplica limites de Arquitetura Limpa, Python tipado, regras de metadados do roteador e validação de pré-commit.

Comunidade e Suporte

Se blender-ai-mcp for útil no seu fluxo de trabalho, considere patrocinar seu desenvolvimento de longo prazo.

O patrocínio ajuda a financiar manutenção, documentação, testes e o trabalho de confiabilidade de nível superior que torna este repositório diferente da geração bruta de código Blender: roteamento orientado a objetivos, ferramentas selecionadas, verificação determinística e suporte a fluxos de trabalho com formato de produção.

Torne-se um patrocinador

Autor

Patryk Ciechański

GitHub: PatrykIti

Licença

Este projeto está licenciado sob a Apache License 2.0.

Consulte: