mcp-server-airo

v1.3.5

Published

4 days ago

MCP Server para API de Gestão de Obras AIRO

0High
0Medium
0Low

airo.app

mcp model-context-protocol gestao-obras construcao airo fastify prisma construction-management ai-integration

🏗️ MCP Server - Gestão de Obras AIRO

Model Context Protocol Server para integração com a API de Gestão de Obras AIRO. Permite que IAs (como Claude, ChatGPT, etc.) interajam diretamente com o sistema de gestão através do protocolo MCP.

🎯 O que é MCP?

O Model Context Protocol (MCP) é um protocolo aberto que permite que modelos de IA se conectem a fontes de dados e ferramentas externas. Este servidor MCP expõe toda a funcionalidade da API de Gestão de Obras para que IAs possam:

✅ Consultar dados de obras, clientes, fornecedores
✅ Criar e gerenciar orçamentos
✅ Controlar lançamentos financeiros
✅ Gerenciar estoque de insumos
✅ Gerar relatórios em tempo real

🚀 Instalação

Pré-requisitos

Node.js 18 ou superior
Claude Desktop (ou outro cliente MCP)
Acesso ao APP AIRO para Gestão de Obras

Instalação Simples (Recomendado)

Não precisa clonar o repositório! O MCP Server está publicado no npm.

Obtenha seu token JWT:

curl -X POST http://api.empresa.com:3333/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"sua-senha"}'

Configure o Claude Desktop:

Edite o arquivo de configuração:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Adicione:

{
  "mcpServers": {
    "gestao-obras": {
      "command": "npx",
      "args": [
        "mcp-server-airo@latest"
      ],
      "env": {
        "API_BASE_URL": "http://api.empresa.com:3333",
        "API_JWT_TOKEN": "seu-token-jwt-aqui"
      }
    }
  }
}

Reinicie o Claude Desktop

✅ Pronto! Simples assim!

Instalação para Desenvolvimento

Se você quer contribuir ou modificar o código:

# 1. Clone o repositório
git clone <url-do-repositorio>
cd MCP-SERVER-AIRO

# 2. Instale as dependências
npm install

# 3. Compile o projeto
npm run build

# 4. Teste localmente
npm run dev

Edite o .env com suas configurações:

# URL da API de Gestão de Obras
API_BASE_URL=http://localhost:3333

# Token JWT (obrigatório)
API_JWT_TOKEN=seu-token-jwt-aqui

🔧 Configuração no Claude Desktop

Para usar este MCP Server com o Claude Desktop, adicione ao arquivo de configuração:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gestao-obras": {
      "command": "node",
      "args": ["C:/APP AIRO/MCP-SERVER-AIRO/dist/index.js"],
      "env": {
        "API_BASE_URL": "http://localhost:3333",
        "API_JWT_TOKEN": "seu-token-jwt-aqui"
      }
    }
  }
}

Importante: Ajuste o caminho absoluto para o local onde você clonou o projeto.

Ferramentas Disponíveis

O servidor expõe 60 ferramentas organizadas por módulo:

🔐 Autenticação

usuario_atual - Obtém dados do usuário autenticado

Nota: As ferramentas de login, registro e configuração de IA foram removidas para garantir que a autenticação seja gerenciada exclusivamente via tokens JWT seguros.

Clientes (5 ferramentas)

listar_clientes - Lista clientes com paginação
buscar_cliente - Busca cliente por ID
criar_cliente - Cria novo cliente (PF ou PJ)
atualizar_cliente - Atualiza dados do cliente
desativar_cliente - Desativa cliente (soft delete)

🏗️ Obras (8 ferramentas)

listar_obras - Lista obras com filtros
buscar_obra - Busca obra por ID
criar_obra - Cria nova obra
atualizar_obra - Atualiza dados da obra
desativar_obra - Desativa obra
vincular_fornecedor_obra - Vincula fornecedor à obra (com contrato/medições)
atualizar_fornecedor_obra - Atualiza vínculo de fornecedor (medições, datas)
desvincular_fornecedor_obra - Remove fornecedor da obra

🧱 Fornecedores (5 ferramentas)

listar_fornecedores - Lista fornecedores com filtros
buscar_fornecedor - Busca fornecedor por ID
criar_fornecedor - Cria novo fornecedor
atualizar_fornecedor - Atualiza dados do fornecedor
desativar_fornecedor - Desativa fornecedor (soft delete)

🧮 Planejamento (9 ferramentas)

listar_etapas - Lista etapas/subetapas/tarefas
obter_hierarquia_planejamento - Retorna hierarquia completa
buscar_etapa - Busca item por ID
criar_item_planejamento - Criação unificada de etapas/subetapas/tarefas
criar_etapa - Helper nível 1
criar_subetapa - Helper nível 2
criar_tarefa - Helper nível 3
atualizar_etapa - Atualiza qualquer nível
deletar_etapa - Remove nível e filhos

💰 Orçamentos (12 ferramentas)

listar_orcamentos - Lista orçamentos
buscar_orcamento - Busca orçamento por ID
criar_orcamento - Gera orçamento via planejamento
atualizar_orcamento - Atualiza dados
deletar_orcamento - Remove orçamento (soft delete)
recalcular_orcamento - Recalcula valores com base nos itens
obter_totalizadores_orcamento - Retorna totais por níveis
adicionar_insumo_tarefa - Adiciona insumo em tarefa
listar_insumos_tarefa - Lista insumos da tarefa
buscar_insumo_tarefa - Busca insumo específico da composição
atualizar_insumo_tarefa - Atualiza quantidades/custos de insumo
remover_insumo_tarefa - Remove insumo da tarefa

📊 Itens de Orçamento (4 ferramentas)

listar_orcamento_itens - Lista itens hierárquicos
buscar_orcamento_item - Busca item específico
atualizar_orcamento_item - Atualiza quantidade/unidade/descrição
deletar_orcamento_item - Remove item (respeitando hierarquia)

📦 Insumos (6 ferramentas)

listar_insumos - Lista insumos (materiais, mão de obra, etc.)
buscar_insumos_similares - Busca por similaridade (evita duplicatas)
buscar_insumo - Busca insumo por ID
criar_insumo - Cria novo insumo
atualizar_insumo - Atualiza insumo
deletar_insumo - Remove insumo

🏭 Estoque por Obra (10 ferramentas)

definir_estoque - Inicializa estoque de um insumo na obra
listar_estoques - Lista geral de estoques
buscar_estoque - Busca registro específico
buscar_estoque_por_insumo_obra - Busca estoque de um insumo numa obra
listar_estoques_obra - Lista todo estoque de uma obra
listar_estoques_insumo - Lista onde um insumo está estocado
listar_alertas_estoque - Lista itens com estoque baixo
atualizar_estoque - Atualiza configurações (mínimo, localização)
ajustar_quantidade_estoque - Ajuste manual (inventário)
transferir_estoque - Transfere entre obras

📋 Consumo de Insumos (5 ferramentas)

listar_consumos - Lista registros de consumo
buscar_consumo - Busca registro por ID
registrar_consumo - Baixa do estoque automaticamente
atualizar_consumo - Corrige lançamento de consumo
deletar_consumo - Estorna consumo ao estoque

💵 Financeiro (8 ferramentas)

listar_lancamentos - Lista lançamentos financeiros
buscar_lancamento - Busca lançamento por ID
criar_lancamento - Cria receita ou despesa (com suporte a múltiplos itens)
atualizar_lancamento - Atualiza lançamento
deletar_lancamento - Remove lançamento
listar_tipos_lancamento - Lista categorias financeiras
criar_tipo_lancamento - Cria nova categoria personalizada
vincular_item_insumo - Vincula item de compra a insumo de estoque

📦 Recursos Disponíveis

Recursos fornecem acesso rápido a dados em tempo real:

gestao-obras://obras/lista - Todas as obras ativas
gestao-obras://obras/em-andamento - Obras em andamento
gestao-obras://clientes/lista - Todos os clientes
gestao-obras://orcamentos/aprovados - Orçamentos aprovados
gestao-obras://insumos/estoque-baixo - Insumos com estoque baixo
gestao-obras://financeiro/pendentes - Lançamentos pendentes
gestao-obras://dashboard/resumo - Dashboard com estatísticas

💡 Exemplos de Uso

Exemplo 1: Listar obras em andamento

Prompt para a IA:

Liste todas as obras que estão em andamento no sistema

A IA usará a ferramenta listar_obras com filtro status: EM_ANDAMENTO.

Exemplo 2: Criar novo cliente

Prompt para a IA:

Cadastre um novo cliente pessoa física:
- Nome: João Silva
- CPF: 123.456.789-00
- Email: [email protected]
- Telefone: (11) 98765-4321

A IA usará a ferramenta criar_cliente com os dados fornecidos.

Exemplo 3: Verificar estoque baixo

Prompt para a IA:

Quais insumos estão com estoque abaixo do mínimo?

A IA usará a ferramenta verificar_estoque_baixo ou acessará o recurso gestao-obras://insumos/estoque-baixo.

Exemplo 4: Gerar relatório financeiro

Prompt para a IA:

Gere um relatório financeiro da obra X do último mês

A IA usará a ferramenta relatorio_financeiro com os parâmetros adequados.

🔒 Segurança

✅ Autenticação JWT obrigatória para todas as operações
✅ Validação de entrada com Zod em todas as ferramentas
✅ Tratamento de erros robusto com mensagens claras
✅ Sem exposição de credenciais - tokens armazenados em variáveis de ambiente

🛠️ Desenvolvimento

Executar em modo desenvolvimento

npm run dev

Compilar para produção

npm run build

Estrutura do projeto

MCP-SERVER-AIRO/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   ├── lib/
│   │   └── api-client.ts     # Cliente HTTP para API
│   ├── types/
│   │   └── index.ts          # Tipos TypeScript
│   ├── tools/                # Ferramentas MCP
│   │   ├── auth.tools.ts
│   │   ├── clientes.tools.ts
│   │   ├── obras.tools.ts
│   │   ├── orcamentos.tools.ts
│   │   ├── insumos.tools.ts
│   │   ├── financeiro.tools.ts
│   │   └── index.ts
│   └── resources/            # Recursos MCP
│       └── index.ts
├── dist/                     # Código compilado
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🧪 Testando o Servidor

Teste 1: Verificar se o servidor inicia

npm run dev

Você deve ver:

🚀 MCP Server de Gestão de Obras iniciado
📡 API Base URL: http://localhost:3333
🔐 Autenticação: Token JWT
🛠️  39 ferramentas disponíveis
📦 7 recursos disponíveis

Teste 2: Usar com Claude Desktop

Configure o claude_desktop_config.json conforme instruções acima
Reinicie o Claude Desktop
Abra uma nova conversa
Digite: "Liste as obras em andamento"
O Claude deve usar o MCP Server automaticamente

📖 Documentação da API

Para mais detalhes sobre os endpoints da API, acesse:

Documentação Interativa: http://localhost:3333/docs
OpenAPI JSON: http://localhost:3333/openapi.json

🤝 Contribuindo

Contribuições são bem-vindas! Para adicionar novas ferramentas:

Crie um novo arquivo em src/tools/
Defina as ferramentas com schema Zod
Adicione ao src/tools/index.ts
Compile e teste

📝 Licença

MIT License - AIRO

🆘 Suporte

Para problemas ou dúvidas:

Verifique se a API está rodando em http://localhost:3333
Confirme que as credenciais no .env estão corretas
Verifique os logs do servidor MCP (stderr)
Teste os endpoints diretamente na documentação da API

Desenvolvido com ❤️ para integração de IA com sistemas de gestão de obras

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🏗️ MCP Server - Gestão de Obras AIRO

🎯 O que é MCP?

🚀 Instalação

Pré-requisitos

Instalação Simples (Recomendado)

Instalação para Desenvolvimento

🔧 Configuração no Claude Desktop

Ferramentas Disponíveis

🔐 Autenticação

Clientes (5 ferramentas)

🏗️ Obras (8 ferramentas)

🧱 Fornecedores (5 ferramentas)

🧮 Planejamento (9 ferramentas)

💰 Orçamentos (12 ferramentas)

📊 Itens de Orçamento (4 ferramentas)

📦 Insumos (6 ferramentas)

🏭 Estoque por Obra (10 ferramentas)

📋 Consumo de Insumos (5 ferramentas)

💵 Financeiro (8 ferramentas)

📦 Recursos Disponíveis

💡 Exemplos de Uso

Exemplo 1: Listar obras em andamento

Exemplo 2: Criar novo cliente

Exemplo 3: Verificar estoque baixo

Exemplo 4: Gerar relatório financeiro

🔒 Segurança

🛠️ Desenvolvimento

Executar em modo desenvolvimento

Compilar para produção

Estrutura do projeto

🧪 Testando o Servidor

Teste 1: Verificar se o servidor inicia

Teste 2: Usar com Claude Desktop

📖 Documentação da API

🤝 Contribuindo

📝 Licença

🆘 Suporte