oa-aec-mcp: Fluxos de Trabalho de Auditoria do Revit como Ferramentas MCP

A maioria dos servidores MCP do Revit expõe primitivas em nível de elemento.

Obtenha paredes. Crie paredes. Defina parâmetros. Exclua elementos.

Esses blocos de construção são úteis se seu objetivo é permitir que um LLM edite um modelo. Mas os coordenadores de BIM geralmente não pensam em termos de CRUD de elementos. Eles pensam em termos de saúde do modelo, conformidade de nomenclatura, grupos de avisos e dados de salas incompletos.

Há também um problema prático com interfaces em nível de elemento: elas colocam o trabalho errado no lugar errado. Se um LLM tiver que executar uma auditoria de convenção de nomenclatura usando ferramentas de elementos brutos, ele terá que enumerar todos os elementos em uma categoria, ler cada nome, aplicar um padrão, coletar falhas e repetir para cada categoria. Isso resulta em milhares de idas e vindas, um custo significativo de tokens e muito raciocínio que o modelo tem que fazer em sua janela de contexto em vez de se concentrar na pergunta real.

Essa é a lacuna que o oa-aec-mcp está tentando preencher.

O Que É

oa-aec-mcp é um servidor MCP de código aberto que expõe quatro ferramentas de auditoria do Revit somente leitura para o Claude Desktop. O plugin em C# lida com toda a coleta e filtragem de dados dentro do Revit, enviando apenas resultados agregados pela conexão WebSocket. O modelo recebe uma resposta estruturada, não um monte de IDs de elementos para classificar.

Dois repositórios públicos, construídos ao longo de duas semanas:

• oa-aec-mcp — Servidor MCP em TypeScript: https://github.com/omarabdelazizeng-sketch/oa-aec-mcp
• oa-aec-mcp-plugin — Plugin Revit em C#: https://github.com/omarabdelazizeng-sketch/oa-aec-mcp-plugin

As Quatro Ferramentas

summarize_model_health — nenhum input necessário. Retorna contagem de avisos, famílias não utilizadas, salas não colocadas, contagem de visualizações e um resumo em linguagem simples da condição do modelo. Esta é a primeira ferramenta a ser chamada quando você deseja uma leitura rápida sobre a situação de um modelo.

list_unplaced_rooms — filtro de nível opcional. Retorna salas não colocadas com número da sala, nome, departamento e nível. Útil quando um programa de sala ainda está evoluindo e os espaços reservados se acumularam.

find_warnings_by_category — aceita um tipo de aviso específico ou "todos". Agrupa avisos por tipo e retorna IDs de elementos afetados. Em vez de uma contagem bruta de avisos, você obtém estrutura: quais categorias de aviso estão impulsionando o número e quais elementos estão envolvidos.

audit_naming_conventions — aceita um padrão regex e uma lista opcional de categorias (Visualizações, Folhas, Salas, Níveis, Paredes, Portas, Janelas, Famílias). Retorna violações agrupadas por categoria, com contagens totais e uma flag de truncamento se houver mais violações do que o limite de retorno.

A principal característica desta ferramenta não é o regex em si. É que Claude pode traduzir uma regra de nomenclatura em linguagem natural em um regex antes de chamar a ferramenta. Um coordenador não precisa saber a sintaxe do regex — ele descreve o padrão, Claude escreve o padrão e a ferramenta executa a auditoria.

Exemplo: Verificação de Modelo Pré-Submissão

Um prompt realista:

Revise este modelo antes da emissão. Verifique a saúde geral, liste quaisquer salas não colocadas no Nível 02, identifique as principais categorias de aviso e verifique se as visualizações e folhas seguem nosso padrão de nomenclatura — duas letras maiúsculas, um hífen, então o nome.

Claude chama quatro ferramentas em sequência:

summarize_model_health()
list_unplaced_rooms(level="Level 02")
find_warnings_by_category("all")
audit_naming_conventions("^[A-Z]{2}-[A-Z0-9_]+$", ["Views", "Sheets"])

A terceira chamada é onde a tradução de linguagem natural → regex acontece. Claude lê "duas letras maiúsculas, um hífen, então o nome" e gera ^[A-Z]{2}-[A-Z0-9_]+$ antes de chamar a ferramenta. O usuário nunca escreve um padrão.

Exemplo de resposta do Claude após as quatro chamadas retornarem:

O modelo não está pronto para emissão. A contagem de avisos é 143, concentrada em valores de marca duplicados (18 instâncias) e salas não cercadas (9 instâncias). O Nível 02 tem três salas não colocadas atribuídas a Operações e TI — estas parecem ser espaços reservados do programa que nunca foram colocados. A conformidade de nomenclatura de visualizações e folhas é ruim: 34 violações do padrão de prefixo de duas letras em 156 elementos verificados. Eu abordaria a colocação de salas e a nomenclatura antes do próximo pacote de coordenação.

Esse é o fluxo de trabalho pretendido. Um prompt, quatro chamadas de ferramentas direcionadas, um resumo acionável.

Arquitetura

Claude Desktop
  ↕ stdio (MCP)
TypeScript MCP Server (oa-aec-mcp)
  ↕ WebSocket localhost:8765
C# Revit Plugin (oa-aec-mcp-plugin)
  ↕ ExternalEvent dispatcher
Revit API

O servidor TypeScript lida com o protocolo MCP e expõe ferramentas para o Claude Desktop. O plugin em C# roda dentro do Revit, recebe solicitações via WebSocket e as executa através do mecanismo ExternalEvent do Revit, de modo que todas as chamadas da API sejam executadas na thread principal do Revit. Os dois repositórios são intencionalmente separados — a camada de protocolo e a lógica específica do Revit permanecem independentes.

Limitações

• Auditorias de nomenclatura usam apenas expressões regulares — sem compreensão semântica dos padrões BIM
• Somente auditoria — não impede nomenclaturas ruins ou bloqueia ações do usuário no Revit
• Sem correções automáticas de qualquer tipo
• v0.1 suporta apenas Revit 2025
• Requer que o plugin acompanhante esteja em execução dentro do Revit antes de chamar qualquer ferramenta

O Que Isso Não É

Já existem quatro ou cinco implementações MCP de código aberto do Revit, incluindo pelo menos uma com várias centenas de estrelas. Este projeto não está tentando ser o mais completo. É mais restrito: quatro ferramentas de auditoria somente leitura que cobrem um segmento específico do que os coordenadores de BIM realmente fazem repetidamente.

Se esse escopo restrito economizar alguns passos manuais de QA antes de uma reunião de coordenação, ele está cumprindo seu papel.

O Que Vem a Seguir

Candidatos a v0.2:

• Auditorias de nomenclatura de múltiplos padrões em uma única chamada
• extract_sheet_index — números de folhas, nomes e revisão atual
• get_view_filter_summary — detecção de sobreposição de visibilidade de visualizações
• Resumo de uso de Workset
• Relatório de cobertura de template de visualização

O mesmo princípio se aplica a tudo na lista: uma ferramenta por fluxo de trabalho de coordenação, não uma ferramenta por método da API.

Experimente

Abra um modelo de produção, execute uma verificação de saúde e veja se os resultados são úteis.

Se algo quebrar, ou se houver um fluxo de auditoria que você executa regularmente que deveria ser uma ferramenta, abra um problema em qualquer um dos repositórios.