SolidWorks MCP Server

Servidor MCP em Python que controla o SolidWorks via COM (win32com), escrito com o SDK oficial (mcp, usando FastMCP). 163 ferramentas (v5.21.5).

Para quem so quer usar

Instale o .mcpb com dois cliques. O passo a passo completo, sem jargao, esta em COMO_USAR.md.

Requisitos: Windows, SolidWorks 2022+ instalado e licenciado, e Claude Desktop.

Related MCP server: SolidworksMCP-python

Para quem vai desenvolver

Política de ferramentas

O catálogo MCP mantém somente operações CAD reutilizáveis e geradores paramétricos de categorias de componentes. Receitas de produtos completos — por exemplo, um pistão automotivo completo, um ventilador ou um redutor específico — não são ferramentas públicas: elas devem viver em scripts de exemplo/workflows que combinem as operações do catálogo. Assim, novos projetos reutilizam as mesmas ferramentas mudando parâmetros, sem transformar cada modelo em uma nova entrada permanente do MCP.

pip install -r requirements.txt
python -m pytest

Configuracao manual em claude_desktop_config.json:

{
  "mcpServers": {
    "solidworks": {
      "command": "python",
      "args": ["C:\\caminho\\para\\mcp-solidworks\\server.py"]
    }
  }
}

Gerar o pacote distribuivel

O manifest.json declara server.type: "uv", entao o Claude Desktop resolve Python e dependencias sozinho a partir do pyproject.toml -- necessario porque pywin32 e pydantic sao extensoes compiladas e nao podem ser empacotadas de forma portatil.

npx @anthropic-ai/mcpb pack . solidworks-mcp-5.18.0.mcpb

O nome do pacote e escopado: npx mcpb pack falha com 404 (mcpb nao existe no registro npm), o que este README mandava fazer ate a v5.18.0. O pack valida o manifest.json antes de empacotar e respeita o .mcpbignore -- confira na listagem que gear_geometry.py, alfa_drawing.py e os onze arquivos de .claude/knowledge/ entraram: o server.py importa os dois primeiros e expoe os outros como resources, entao um pacote sem eles instala e quebra em uso.

Abra o SolidWorks (opcional -- o servidor consegue abrir sozinho) e peca para o Claude "conectar ao SolidWorks".

Seguranca para uso publico

Este servidor foi projetado para automacao local confiavel. Ele controla uma sessao real do SolidWorks pelo COM do Windows, entao ferramentas como salvar, fechar, suprimir componentes e alterar geometrias modificam documentos abertos.

A ferramenta execute_python fica desativada por padrao porque executa Python com acesso aos objetos COM sw e doc. Para usar somente em depuracao local confiavel, defina explicitamente:

$env:SOLIDWORKS_MCP_ENABLE_EXECUTE_PYTHON = "1"

Nao publique modelos CAD privados, pacotes .mcpb, logs ou resultados de teste gerados localmente. O .gitignore ja exclui esses artefatos por padrao.

Status de verificacao (testado ao vivo no SolidWorks 2025, PT-BR)

A matriz abaixo registra o estado validado no SolidWorks 2025 PT-BR. Legenda:

• OK = criou o recurso com sucesso no teste ao vivo.

• EXP = experimental: a assinatura COM esta correta mas o recurso depende de selecao/estado especifico ou de uma parte da API que se comporta de forma inconsistente nesta versao; pode exigir ajuste manual.

Conexao / Documentos / Utilidades -- OK

connect_solidworks, get_solidworks_info, create_new_part, create_new_assembly, create_new_drawing, open_document, close_document, save_document, get_document_info, list_open_documents, set_units, set_view, zoom_to_fit, zoom_to_area, get_view_state

execute_python e uma ferramenta de depuracao privilegiada. Ela existe no catalogo, mas permanece bloqueada ate SOLIDWORKS_MCP_ENABLE_EXECUTE_PYTHON=1 ser definido.

Correcao importante: os templates padrao sao resolvidos pelos indices corretos (swDefaultTemplatePart/Assembly/Drawing = 8/9/10). Antes, o desenho era criado silenciosamente como uma peca.

Esbocos e desenho 2D -- OK

create_sketch, create_sketch_on_face, close_sketch, get_sketch_status, create_3d_sketch, draw_line, draw_line_3d, draw_circle, draw_rectangle, draw_arc, draw_polygon, add_sketch_dimension, add_sketch_relation

draw_profile (v5.18.0) e o caminho para qualquer curva calculada -- involuto, lei de came, dente de polia HTD, trocoide, aerofolio: desenha a cadeia inteira com o motor de inferencia desligado (SetAddToDB) numa unica chamada e confere a posicao de cada vertice lida de volta do SolidWorks. Marcada EXP pelo mesmo motivo que create_spur_gear (o caminho COM nao foi rodado nesta instalacao); a diferenca e que agora uma geometria deslocada aparece em displaced_points em vez de virar peca errada.

Correcao de premissa (v5.18.0): o risco do snap de esboco nao e "peca grande, feature pequena". O motor de inferencia junta um ponto novo ao ponto vizinho que ja existe quando os dois estao a poucos pixels -- logo o que decide e o espacamento entre pontos consecutivos do proprio perfil. Um flanco involuto amostrado a 0,3 mm colapsa numa engrenagem de 44 mm, onde nao ha peca grande nenhuma. Ver .claude/knowledge/verificacao_e_qa.md.

Features 3D -- OK

extrude_sketch, cut_extrude, revolve_sketch, sweep_sketch, loft_sketches, fillet_edges, chamfer_edges, shell_body, linear_pattern, circular_pattern, hole_wizard, list_features, delete_feature

cut_part_end (v5.21.0, medido ao vivo): corte de extremidade / mitra. Fatia uma peca de tubo/perfil com um plano (normal + offset ou point, em coordenadas da peca; origin permite dar o plano em coordenadas da montagem) e remove o lado para onde a normal aponta, deixando a ponta como UMA face plana inclinada que assenta face a face contra outro membro (banzo x perna, corrimao x guarda-corpo). Corta com um retangulo gigante no plano global que contem a normal, extrudado simetrico por toda a peca. A resposta traz volume antes/depois, caixa antes/depois, removed_mm3, end_on_plane (ponto mais distante ao longo da normal lido do solido) e cut_face_area_mm2. Limitacao: a normal tem de ser perpendicular a um eixo global (sem angulo composto); para mitrar uma ponta rente a uma parede o tubo bruto precisa de sobra de comprimento antes do corte.

Adicionada em 17/08/2026: ate esta versao nao havia forma de apagar uma feature de peca por nome (so existia delete_component para assembly). delete_feature seleciona por SelectByID2(nome, "BODYFEATURE", ...) e chama DeleteSelection2; por padrao tambem remove features dependentes (ex.: um weld member construido sobre um esboco 3D) para nao esbarrar no dialogo de confirmacao do SolidWorks, que travaria a chamada COM.

Operacoes de corpo / referencia

mirror_feature (OK), mirror_body (OK), move_copy_body (OK), create_reference_plane (OK), set_appearance (OK), set_material (EXP -- a densidade continua em 1000 kg/m3 (agua): confirmado ao vivo em 05/10/2026, mesmo com o .sldmat resolvido, cinco ordens de argumentos testadas e nome da configuracao ativa; o nome tambem le de volta vazio. Desde a v5.12.0 a ferramenta verifica pela DENSIDADE e falha com erro explicito em vez de reportar sucesso; measure_body devolve density_kg_m3 e avisa quando a massa esta em densidade de agua; lookup_material_properties le densidade/modulo/escoamento direto do .sldmat (peso = volume x densidade) como caminho correto enquanto a causa raiz -- no SolidWorks ou na instalacao, nao no codigo -- nao e encontrada), create_reference_axis (EXP -- InsertAxis2 depende de selecao valida), combine_bodies (EXP -- corpos precisam se tocar/interseccionar), split_body (EXP -- fluxo Pre/PostSplitBody), add_rib (EXP)

Engrenagens

create_spur_gear (EXP -- ver a ressalva abaixo)

A geometria do dente e testada: gear_geometry.py e Python puro e tests/test_gear_geometry.py tem 113 testes que conferem o involuto contra a sua propria definicao, a espessura pi*m/2 na circunferencia primitiva (a condicao de engrenamento), a tangencia do raio de pe, o fechamento do contorno e a prova de que ele nao pode se autointersectar. O que nao foi rodado nesta instalacao e o caminho COM: SetAddToDB(True) + umas 500 chamadas de CreateLine2 num unico esboco. Por isso EXP, e nao OK.

A propria ferramenta mede o resultado: compara o volume real do solido com o volume analitico do contorno e devolve verified, mais um teeth_present que existe so pra pegar o disco liso. Ou seja, se o caminho COM falhar nesta instalacao, a falha vem reportada em vez de silenciosa -- que era exatamente o problema. Para confirmar ao vivo: python tests/run_gear_live_test.py.

Montagem

insert_component (OK -- posicao conferida: devolve actual_position lido do SolidWorks, deviation e verified), verify_assembly_positions (OK), capture_assembly_pose (OK), restore_assembly_pose (OK), list_components (OK), fix_component, float_component, delete_component, suppress_component, unsuppress_component, list_mates, interference_check (OK), add_mate (EXP -- devolve a posicao dos dois componentes antes/depois, os graus de liberdade que a mate NAO trava, e geometry_check com o angulo medido entre as duas faces; align deixou de forcar swMateAlignALIGNED), add_advanced_mate (EXP), add_cam_follower_mate (OK), add_screw_mate (OK), add_rack_pinion_mate (OK), list_motion_studies (OK), create_motion_study (OK), create_assembly_pattern (EXP -- precisa de referencia de direcao), create_exploded_view (EXP), extract_assembly_data (OK)

Adicionada em 02/10/2026 para fluxos de extracao tipo BOM (ex.: pipelines de IA que precisam de quantidade, material, peso e dimensoes por peca): sem ela, um cliente precisa de list_components mais um get_custom_properties e um measure_body por componente. extract_assembly_data percorre os componentes de topo da montagem ativa, abre o IModelDoc2 de cada um (IComponent2.GetModelDoc2 -- chega como metodo ligado sob dynamic IDispatch e ja resolvido sob a typelib gerada; o valor pre-chamada e usado como fallback se a chamada em si falhar com membro-nao-encontrado) e le propriedades/massa no mesmo nivel padrao de get_custom_properties (config vazio = nivel do documento, nao a configuracao do componente na montagem), numa unica chamada. Tambem devolve bom: os mesmos dados agrupados por arquivo de origem com quantity computada, pronto para um backend montar a BOM/lista de corte de verdade. Falha por componente (sem material, suprimido, sem corpo) fica no errors daquele item em vez de derrubar a chamada inteira -- a logica interna de leitura de propriedades e medicao e a mesma de get_custom_properties/measure_body (extraida para _read_custom_properties/_measure_model_doc para as duas ferramentas nao divergirem com o tempo).

Propriedades / Medicao / Exportacao / Configuracoes -- OK

get_custom_properties, set_custom_property, measure_body, export_document, create_configuration, switch_configuration (resolve nomes localizados, ex. "Valor predeterminado")

Leitura de estado (tela, arvore, montagem) -- OK

Adicionado e validado ao vivo em 16/08/2026: get_view_state reporta o zoom (Scale2), o codigo bruto de modo de exibicao, a matriz de rotacao 3x3 da camera e -- quando ela bate exatamente com uma das 9 vistas nomeadas de set_view -- esse nome em closest_named_view (None quando o usuario girou o modelo livremente; testado ao vivo com uma rotacao manual para confirmar que nao ha falso-positivo). list_features passou a reportar suppressed e error_code por recurso, e list_components passou a reportar visible (independente de suppressed) via IComponent2.GetVisibility, confirmado por um teste de ida-e-volta ocultar/exibir. Nenhum destes numeros foi assumido: os valores de referencia das 9 orientacoes nomeadas e o mapeamento 0/1 de visibilidade foram capturados ao vivo antes de escrever o codigo.

Macros VBA -- OK

Adicionado em 16/08/2026 apos comparar este servidor com outros MCPs de SolidWorks publicos (todos expoem execucao de macro; este nao expunha). list_macro_methods inspeciona um .swp/.swb/.dll e lista os pontos de entrada sem executar nada, separando os procedimentos sem argumentos (os unicos que RunMacro2 consegue chamar) dos que exigem parametros. run_macro executa um procedimento; com module/procedure vazios ele resolve sozinho quando existe exatamente um ponto de entrada, e caso contrario lista as opcoes em vez de adivinhar.

Os filtros do swMacroMethods_e foram descobertos ao vivo, nao deduzidos dos nomes do enum: 1 = sem argumentos, 2 = com argumentos, e 0 -- que parece significar "todos" -- retorna None.

Seguranca: run_macro executa o VBA que estiver dentro do arquivo, com os privilegios da sessao do SolidWorks, sem sandbox. Use apenas macros confiaveis, e prefira list_macro_methods antes para ver o conteudo.

Perfis estruturais (weldments) -- OK, exceto add_end_cap

Validado ao vivo (SolidWorks 2025) com um membro em L + um membro cruzando-o, ambos em tubo quadrado ISO: create_3d_sketch, draw_line_3d, create_weldment_profile, add_gusset, trim_extend_structural. O caminho da biblioteca de perfis e resolvido em C:\ProgramData\SOLIDWORKS\...\weldment profiles\<padrao>\<tipo>.sldlfp (o tamanho e uma configuracao dentro do arquivo, descoberta automaticamente por create_weldment_profile a partir do nome pedido).

add_gusset funciona de forma confiavel no caso classico (uma face de viga + uma face de chapa/outra viga que se encontram numa aresta real); um canto chanfrado (miter) de uma unica peca em L e um caso mais ambiguo e pode precisar de um par de faces escolhido com mais cuidado.

add_end_cap (EXP -- defeito confirmado do SolidWorks 2025): apos corrigir um bug real do lado do MCP (a face certa era identificada mas depois descartada e re-selecionada por ray-casting a partir do ponto original, que cai exatamente na borda do vazio interno de um perfil oco -- agora a face identificada e selecionada diretamente), InsertEndCapFeature3 ainda retorna None em toda uma matriz de tentativas: os tres valores do enum de direcao, com/sem tratamento de canto, com uma ou duas faces selecionadas, com o documento salvo, e ate com os valores exatos do exemplo oficial da API da SolidWorks copiados literalmente. Mesmo padrao ja documentado abaixo para create_helix (InsertHelix).

Chapa metalica -- OK

Validado ao vivo (SolidWorks 2025): create_base_flange (o parametro PCBA exige um VARIANT de dispatch, nao bool -- corrigido), add_sheet_metal_bend (usa Insert Bends num corpo previamente casqueado com shell_body), add_sheet_metal_edge_flange (requer objetos de aresta, resolvidos a partir de um ponto conhecido na aresta), flatten_sheet_metal (alterna flat/folded).

Roscas / usinagem -- parcial

add_cosmetic_thread (EXP), add_thread_feature (delega para rosca cosmetica -- roscas 3D reais NAO sao expostas pela API do SolidWorks), create_helix (EXP -- InsertHelix retorna None via COM nesta versao), create_knurl (EXP -- Wrap+Deboss; desde a v5.18.0 desenha as celulas com a inferencia desligada e confere cada vertice: a celula tem 0,2 mm de largura com vertices a 0,1 mm, tres vezes mais apertado que o dente de engrenagem que colapsava, e a unica checagem era "o Wrap nao voltou None" -- uma celula achatada gravava nada e reportava sucesso. A PROFUNDIDADE gravada continua sem medicao: o Wrap nao expoe valor pra ler de volta, e o retorno diz isso).

Desenho tecnico detalhado -- parcial

add_drawing_annotation (OK), insert_drawing_view (OK -- validado ao vivo inserindo uma vista isometrica de uma peca de weldment; a nota anterior sobre CreateDrawViewFromModelView3 retornar None estava desatualizada), add_weld_symbol (OK -- validado ao vivo colocando um simbolo de solda de filete numa aresta da vista inserida). As demais sao EXP e dependem do gerenciador de propriedades ou de uma vista de modelo com estado especifico: insert_section_view, insert_detail_view, insert_broken_view, insert_auxiliary_view, add_drawing_dimension, add_centerline, add_surface_finish, add_gdt_symbol, add_balloon, insert_bom_table, insert_cut_list_table.

Notas de implementacao

extract_assembly_data nao via o material nativo (corrigido em 02/10/2026)

Num teste de ponta a ponta com o backend do Alfa Detail (POST real do resultado de extract_assembly_data contra a API rodando), toda peca que tinha material atribuido via set_material chegava como "sem material" do outro lado. Causa: set_material grava no slot nativo de material do SolidWorks (SetMaterialPropertyName2), que e separado do CustomPropertyManager -- extract_assembly_data so lia propriedades customizadas, entao nunca via esse material. extract_assembly_data agora le tambem o material nativo via GetMaterialPropertyName2 (o parametro de saida Database precisa de um VARIANT real por referencia, mesma familia de quirk ja documentada para OpenDoc6/ActivateDoc3/Save3 abaixo) e injeta como propriedade "Material" -- mas so como fallback, se o modelo ja tiver uma propriedade customizada Material explicita, essa continua valendo. Cobre os dois casos que o proprio PDF do Alfa Detail preve: "Material: get_custom_properties OU set_material".

OpenDoc6/ActivateDoc3 com erro de tipo COM (corrigido em 02/10/2026)

open_document e, por consequencia, insert_component (que reabre o componente e reativa a montagem internamente antes de inserir) passaram a falhar com Tipo nao correspondente (DISP_E_TYPEMISMATCH) nesta instalacao. Causa: _open_doc6/_activate_doc3 passavam inteiros simples (0, 0) para os parametros de saida (Errors/Warnings) de OpenDoc6/ActivateDoc3. Sob o binding COM atual desta maquina isso nao e aceito -- precisa de VARIANTs reais por referencia (VT_BYREF | VT_I4), exatamente o padrao que _save_doc3 ja usava para Save3. AddComponent5 (usado por insert_component) nunca teve bug proprio: o erro aparecia por causa da chamada anterior a _open_doc6/_activate_doc3 dentro do mesmo fluxo, nao da propria insercao. As duas funcoes agora tentam o VARIANT primeiro e caem para inteiros simples (except TypeError) se o binding ativo rejeitar o VARIANT, cobrindo os dois modos de binding como _save_doc3 ja fazia.

Reconexao apos o SolidWorks reiniciar (corrigido em 16/08/2026)

A checagem de conexao viva era _ = app.RevisionNumber. Com a typelib gerada (o caso do Python 3.14 aqui), RevisionNumber e um metodo, entao esse acesso so montava o objeto de metodo do lado do Python e nunca chegava a cruzar a fronteira COM -- um proxy de uma instancia do SolidWorks ja encerrada passava na checagem como se estivesse saudavel. O resultado era que, depois de fechar e reabrir o SolidWorks, todas as chamadas falhavam com "O servidor RPC nao esta disponivel", inclusive connect_solidworks, porque o caminho de reconexao nunca era alcancado. Agora _com_is_alive() invoca a chamada de fato, e o mesmo padrao de no-op foi corrigido no rebuild de shell_body.

Novas em v5.19.0 (caixa de engrenagens: o que o teste ao vivo mostrou)

Testado ao vivo no SolidWorks 2025 (API 33.4) montando uma caixa de dois estagios (relatorio: RELATORIO_CAIXA_ENGRENAGENS.md).

• create_spur_gear ganhou o que a caixa precisava (e create_gear, que delega a ele, repassa): phase gira o contorno dentado em torno do eixo — o motor fica em phase = 0 (dente sobre +X) e a engrenagem conduzida, do lado +X dele, usa phase = 180 + 180/dentes para ter um vao de frente para cada ponta de dente; sem isso duas engrenagens de dentes pares batem dente contra dente. keyway_width/keyway_depth abrem o rasgo de chaveta (lado +Y) com o mesmo primitivo a prova de snap, e o volume esperado da verificacao ja o desconta.

• draw_spline corrigido na API 33.4: CreateSpline3 le o array como triplas (x, y, z), nao pares. Com pares, 3 pontos viravam uma reta e 10 pontos um emaranhado de 139 mm. Agora envia x, y, 0.

• Aprendizado do teste ao vivo: um contorno so fecha se as extremidades forem numericamente identicas (arcos por seno/cosseno diferem do spline arredondado em ~5e-8 m, acima da resolucao de 1e-8 m, e corte/boss recusam). O create_spur_gear ja evita isso, pois desenha um unico contorno com a inferencia desligada.

Novas em v5.18.0 (a classe inteira, nao uma forma: 155 -> 157)

A v5.17.0 consertou uma forma. A analise do que mais sofria da mesma falha mostrou que o problema era outro, e maior.

1. O criterio documentado do snap estava errado. verificacao_e_qa.md dizia "peca grande, feature pequena". Mas a engrenagem saia lisa numa peca de 44 mm -- nao havia peca grande ali. O que o motor de inferencia junta e um ponto novo que cai a poucos pixels de um ponto que ja esta no esboco: o que decide e o espacamento entre pontos consecutivos do perfil, nao o tamanho da feature nem o da peca. Dente involuto amostrado a 0,3 mm num pinhao de 44 mm = 0,7% da vista, dentro do raio de snap em qualquer zoom normal. Isso reclassifica todo perfil que seja curva amostrada, nao so engrenagem.

2. draw_profile -- o primitivo que faltava. Recebe os pontos de uma curva calculada e desenha a cadeia inteira com a inferencia desligada, numa chamada (antes: 200 chamadas de draw_line pelo motor de inferencia, ou draw_spline, que verificava so as duas pontas). Depois le cada vertice de volta e compara: max_point_deviation, displaced_points com indice, verified. Perfil com segmento faltando nao volta, levanta erro -- perfil incompleto e perfil aberto. create_spur_gear foi refatorado para usar o mesmo primitivo, e agora recusa extrudar um perfil deslocado em vez de so avisar.

3. Tres falhas silenciosas achadas na auditoria, todas da mesma familia:

• create_knurl estava quebrado (ou a um zoom de estar): celulas de 0,2 mm com vertices a 0,1 mm desenhadas direto pelo SketchManager, e a unica verificacao era InsertWrapFeature2 != None. Uma celula achatada gravava nada e a ferramenta dizia sucesso. Agora desenha pelo primitivo e confere vertice por vertice.

• draw_spline verificava so as pontas -- justamente os dois pontos que o snap tem menos chance de mover. Um ponto de controle interior deslocado deixava as duas pontas certas e a curva deformada voltava verified: true. Agora le os pontos de controle de volta (interior_points); quando o SolidWorks nao os expoe, o retorno diz que o interior esta nao verificado, em vez de deixar as pontas passarem por prova.

• Canaletas de anel do create_automotive_piston: dois circulos a 3 mm um do outro, ambos pelo motor de inferencia. draw_circle ja media o proprio raio; ninguem lia. Agora le, e levanta erro se a canaleta saiu rasa ou colapsada.

4. create_gear virou delegacao. Um create_gear entrou na main em paralelo com este trabalho, construindo a engrenagem do jeito que se modela a mao: blank no diametro de topo, UM vao de dente involuto cortado, e circular_pattern desse corte. A aritmetica do involuto nele estava certa -- nao era bug de matematica. O que faltava eram as duas coisas desta versao: os flancos iam por CreateSpline3, ou seja pelo motor de inferencia (12 amostras num flanco de 4,5 mm = pontos a 0,4 mm, dentro do raio de snap), e a unica verificacao era "o pattern nao voltou None" -- um vao achatado, repetido 20 vezes, e um blank, e nada olhava. O nome continua (quem ja chamava create_gear nao quebra, e os argumentos e as chaves de retorno antigas seguem iguais), mas agora ele chama create_spur_gear. tooth_gap_feature volta None: nao existe corte-semente pra nomear, porque os dentes nao sao feitos cortando um.

5. Posicao das pecas na montagem. create_automotive_piston_assembly nao tem mates por projeto -- os cinco offsets sao a unica coisa que posiciona as pecas. O insert_component ja devolvia actual_position/deviation/verified de cada uma, lido do SolidWorks; nada lia. Agora cada colocacao e conferida, a ferramenta levanta erro se alguma peca nao chegou onde foi posta, e o retorno traz component_positions com a pose medida de todas. O position_check tambem diz o que esperar do verify_assembly_positions aqui: M01 nos cinco (montagem deliberadamente sem mates) e M03 em connecting_rod/wrist_pin/bearing, que sao modeladas no lugar e compartilham a origem de insercao de proposito.

Novas em v5.17.0 (a engrenagem tem dentes, 154 -> 155)

O sintoma: toda engrenagem modelada aqui saia lisa. Um cilindro com furo.

Nao era um bug, era a aritmetica. Um flanco involuto precisa de uma duzia de pontos a decimos de milimetro um do outro. Toda chamada draw_* passa pelo motor de inferencia do SolidWorks, cujo raio de snap e medido em pixels de tela (ver "O esboco e onde o erro nasce" em .claude/knowledge/verificacao_e_qa.md), e dois pontos em escala de dente, um do lado do outro, e exatamente o que esse motor junta -- movendo o ponto, sem erro nenhum. O perfil do vao de dente chegava degenerado ao cut_extrude, e um vao achatado repetido 20 vezes pelo circular_pattern e um disco de novo. Nenhuma das 154 ferramentas avisava: validate_model passava, measure_body devolvia uma massa plausivel, e a peca era entregue como engrenagem.

O conserto: create_spur_gear. O contorno inteiro -- todos os dentes, fechado -- e calculado analiticamente em gear_geometry.py (ISO 53, altura cheia: adendo 1,0m, dedendo 1,25m, 20 graus, sem correcao de perfil) e desenhado como um perfil com o motor de inferencia desligado (SetAddToDB), depois extrudado uma vez. Sem corte, sem padrao, nada pra snapar. Inclui raio de pe tangente (0,38*m, o raio de ponta do cremalheira da ISO 53), furo de eixo opcional e a distancia entre centros pro par engrenar.

E ele se mede. A secao transversal exata do contorno e conhecida, entao o volume real do solido extrudado e comparado com ela: verified so vem true quando fecham dentro de volume_tolerance, e teeth_present e uma checagem separada e mais grosseira de que o material dos vaos saiu mesmo do blank -- essa e a que pega "saiu lisa". Nao da pra uma engrenagem sair lisa e ser reportada como pronta.

Limites declarados na docstring: so engrenagem cilindrica de dentes retos, externa, sem correcao de perfil. Helicoidal, interna, conica, coroa/rosca sem fim e chanfro de topo ficam de fora -- e, como sempre, nao ha FEA aqui pra conferir resistencia do dente.

Novas em v5.17.0 (contexto para a IA: resource novo + descricoes corrigidas)

As tres versoes anteriores criaram uma camada de medicao inteira — verified, snapped, moved, deviation, measurement_method, components_moved — e nada explicava ao cliente como ler esses campos. Um verified: null lido como sucesso reintroduz exatamente o problema que a medicao resolve.

solidworks://knowledge/campos-de-verificacao (resource novo, 13 no total). Registrado primeiro na lista, porque e o unico que vale para qualquer pedido: fala do RETORNO DAS FERRAMENTAS, nao de engenharia. Cobre o contrato (requested_* vs actual_*), por que verified: false e verified: null sao coisas diferentes, o que fazer com cada campo especifico, as cinco armadilhas confirmadas (snap de esboco em espaco de tela, alinhamento de mate forcado, primeiro componente ancorado, dimensao de feature reduzida sem erro, pose de mecanismo que nenhuma mate segura) e — deliberadamente — a lista do que ainda nao foi validado ao vivo, para que nada disso seja citado como garantia.

Duas descricoes de resource estavam desatualizadas, e isso e pior do que parece: a descricao e o que o modelo usa para decidir se abre o resource, entao uma descricao que nao menciona uma secao garante que aquela secao nunca seja lida. montagens-mecanicas-reais nao falava de mecanismo, motion study nem add_advanced_mate; verificacao-e-qa nao falava do snap de esboco. Corrigidas.

Testes de resource, que nao existiam. 19 novos, entre eles: todo arquivo em .claude/knowledge/ tem de estar registrado (um arquivo nao registrado alcanca o Claude Code neste repo e mais nada — do Claude Desktop, .claude/ e invisivel e os resources sao tudo), todo resource registrado aponta para um arquivo que existe, toda descricao tem corpo, o resource novo cobre cada campo que as ferramentas devolvem, e ele admite o que nao foi provado.

Novas em v5.16.0 (movimento: a mate de mecanismo conferida)

A correcao de alinhamento da v5.14.0 estava incompleta, e isso explica o sintoma: modelagem estatica saia bem, movimento saia torto.

1. O add_advanced_mate ainda forcava ALIGNED. A v5.14.0 trocou o literal 0 do segundo parametro do AddMate5 (swMateAlign_e) por um align configuravel no add_mate, e deixou o literal 0 identico no add_advanced_mate. Acontece que add_advanced_mate e justamente a ferramenta com que um mecanismo e construido: e dela que saem distance, angle, gear, width, symmetric e lock. Montagem estatica usa add_mate (corrigido); mecanismo usa add_advanced_mate (nao corrigido) — por isso o movimento saia torto e o modelo parado nao. Agora ele tem o mesmo align ('aligned' | 'anti_aligned' | 'closest', default).

2. Nenhuma das 4 mates de mecanismo dizia onde deixou as pecas. Uma mate nao recebe uma posicao: recebe uma relacao, e a posicao e a consequencia. Quando ela resolve, o SolidWorks arrasta o que ainda esta livre ate a configuracao permitida — correto, e exatamente onde nasce o "pedi movimento e saiu fora de posicao". add_advanced_mate, add_cam_follower_mate, add_screw_mate e add_rack_pinion_mate agora devolvem components com position_before, position_after e moved.distance de cada componente pego. As mates que acoplam dois graus de liberdade (gear, parafuso, pinhao) fixam so a razao entre eles e deixam os dois livres: criar a mate desliza a peca ate onde o acoplamento fecha, e esperar que ela fique onde estava e o erro.

3. Criar/ativar motion study pode mover a montagem, sem registro. O MotionManager troca a montagem para o estado do estudo, e o SolidWorks nao guarda a pose anterior em lugar nenhum — e a forma mais provavel de perder uma pose de mecanismo que deu trabalho. create_motion_study agora mede: components_moved (pior primeiro) e pose_preserved. O fluxo certo e capture_assembly_pose(filepath=...) antes, e restore_assembly_pose se o relatorio mostrar movimento indesejado.

Todas as quatro trazem mechanism_note: nenhuma mate segura um grau de liberdade livre, porque o grau livre e o movimento — quem torna a pose reproduzivel e capture_assembly_pose/restore_assembly_pose, nao outra mate.

Novas em v5.15.0 (geometria de peca conferida, 153 -> 154)

A v5.14.0 consertou a camada de montagem. A de peca continuava 100% eco: auditoria com AST de todo o server.py achou 153 chaves de coordenada ou dimensao em 86 ferramentas, 95 delas eco (o valor devolvido vinha dos parametros), contra 9 que liam algo de volta — e cinco dessas nove eram so o titulo do documento. O desvio nasce no esboco, e naquele momento ninguem podia olhar.

1. O snap de esboco e em espaco de TELA, e move a geometria. Toda chamada Create* do ISketchManager passa pelo motor de inferencia do SolidWorks, cujo raio de snap e uma distancia em pixels. Medido ao vivo numa peca de 1,74 x 1,80 x 1,50 m: um retangulo de 40 x 20 mm foi recusado no zoom que enquadrava a peca inteira (CreateCornerRectangle devolveu null), enquanto CreateLine, que nao passa por esse caminho, funcionou no mesmo zoom; a mesma chamada de retangulo funcionou depois de aproximar o zoom. Essa e a falha ruidosa. A silenciosa e pior: quando o snap apenas desloca um ponto para um vertice vizinho, a chamada tem sucesso e devolve um segmento valido no lugar errado.

• As 8 primitivas (draw_line, draw_centerline, draw_circle, draw_rectangle, draw_arc, draw_polygon, draw_spline, draw_line_3d) agora leem o segmento criado de volta e devolvem actual, deviation, verified e snapped — a geometria foi criada e o SolidWorks a colocou em outro lugar. O draw_rectangle devolvia width = abs(x2 - x1): aritmetica nos proprios argumentos, zero contato com o modelo. Agora ha actual_width/actual_height/actual_corners, medidos dos quatro segmentos.

• A recusa ruidosa deixou de mentir. A mensagem era "Is a sketch active?" com o esboco aberto o tempo todo; agora o esboco e checado primeiro, a recusa e reportada como o que e, e ha uma tentativa de retry com zoom na area alvo (reportada em zoom_retry).

• list_sketch_entities (nova, somente leitura) e o equivalente do get_component_transform no nivel de peca: tipo, pontos, centro, raio e se e geometria de construcao, de cada segmento. Sem ela nao havia como perguntar onde a geometria de esboco foi parar — GetSketchSegments aparecia uma unica vez em 12.300 linhas, enterrada dentro do create_weldment_profile.

2. A primeira peca da montagem e ancorada, e ninguem avisava. O SolidWorks fixa o primeiro componente inserido. Uma peca fixa nunca se move: toda mate contra ela e resolvida movendo a outra. O insert_component nunca lia IsFixed, entao a IA matava a peca principal esperando que ela se alinhasse, via a outra se mover, e concluia que a peca principal "nao muda de posicao". Agora o retorno traz fixed e, quando verdadeiro, o aviso com a consequencia e o float_component como saida.

3. O SolidWorks reduz dimensao que nao cabe, sem erro. Todas as ferramentas de feature checavam if feat is None e nada mais — a falha ruidosa coberta, o desvio silencioso descoberto. fillet_edges, chamfer_edges, shell_body, extrude_sketch e cut_extrude agora leem a dimensao de volta (actual_radius, actual_distance/actual_angle, actual_thickness, actual_depth) com measurement_method dizendo por qual rota foi lida.

4. move_copy_body devolvia a translacao pedida. Agora mede a caixa envolvente antes e depois (measured_center_shift). So verifica no caso sem ambiguidade (translacao pura, copy=False, sem rotacao); com rotacao ou copia a caixa muda de forma e verified vem None com verification_skipped dizendo por que, em vez de um alarme falso.

5. joint_centers do pistao prometia garantia que nao tinha. Era aritmetica nos argumentos publicada sob uma chave chamada contract, afirmando que os dois mancais e o pino realmente estavam ali. Agora traz measured: false e design_intent dizendo que foi calculado, nao medido.

Novas em v5.14.0 (posicao de montagem conferida + mecanismos, 150 -> 153)

Tres bugs distintos de posicionamento, e o caso de montagem com movimento.

1. Peca multi-corpo era inserida fora do lugar. A correcao de origem do insert_component (que compensa o AddComponent5, que posiciona o CENTRO da caixa envolvente no ponto pedido, nao a origem) media a caixa de bodies[0] apenas. Toda estrutura soldada e todo perfil estrutural tem mais de um corpo, e a caixa do primeiro corpo descreve so um pedaco da peca: a peca saia deslocada pela diferenca entre as duas caixas. Agora a caixa e a uniao de todos os corpos solidos.

2. O alinhamento da mate era forcado em toda chamada. O segundo parametro do AddMate5 e swMateAlign_e (ALIGNED=0, ANTI_ALIGNED=1, CLOSEST=2) e estava fixo em 0 — forcando ALIGNED independentemente da geometria. Para duas faces feitas pra se encarar (duas faces planas pressionadas, eixo contra ombro), ALIGNED e a solucao errada; o SolidWorks nao reporta erro, porque e uma solucao matematicamente valida, so nao e a que encaixa. Era a causa da "brecha torta" sem erro nenhum. add_mate agora tem align ('aligned' | 'anti_aligned' | 'closest', novo default) e devolve geometry_check com o angulo real medido entre as direcoes de referencia das duas faces, em coordenadas da montagem.

3. Nenhuma ferramenta de posicionamento conferia o proprio resultado. Devolviam os parametros de entrada de volta (padrao "eco"), entao uma peca no lugar errado era indistinguivel de sucesso. Agora insert_component e set_component_transform leem a pose de volta do SolidWorks e devolvem requested_position ao lado de actual_position, deviation e verified; get_component_transform rotula a convencao da matriz (rotation_convention: "row-major") pro chamador nao adivinhar. verify_assembly_positions (nova) e o gate de montagem, no formato do verify_drawing: M01 nem fixa nem matada, M02 sobre a origem, M03 duas pecas na mesma posicao, M04 fixa e matada ao mesmo tempo, M05 posicao ilegivel, M06 peca declarada movel mas fixa.

4. Montagem com movimento perdia as posicoes. Uma montagem estatica guarda a posicao de graca: tudo nela e fixo ou totalmente matado, e um rebuild devolve cada peca ao mesmo lugar. Um mecanismo nao pode funcionar assim — suas pecas moveis sao sub-restringidas de proposito, e esse grau de liberdade livre e o movimento. A pose em que ele esta e uma de infinitas validas, e o proximo drag, rebuild ou motion study a substitui sem registrar qual era. Nao e um bug de mate: nenhuma mate pode travar um grau de liberdade que deve ficar livre.

• verify_assembly_positions ganhou moving_components: os nomes das pecas que devem se mover. Sem isso, cada uma delas dispara M01, porque estar sub-restringida e exatamente o que uma peca movel e. Declaradas, ficam isentas de M01 e passam a ser checadas pelo problema oposto (M06: fixa quando deveria estar livre).

• capture_assembly_pose / restore_assembly_pose (novas): gravam a pose exata de cada componente e a colocam de volta. Guardam a matriz de rotacao 3x3 que o SolidWorks reporta e a translacao em metros — sem conversao pra angulo de Euler, porque decompor e recompor nao e exato e uma pose de mecanismo tem que voltar exata. Com filepath, a pose vira um JSON e sobrevive a sessao (varios arquivos = varias posicoes do mesmo mecanismo). O restore mede o resultado: se uma mate arrastar o componente no rebuild, isso aparece como deviation em vez de sucesso limpo.

Novas em v5.12.0 (7 ferramentas, 143 -> 150)

• Camada de leitura/verificacao de desenho (modulo alfa_drawing.py, sem COM, testado em Linux): get_drawing_layout, get_view_entities, get_view_dimensions, dimension_by_entity_ids (cota por entidade, com expected_mm e erro E01 se medir outra coisa) e verify_drawing (relatorio estruturado de cobertura de cotas, sobreposicao, escala). Validado ao vivo 29/29 em tests/run_drawing_live_test.py.

• extract_assembly_bom: BOM recursiva (todos os niveis), chave (arquivo, configuracao), ignora suprimidos/excluidos. extract_assembly_data fica mantida para compatibilidade, marcada como substituida.

• lookup_material_properties: propriedades lidas do .sldmat.

Arquitetura

• Todas as chamadas COM rodam em uma unica thread dedicada (COM/STA).

• Timeout de 120s por operacao COM; limpeza automatica no shutdown.

• Late binding (dispatch dinamico) -- igual ao ambiente do Claude Desktop.

Camada de metodologia (design-sandbox): instructions, resource e prompt

As 157 ferramentas sao primitivas; sozinhas nao ensinam a IA a projetar bem. O servidor expoe as outras duas primitivas do protocolo MCP para cobrir essa lacuna, codificando o metodo ja validado nas replicas de engenharia deste projeto (ver RELATORIO_TESTES.md) em vez de depender de disciplina manual a cada conversa:

• instructions do FastMCP(...): injetado automaticamente pelo cliente MCP ao conectar. Resume o loop planejar -> isolar -> construir incremental -> validar (measure_body/validate_model) -> inspecionar visualmente (capture_standard_views) antes de avancar.

• Resource solidworks://tool-status: reexpoe a secao "Status de verificacao" deste README (fonte unica, lida em tempo real -- sem duplicar o conteudo) para a IA saber quais ferramentas sao OK vs. EXP antes de depender de uma delas.

• Prompt design_from_reference(part_description, key_dimensions, reference_source): roteiro passo a passo para projetar uma peca nova a partir de uma referencia real, formalizando o processo usado nas 5 replicas de engenharia (bucha, rolamento, polia, clevis, helice).

Base de conhecimento de engenharia (.claude/) -- adicionada em 03/10/2026

.claude/CLAUDE.md + .claude/knowledge/*.md sao a convencao de projeto do Claude Code -- invisiveis para um cliente que so fala MCP (o caso normal de uso deste servidor: Claude Desktop com a extensao instalada). Os mesmos arquivos agora sao expostos tambem como resources solidworks://knowledge/index + solidworks://knowledge/<topico> (materiais, tolerancias-e-ajustes, gdt, elementos-de-maquina, chapa-metalica, soldas-e-perfis-estruturais, processos-de-fabricacao, verificacao-e-qa, roteiro-projetista, montagens-mecanicas-reais -- este adicionado em 04/10/2026 --, engrenagens -- adicionado em 06/10/2026) -- mesma fonte, lida ao vivo, para os dois clientes nunca divergirem. Cobrem o que a IA precisa saber pra projetar como um projetista/engenheiro de verdade (nao so "como chamar a ferramenta"): material certo por aplicacao, ajuste ISO entre furo e eixo, GD&T, dimensao de parafuso/rolamento/chaveta padronizado, regras de chapa dobrada e de weldment, DFM por processo de fabricacao, e um checklist de verificacao antes de entregar a peca -- incluindo o que fazer quando pedem confirmacao de resistencia (nao ha FEA neste MCP; ver verificacao-e-qa).

Descoberta do SolidWorks

• _find_solidworks_exe le HKLM\SOFTWARE\SolidWorks\SOLIDWORKS <ano>\Setup\ SolidWorks Folder e cobre o layout novo de pastas (...\SOLIDWORKS\ sem ano, e SOLIDWORKS (2) para instalacoes lado a lado).

Planos localizados

• Nomes de planos padrao sao resolvidos pela posicao na arvore (1o/2o/3o RefPlane), nao por texto em ingles.

Unidades

• Distancias/raios sao convertidos para metros antes de qualquer chamada COM.

Proximos passos para "producao completa"

As ferramentas EXP sao os proximos alvos.

Alvos da lista original, ja concluidos (validados ao vivo, hoje OK):

1. insert_drawing_view (desbloqueia toda a prancha de desenho -- categoria E).

2. create_weldment_profile (estruturas de plataformas/tanques).

3. create_base_flange (tanques de chapa).

Alvos atuais (v5.12.0), por impacto:

1. set_material -- densidade nao aplicada (afeta peso de toda BOM). Proximo passo: aplicar material a mao (Editar Material) e ver se a densidade muda; se nao mudar, o defeito e da instalacao. Contorno: lookup_material_properties.

2. Desenho tecnico EXP -- add_drawing_dimension, insert_section_view, insert_detail_view, add_balloon, insert_bom_table, insert_cut_list_table.

3. add_end_cap e create_helix -- retornam None via COM no SolidWorks 2025 (defeito do lado do SolidWorks; investigar alternativa). Recomenda-se validar cada fluxo gravando uma macro VBA na versao alvo e espelhando a sequencia exata de selecao/chamada COM.