CLI_Revit

Harness MCP eficiente em tokens para automação Revit/BIM — pesquise e execute mais de 160 scripts em vez de expor ferramentas individualmente.

GitHub
1
Experimente este MCPPatrocinado

Documentação

CLI Revit / Sin Tool

Repositório mínimo para operar o Revit com a menor intermediação possível entre o LLM e a API.

O que é este repositório

CLI_Revit é um harness local de automação para o Revit.

Mais concretamente:

  • conecta um agente ou LLM a um modelo aberto no Revit
  • permite descobrir, parametrizar e executar scripts BIM reutilizáveis
  • expõe uma superfície shell-first por revit_cli.py e uma superfície MCP por mcp_server.py
  • mantém uma camada mínima de intermediação entre o agente e a API do Revit

Não é apenas um plugin, nem apenas uma biblioteca, nem apenas um servidor MCP. O MCP é uma interface de acesso a mais; o núcleo do repositório é o harness de execução e automação sobre o Revit.

Quickstart

Requisitos mínimos:

  • Revit 2023/2024/2025 instalado (para RevitAPI.dll/RevitAPIUI.dll)
  • .NET SDK ou Visual Studio 2022/Build Tools + .NET Framework 4.8 targeting pack
  • Python 3.8+ x64
  • pip install websocket-client mcp

Passos:

# 1. compilar e instalar el plugin de Revit (detecta version instalada)
cd plugin
build_all_versions.bat
cd ..

# 2. abrir Revit con un documento activo
#    el plugin RevitAgent levanta el servidor WebSocket solo, en ws://localhost:18789

# 3. verificar conexion
python revit_cli.py doctor
python revit_cli.py ping

# 4. primer comando real
python revit_cli.py search "muros"
python revit_cli.py show get_elementos
python revit_cli.py run get_resumen_modelo --params-json "{\"detalle\":\"minimo\"}"

Se ping responder DOWN: o Revit não está aberto, o .addin não foi instalado, ou falta configurar PYTHONNET_PYDLL — detalhes completos em plugin/README.md.

Para usar a partir de um agente em vez do shell (Claude Code, OpenCode, ou qualquer cliente MCP): o repositório já traz .mcp.json e mcp_server.py prontos, ver seção "Uso a partir do Claude Code" abaixo.

Harness vertical, não genérico

Mesmo padrão de um harness genérico (Claude Code, OpenCode, dsh): loop de agente + intermediação mínima entre decisão e execução + feedback estruturado para verificação. A diferença é o escopo:

  • um harness genérico decide seu domínio por prompt/contexto
  • este harness tem o domínio hardcoded no protocolo: catálogo de scripts, convenção get_/crear_/modificar_, contrato RESULTADO: OK|WARN|ERROR

Por isso é exposto via MCP e não como plugin nativo de cada harness geral: o harness vertical é mantido uma única vez neste repositório, e qualquer harness geral o consome como cliente MCP sem reescrita.

Mapa rápido

  • docs/INICIO_BIM.md: porta de entrada para uma sessão de modelagem BIM do agente
  • README.md: guia do repositório e estado atual de desenvolvimento
  • docs/DESARROLLO_REPO.md: guia para continuar o repositório por capacidades BIM, não por acúmulo de scripts
  • docs/CAPACIDADES_BIM.md: matriz curta de capacidades cobertas, parciais, ausentes e prioridades ativas
  • docs/SCRIPTS_BASE.md: núcleo operativo do repositório e regras para tocar scripts base
  • hints.md: caderno operativo curto e corrigível
  • CONTRIBUTING.md: critério de aceitação de PRs e convenções de scripts
  • LICENSE / NOTICE / AUTHORS: licença Apache-2.0 e créditos
  • revit_cli.py: entrypoint shell-first para buscar e executar scripts
  • revit_client.py: cliente WebSocket mínimo para executar Python raw
  • plugin/: add-in C# local do Revit (RevitAgentPlugin) para compilar e instalar o servidor WebSocket

Critério de design

A regra central deste repositório é simples:

  • cada tarefa BIM deve consumir a menor quantidade de tokens possível para chegar a uma resposta boa
  • os tokens devem ir para ler estado real do modelo, decidir e verificar
  • não devem ir para contexto inflado, routing local, wrappers redundantes ou documentação longa

Na prática, isso significa:

  • cliente para o Revit pequeno e óbvio
  • scripts explícitos e reutilizáveis
  • hints curtos em vez de uma camada de tools
  • poucas peças base, não catálogos grandes de variantes

Fórmula de trabalho:

leer poco -> decidir bien -> mutar chico -> verificar -> guardar solo la regla util

Guia de uso

Em uma sessão nova:

  1. ler docs/INICIO_BIM.md
  2. ler hints.md
  3. executar python revit_cli.py doctor
  4. ir para README.md apenas se precisar de contexto do repositório ou decisões de arquitetura
  5. fazer uma leitura mínima real do modelo antes de mutar

Regras de trabalho:

  • se já existe um script útil, buscá-lo e executá-lo com PARAMS
  • se o pedido é uma variante pequena, ajustar o script existente antes de criar outro
  • criar um script novo apenas quando abrir uma capacidade reutilizável de verdade
  • não salvar um script novo para uma decisão pontual de modelagem
  • se o pedido admite várias soluções BIM razoáveis e o critério não está dito, consultar antes de fixar uma variante permanente

Uso rápido

A ideia de revit_cli.py não é substituir o LLM, mas evitar que ele tenha que reescrever Python completo para cada consulta.

Exemplos:

python revit_cli.py doctor
python revit_cli.py ping
python revit_cli.py search "resumen del modelo"
python revit_cli.py show get_elementos
python revit_cli.py run get_resumen_modelo --params-json "{\"detalle\":\"minimo\"}"
python revit_cli.py run crear_muros --params-json "{\"segmentos_m\":[[[0,0],[5,0]]],\"nivel_inicial\":\"Nivel 1\",\"altura_default_m\":3.0}"

Launcher local único para Codex

Se você for usar Codex com modelo local a partir deste repositório, o entrypoint passa a ser:

.\codex-local.ps1 -Model qwen
.\codex-local.ps1 -Model gemma

Launchers equivalentes para outros CLIs locais:

.\hermes-local.ps1 -Model qwen
.\opencode-local.ps1 -Model qwen

Nota:

  • hermes-local.ps1 exige contexto mínimo de 65536; qwen3-coder-30b-q4 e gemma4-26b-a4b-q4km ficam configurados para esse objetivo nos launchers locais.

Regras do launcher:

  • vive em CLI_Revit, não depende de proj-agent-local
  • resolve os GGUF em C:\Users\fmg\local_models
  • resolve llama-server.exe em C:\Users\fmg\local_models\llama.cpp\llama-server.exe
  • se necessário, permite override por PROJ_AGENT_MODEL_PATH, PROJ_AGENT_LLAMA_SERVER_EXE ou .codex/local-model-paths.json

Para escolher um perfil exato sem usar alias:

.\codex-local.ps1 -Profile qwen3-coder-30b-q4
.\codex-local.ps1 -Profile gemma4-26b-a4b-q4km

Uso a partir do Claude Code

Agora o repositório também inclui um servidor MCP local para que o Claude possa usar os scripts existentes sem sair do fluxo normal do projeto.

Arquivos:

  • mcp_server.py: servidor MCP sobre stdio que reutiliza revit_cli.py e revit_client.py
  • .mcp.json: configuração de projeto para Claude Code
  • .claude/settings.json: permissões pré-aprovadas apenas para ferramentas seguras de descoberta e consulta

Fluxo mínimo:

  1. ter o Revit aberto com o plugin RevitAgent levantado
  2. abrir este repositório a partir do Claude Code
  3. aprovar o servidor revit-agent quando o Claude detectar .mcp.json
  4. usar ferramentas MCP como search_scripts, show_script e run_script

Notas curtas:

  • o catálogo completo de scripts/ fica oculto atrás de search_scripts, show_script e run_script
  • as tools MCP aceitam timeout e max_output_bytes; se uma saída exceder o limite, o plugin devolve preview e salva a saída completa em .revit_cli/artifacts
  • o plugin aceita requests paralelas de CLI/MCP/WebSocket, mas as executa em fila FIFO dentro do thread principal do Revit
  • o servidor carrega o catálogo ao iniciar; se você adicionar scripts novos, reinicie o Claude ou recarregue o servidor
  • as tools de mutação não ficaram pré-autorizadas em .claude/settings.json; a ideia é manter permissões conservadoras sobre o modelo
  • run_script executa qualquer script por nome ou caminho relativo sem inflar o catálogo visível de tools

Fluxo operativo

Arquitetura mínima:

LLM / cliente
    -> revit_cli.py o revit_client.py
    -> ws://localhost:18789
    -> plugin RevitAgent (C# + Python.NET)
    -> Autodesk.Revit.DB

revit_cli.py é a porta de entrada normal.

revit_client.py serve para executar Python raw quando é preciso controle total ou para prototipar uma peça nova antes de transformá-la em script reutilizável.

O transporte WebSocket é compatível com uso concorrente: vários clientes podem enviar requests ao mesmo tempo. O Revit continua single-threaded, então o plugin as enfileira em FIFO e as executa sequencialmente em ExternalEvent. As respostas incluem diagnostics com tempos de fila/execução e bytes de saída.

Arquivos principais

  • revit_client.py: cliente WebSocket mínimo para o Revit
  • revit_cli.py: buscador/runner mínimo para reutilizar scripts existentes
  • docs/DESARROLLO_REPO.md: critério de roadmap e foco do repositório
  • docs/CAPACIDADES_BIM.md: matriz acionável de capacidades BIM e prioridades
  • docs/SCRIPTS_BASE.md: lista de scripts base e critério de cuidado do núcleo
  • plugin/: código-fonte, build e instalação do plugin local do Revit
  • hints.md: caderno operativo curto e corrigível
  • .revit_cli/: estado local mínimo entre sessões (last_run.json + history.jsonl)
  • scripts/consulta: leituras do modelo
  • scripts/creacion: ações de modelagem
  • scripts/modificacion: ajustes sobre elementos existentes, tags e mudanças de documentação em vistas
  • scripts/reportes: saídas técnicas persistentes e exportações

Regra de nomes

O nome do script deve refletir seu contrato operativo real, não apenas a intenção de negócio.

  • get_*: leitura do modelo, sem mutação nem artefato persistente
  • crear_*: cria elementos novos no modelo
  • modificar_* ou verbo de mudança (mover_*, aplicar_*, etiquetar_*, reubicar_*): muta elementos ou vistas existentes
  • exportar_*: gera saída externa persistente (PDF, imagem, etc.)
  • generar_reporte_* / generar_memoria_*: gera documento técnico persistente

Se um script misturar dois contratos, deve ser dividido ou ficar claramente enviesado para um e expor alias de compatibilidade.

Plugin local

Este repositório já inclui o plugin necessário para que o runtime seja autossuficiente:

  • código-fonte em plugin/
  • projeto .NET em plugin/RevitAgentPlugin.csproj
  • build local em plugin/build.bat
  • build multi-versão em plugin/build_all_versions.bat
  • documentação operativa em plugin/README.md

Fluxo mínimo:

cd plugin
build_all_versions.bat

Se você só precisa de uma instalação pontual e build.bat detecta bem sua versão do Revit:

cd plugin
build.bat

Notas curtas:

  • o plugin instala o servidor em ws://localhost:18789
  • editar_boceto_muro.py pode aproveitar RevitEditScopeHelpers do assembly do plugin
  • o detalhe de requisitos (dotnet, net48, PYTHONNET_PYDLL, Addins por versão) vive em plugin/README.md

Protocolo raw

Request:

{
  "action": "execute",
  "script": "codigo python aqui",
  "timeout_s": 60,
  "request_id": "opcional",
  "max_output_bytes": 262144,
  "artifact_dir": "C:\\Users\\fmg\\Desktop\\CLI_Revit\\.revit_cli\\artifacts"
}

timeout_s, request_id, max_output_bytes e artifact_dir são opcionais. max_output_bytes usa 256 KB por padrão; se exceder, result/traceback contém um preview e a saída completa fica como artefato local.

Response OK:

{
  "status": "ok",
  "request_id": "opcional",
  "result": "stdout capturado o OK",
  "artifacts": [],
  "diagnostics": {
    "elapsed_ms": 12,
    "queue_wait_ms": 2,
    "execution_ms": 5,
    "output_truncated": false
  }
}

Response Error:

{ "status": "error", "error": "mensaje", "traceback": "stacktrace" }

Variáveis disponíveis em cada script:

  • doc: Autodesk.Revit.DB.Document
  • uidoc: Autodesk.Revit.UI.UIDocument
  • app: Autodesk.Revit.ApplicationServices.Application

Regras do ambiente

  • devolver resultados com print(), não pela última expressão
  • não usar with Transaction(...); abrir e fechar a transação manualmente
  • o Revit trabalha em pés decimais; converter unidades de forma explícita
  • se uma API pedir IList<T>, usar List[T] do .NET, não list do Python
  • FamilySymbol.Activate() deve ocorrer dentro de uma Transaction
  • ToElements() convém envolvê-lo com list() antes de usar slicing

Contrato de saída mínima

Para não inflar contexto, a saída dos scripts deve ser pensada para decisão operativa, não para narração.

  • python revit_cli.py run ... agora usa --output-mode auto por padrão: se detectar *_JSON= ou stdout longo, compacta a resposta.
  • se precisar ver todo o stdout, usar python revit_cli.py run ... --output-mode raw
  • emitir sempre uma linha de status curta: RESULTADO: OK|WARN|ERROR ou RESULTADO=ok
  • emitir métricas-chave em maiúsculas: TOTAL_VISTAS, COUNT_FILTRADAS, ELEMENT_IDS, etc.
  • se precisar de detalhe estruturado, emiti-lo em uma única linha NOMBRE_JSON=...
  • limitar detalhe humano com max_detalle; o detalhe completo deve ficar opt-in, não por padrão

Regra prática:

1 linea de estado
+ 3 a 8 metricas utiles
+ 0 o mas payloads *_JSON compactables
+ tablas o detalle solo si cambian una decision

Padrão de transação:

from Autodesk.Revit.DB import Transaction

txn = Transaction(doc, "Operacion")
txn.Start()
try:
    # cambios
    txn.Commit()
except Exception:
    txn.RollBack()
    raise

Conversões

  • metros -> pés: valor_m * 3.28084
  • pés -> metros: valor_ft * 0.3048

Verificar conexão

from revit_client import ping
print("Conectado:", ping())

O que não queremos reconstruir

  • tool_catalog.py
  • prepare-request
  • routing interno
  • RAG ou memória automática complexa
  • um agente de preferência
  • documentação grande difícil de corrigir

Estado do repositório

Estado atual:

  • o fluxo shell-first já existe e funciona desde revit_cli.py
  • doctor valida conexão, metadados mínimos e smoke tests de busca
  • run deixa um rastro local pequeno em .revit_cli/ para retomar entre sessões sem inflar o repositório
  • o plugin do Revit já vive dentro deste repositório e pode ser compilado a partir de plugin/
  • há uma base ampla de scripts reutilizáveis em scripts/consulta, scripts/creacion, scripts/modificacion e scripts/reportes
  • hints.md já cumpre o papel de memória operativa curta
  • a nova separação documental deixa um ponto de entrada BIM (docs/INICIO_BIM.md) e este README como guia viva do repositório

Pendente ou critério vigente:

  • continuar consolidando scripts base em vez de adicionar variantes pequenas
  • verificar em uso real que os scripts mais frequentes continuem confiáveis
  • documentar apenas o que mudar decisões operativas ou de arquitetura
  • manter este repositório pequeno, legível e fácil de corrigir

Como guardar aprendizado

  • .revit_cli/last_run.json e .revit_cli/history.jsonl para rastro local mínimo de execuções
  • hints.md para regras curtas de alto valor
  • README.md para decisões de arquitetura, guia e estado do repositório

Se algo não couber em 1 ou 2 bullets, provavelmente não é um hint. Se um dado só serve para recuperar uma execução recente, provavelmente vai para .revit_cli/, não para hints.md.

Encerramento

Este repositório não busca que o LLM "saiba muito" antes de agir.

Busca que ele possa:

  • ler apenas o necessário
  • escolher um template simples
  • executar contra o modelo real
  • verificar
  • e seguir com o menor custo de tokens por tarefa