CLI_Revit

Token-efficient MCP harness for Revit/BIM automation — search+run over 160+ scripts instead of exposing tools individually.

GitHub
1
Try this MCPSponsored

Documentation

CLI Revit / Sin Tool

Repo minimo para operar Revit con la menor intermediacion posible entre el LLM y la API.

Que es este repo

CLI_Revit es un harness local de automatizacion para Revit.

Mas concreto:

  • conecta un agente o LLM con un modelo abierto en Revit
  • permite descubrir, parametrizar y ejecutar scripts BIM reutilizables
  • expone una superficie shell-first por revit_cli.py y una superficie MCP por mcp_server.py
  • mantiene una capa minima de intermediacion entre el agente y la API de Revit

No es solo un plugin, ni solo una libreria, ni solo un servidor MCP. El MCP es una interfaz de acceso mas; el nucleo del repo es el harness de ejecucion y automatizacion sobre Revit.

Quickstart

Requisitos minimos:

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

Pasos:

# 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\"}"

Si ping responde DOWN: Revit no esta abierto, el .addin no quedo instalado, o falta configurar PYTHONNET_PYDLL — detalle completo en plugin/README.md.

Para usarlo desde un agente en vez de la shell (Claude Code, OpenCode, o cualquier cliente MCP): el repo ya trae .mcp.json y mcp_server.py listos, ver seccion "Uso desde Claude Code" mas abajo.

Harness vertical, no generico

Mismo patron que un harness generico (Claude Code, OpenCode, dsh): loop de agente + intermediacion minima entre decision y ejecucion + feedback estructurado para verificar. La diferencia es el alcance:

  • un harness generico decide su dominio por prompt/contexto
  • este harness tiene el dominio hardcodeado en el protocolo: catalogo de scripts, convencion get_/crear_/modificar_, contrato RESULTADO: OK|WARN|ERROR

Por eso se expone via MCP y no como plugin nativo de cada harness general: el harness vertical se mantiene una sola vez en este repo, y cualquier harness general lo consume como cliente MCP sin reescritura.

Mapa rapido

  • docs/INICIO_BIM.md: puerta de entrada para una sesion de modelado BIM del agente
  • README.md: guia del repo y estado actual de desarrollo
  • docs/DESARROLLO_REPO.md: guia para continuar el repo por capacidades BIM, no por acumulacion de scripts
  • docs/CAPACIDADES_BIM.md: matriz corta de capacidades cubiertas, parciales, ausentes y prioridades activas
  • docs/SCRIPTS_BASE.md: nucleo operativo del repo y reglas para tocar scripts base
  • hints.md: libreta operativa corta y corregible
  • CONTRIBUTING.md: criterio de aceptacion de PRs y convenciones de scripts
  • LICENSE / NOTICE / AUTHORS: licencia Apache-2.0 y creditos
  • revit_cli.py: entrypoint shell-first para buscar y correr scripts
  • revit_client.py: cliente WebSocket minimo para ejecutar Python raw
  • plugin/: add-in C# local de Revit (RevitAgentPlugin) para compilar e instalar el servidor WebSocket

Criterio de diseno

La regla central de este repo es simple:

  • cada tarea BIM debe consumir la menor cantidad de tokens posible para llegar a una respuesta buena
  • los tokens deben ir a leer estado real del modelo, decidir y verificar
  • no deben ir a contexto inflado, routing local, wrappers redundantes o documentacion larga

En la practica eso significa:

  • cliente a Revit chico y obvio
  • scripts explicitos y reutilizables
  • hints cortos en vez de una capa de tools
  • pocas piezas base, no catalogos grandes de variantes

Formula de trabajo:

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

Guia de uso

En una sesion nueva:

  1. leer docs/INICIO_BIM.md
  2. leer hints.md
  3. correr python revit_cli.py doctor
  4. ir a README.md solo si hace falta contexto del repo o decisiones de arquitectura
  5. hacer una lectura minima real del modelo antes de mutar

Reglas de trabajo:

  • si ya existe un script util, buscarlo y correrlo con PARAMS
  • si el pedido es una variante chica, ajustar el script existente antes de crear otro
  • crear un script nuevo solo cuando abre una capacidad reutilizable de verdad
  • no guardar un script nuevo para una decision puntual de modelado
  • si el pedido admite varias soluciones BIM razonables y el criterio no esta dicho, consultar antes de fijar una variante permanente

Uso rapido

La idea de revit_cli.py no es reemplazar al LLM sino evitar que tenga que reescribir Python completo para cada consulta.

Ejemplos:

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 unico para Codex

Si vas a usar Codex con modelo local desde este repo, el entrypoint pasa a ser:

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

Launchers equivalentes para otros CLIs locales:

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

Nota:

  • hermes-local.ps1 exige contexto minimo de 65536; qwen3-coder-30b-q4 y gemma4-26b-a4b-q4km quedan configurados para ese objetivo en los launchers locales.

Reglas del launcher:

  • vive en CLI_Revit, no depende de proj-agent-local
  • resuelve los GGUF en C:\Users\fmg\local_models
  • resuelve llama-server.exe en C:\Users\fmg\local_models\llama.cpp\llama-server.exe
  • si hace falta, permite override por PROJ_AGENT_MODEL_PATH, PROJ_AGENT_LLAMA_SERVER_EXE o .codex/local-model-paths.json

Para elegir un perfil exacto sin usar alias:

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

Uso desde Claude Code

Ahora el repo tambien incluye un servidor MCP local para que Claude pueda usar los scripts existentes sin salir del flujo normal del proyecto.

Archivos:

  • mcp_server.py: servidor MCP sobre stdio que reutiliza revit_cli.py y revit_client.py
  • .mcp.json: configuracion de proyecto para Claude Code
  • .claude/settings.json: permisos preaprobados solo para herramientas seguras de descubrimiento y consulta

Flujo minimo:

  1. tener Revit abierto con el plugin RevitAgent levantado
  2. abrir este repo desde Claude Code
  3. aprobar el servidor revit-agent cuando Claude detecte .mcp.json
  4. usar herramientas MCP como search_scripts, show_script y run_script

Notas cortas:

  • el catalogo completo de scripts/ queda oculto detras de search_scripts, show_script y run_script
  • las tools MCP aceptan timeout y max_output_bytes; si una salida supera el limite, el plugin devuelve preview y guarda la salida completa en .revit_cli/artifacts
  • el plugin acepta requests paralelas desde CLI/MCP/WebSocket, pero las ejecuta en cola FIFO dentro del hilo principal de Revit
  • el server carga el catalogo al iniciar; si agregas scripts nuevos, reinicia Claude o vuelve a cargar el servidor
  • los tools de mutacion no quedaron preautorizados en .claude/settings.json; la idea es mantener permisos conservadores sobre el modelo
  • run_script ejecuta cualquier script por nombre o ruta relativa sin inflar el catalogo visible de tools

Flujo operativo

Arquitectura minima:

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

revit_cli.py es la puerta de entrada normal.

revit_client.py sirve para ejecutar Python raw cuando hace falta control total o para prototipar una pieza nueva antes de volverla script reusable.

El transporte WebSocket es compatible con uso concurrente: varios clientes pueden enviar requests a la vez. Revit sigue siendo single-threaded, por lo que el plugin las encola en FIFO y las ejecuta secuencialmente en ExternalEvent. Las respuestas incluyen diagnostics con tiempos de cola/ejecucion y bytes de salida.

Archivos principales

  • revit_client.py: cliente WebSocket minimo hacia Revit
  • revit_cli.py: buscador/runner minimo para reutilizar scripts existentes
  • docs/DESARROLLO_REPO.md: criterio de roadmap y foco del repo
  • docs/CAPACIDADES_BIM.md: matriz accionable de capacidades BIM y prioridades
  • docs/SCRIPTS_BASE.md: lista de scripts base y criterio de cuidado del nucleo
  • plugin/: codigo fuente, build e instalacion del plugin local de Revit
  • hints.md: libreta operativa corta y corregible
  • .revit_cli/: estado local minimo entre sesiones (last_run.json + history.jsonl)
  • scripts/consulta: lecturas del modelo
  • scripts/creacion: acciones de modelado
  • scripts/modificacion: ajustes sobre elementos existentes, tags y cambios de documentacion en vistas
  • scripts/reportes: salidas tecnicas persistentes y exportaciones

Regla de nombres

El nombre del script debe reflejar su contrato operativo real, no solo la intencion de negocio.

  • get_*: lectura del modelo, sin mutacion ni artefacto persistente
  • crear_*: crea elementos nuevos en el modelo
  • modificar_* o verbo de cambio (mover_*, aplicar_*, etiquetar_*, reubicar_*): muta elementos o vistas existentes
  • exportar_*: genera salida externa persistente (PDF, imagen, etc.)
  • generar_reporte_* / generar_memoria_*: genera documento tecnico persistente

Si un script mezcla dos contratos, debe partirse o quedar claramente sesgado hacia uno y exponer alias de compatibilidad.

Plugin local

Este repo ya incluye el plugin necesario para que el runtime sea autosuficiente:

  • codigo fuente en plugin/
  • proyecto .NET en plugin/RevitAgentPlugin.csproj
  • build local en plugin/build.bat
  • build multi-version en plugin/build_all_versions.bat
  • documentacion operativa en plugin/README.md

Flujo minimo:

cd plugin
build_all_versions.bat

Si solo necesitas una instalacion puntual y build.bat detecta bien tu version de Revit:

cd plugin
build.bat

Notas cortas:

  • el plugin instala el servidor en ws://localhost:18789
  • editar_boceto_muro.py puede aprovechar RevitEditScopeHelpers del assembly del plugin
  • el detalle de requisitos (dotnet, net48, PYTHONNET_PYDLL, Addins por version) vive en 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 y artifact_dir son opcionales. max_output_bytes usa 256 KB por defecto; si se supera, result/traceback contiene una preview y la salida completa queda como artefacto 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" }

Variables disponibles en cada script:

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

Reglas del entorno

  • devolver resultados con print(), no por ultima expresion
  • no usar with Transaction(...); abrir y cerrar la transaccion manualmente
  • Revit trabaja en pies decimales; convertir unidades de forma explicita
  • si una API pide IList<T>, usar List[T] de .NET, no list de Python
  • FamilySymbol.Activate() debe ocurrir dentro de una Transaction
  • ToElements() conviene envolverlo con list() antes de usar slicing

Contrato de salida minima

Para no inflar contexto, la salida de los scripts debe pensarse para decision operativa, no para narracion.

  • python revit_cli.py run ... ahora usa --output-mode auto por default: si detecta *_JSON= o stdout largo, compacta la respuesta.
  • si necesitas ver todo el stdout, usar python revit_cli.py run ... --output-mode raw
  • emitir siempre una linea de estado corta: RESULTADO: OK|WARN|ERROR o RESULTADO=ok
  • emitir metricas clave en mayusculas: TOTAL_VISTAS, COUNT_FILTRADAS, ELEMENT_IDS, etc.
  • si hace falta detalle estructurado, emitirlo en una sola linea NOMBRE_JSON=...
  • limitar detalle humano con max_detalle; el detalle completo debe quedar opt-in, no por defecto

Regla practica:

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

Patron de transaccion:

from Autodesk.Revit.DB import Transaction

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

Conversiones

  • metros -> pies: valor_m * 3.28084
  • pies -> metros: valor_ft * 0.3048

Verificar conexion

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

Que no queremos reconstruir

  • tool_catalog.py
  • prepare-request
  • routing interno
  • RAG o memoria automatica compleja
  • un agente de preferencia
  • documentacion grande dificil de corregir

Estado del repo

Estado actual:

  • el flujo shell-first ya existe y funciona desde revit_cli.py
  • doctor valida conexion, metadata minima y smoke tests de busqueda
  • run deja un rastro local chico en .revit_cli/ para retomar entre sesiones sin inflar el repo
  • el plugin de Revit ya vive dentro de este repo y puede compilarse desde plugin/
  • hay una base amplia de scripts reutilizables en scripts/consulta, scripts/creacion, scripts/modificacion y scripts/reportes
  • hints.md ya cumple el rol de memoria operativa corta
  • la nueva separacion documental deja un punto de entrada BIM (docs/INICIO_BIM.md) y este README como guia viva del repo

Pendiente o criterio vigente:

  • seguir consolidando scripts base en lugar de sumar variantes pequenas
  • verificar en uso real que los scripts mas frecuentes sigan siendo confiables
  • documentar solo lo que cambie decisiones operativas o de arquitectura
  • mantener este repo chico, legible y facil de corregir

Como guardar aprendizaje

  • .revit_cli/last_run.json y .revit_cli/history.jsonl para rastro local minimo de ejecuciones
  • hints.md para reglas cortas de alto valor
  • README.md para decisiones de arquitectura, guia y estado del repo

Si algo no entra en 1 o 2 bullets, probablemente no es un hint. Si un dato solo sirve para recuperar una corrida reciente, probablemente va a .revit_cli/, no a hints.md.

Cierre

Este repo no busca que el LLM "sepa mucho" antes de actuar.

Busca que pueda:

  • leer solo lo necesario
  • elegir una plantilla simple
  • ejecutar contra el modelo real
  • verificar
  • y seguir con el menor costo de tokens por tarea