MCP Server - Vista CRM Loft 🏠🚀

![License: MIT](https://opensource.org/licenses/MIT) ![MCP](https://modelcontextprotocol.io) ![TypeScript](https://www.typescriptlang.org/) ![Version](https://github.com/fabiohsan-dev/mcp-vista-loft)

Integração de nível empresarial com a API Vista CRM (Loft Edition), projetada especificamente para agentes de IA que precisam gerenciar operações imobiliárias complexas com precisão, segurança e economia de tokens.

Este servidor implementa o Model Context Protocol (MCP), expondo mais de 40 ferramentas que permitem a modelos de linguagem (LLMs) pesquisar imóveis, gerenciar o funil de vendas (Pipeline), capturar leads e controlar agendas de visitas.

---

🌟 Funcionalidades de Elite

🔍 Busca de Nova Geração: Suporte a queries complexas via imovel_busca_avancada e filtros dinâmicos via imovel_listar_conteudo.
📈 Gestão de Funil (Pipeline): Controle total de negociações e perfis de interesse do cliente.
💎 Otimização Inteligente de Contexto: Processamento via PayloadOptimizer que remove ruído (nulls/vazios), reduzindo o consumo de tokens em até 60%.
🛡️ Resiliência em Produção: Cliente HTTP customizado com tratamento de erros de negócio camuflados, timeouts e isolamento de falhas.
📊 Observabilidade Total: Logs estruturados em stderr para monitoramento em tempo real sem interferir no protocolo de dados.

---

⚠️ Segurança: Este servidor manipula dados sensíveis de CRM. O uso em ambientes de produção deve ser monitorado para prevenir ataques de injeção de prompt que visem a exfiltração de dados privados.

---

🏗️ Arquitetura do Sistema

O projeto segue os princípios de Clean Architecture, garantindo manutenibilidade e facilidade de testes.

graph TD
    IA[Claude/Cursor/Gemini] -->|JSON-RPC via stdio| MCP[MCP Server Layer]
    subgraph "Product Logic"
        MCP --> Tools[Tools Layer - Controllers]
        Tools --> Services[Services Layer - Business Logic]
        Services --> Optimizer[Payload Optimizer - Utility]
        Services --> Clients[Vista HTTP Client - Infrastructure]
    end
    Clients -->|HTTPS| Vista[API Vista CRM / Loft]

---

🚀 Instalação e Setup

Pré-requisitos

Node.js 18.x ou superior.
NPM ou Yarn.
Chave de API da Vista Software.

Passo a Passo

Clone o repositório:

   git clone https://github.com/fabiohsan-dev/mcp-vista-loft.git
   cd mcp-vista-loft

Instalação e Build:

   npm install
   npm run build

Configuração de Ambiente:

Crie um arquivo .env na raiz: ``env VISTA_URL=https://sua-instancia.vistahost.com.br VISTA_KEY=sua-chave-api DEFAULT_LIMIT=20 TIMEOUT_MS=30000 ``

---

🔌 Integração com Agentes de IA

1. Claude Desktop

Adicione ao seu arquivo de configuração:

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

{
  "mcpServers": {
    "vista-crm-loft": {
      "command": "node",
      "args": ["/CAMINHO/ABSOLUTO/mcp-vista-loft/dist/index.js"],
      "env": {
        "VISTA_URL": "SUA_URL",
        "VISTA_KEY": "SUA_KEY"
      }
    }
  }
}

2. Cursor IDE

Vá em Settings > Cursor Settings > MCP e adicione um novo servidor:

Name: Vista CRM Loft
Type: command
Command: node /CAMINHO/ABSOLUTO/mcp-vista-loft/dist/index.js

---

📋 Catálogo de Ferramentas (40+ ferramentas)

🏠 Módulo de Imóveis

| Ferramenta | Descrição | |------------|-----------| | imoveis_pesquisar | Busca padrão com filtros e ordenação. | | imovel_busca_avancada | Execução de queries JSON complexas. | | imovel_detalhes | Dados técnicos completos do imóvel. | | imovel_listar_conteudo | Obtém valores únicos para filtros (ex: bairros ativos). | | imovel_prontuario | Histórico detalhado e categorizado de eventos. | | imovel_fotos / anexos | Gestão de mídia e documentação técnica. |

👥 Módulo de Clientes & Leads

| Ferramenta | Descrição | |------------|-----------| | clientes_pesquisar | Busca de contatos no CRM. | | lead_enviar | Captura de leads de fontes externas (site/redes sociais). | | cliente_historico | Log completo de interações com o cliente. | | cliente_favoritos | Gestão de imóveis de interesse do contato. |

📈 Módulo de Pipeline & Negócios

| Ferramenta | Descrição | |------------|-----------| | pipeline_listar | Gestão do funil de vendas e perfis de interesse. | | pipeline_atualizar_etapa | Movimentação de negócios entre fases do funil. | | pipeline_campos | Consulta de campos customizados do funil. |

📅 Módulo de Agenda & Configuração

| Ferramenta | Descrição | |------------|-----------| | agendamentos_pesquisar | Filtro de agenda por corretor, cliente ou imóvel. | | webhook_listar | Monitoramento de integrações em tempo real. | | imovel_deletar_video | Remoção definitiva de ativos de mídia. | ---

🧪 Qualidade e Testes

O servidor conta com uma infraestrutura de testes automatizada para garantir a estabilidade das 40+ ferramentas.

1. Testes Unitários (Vitest)

Validam a lógica pura, como o otimizador de tokens: ``bash npm test ``

2. Smoke Test de Integração (Python)

Valida o protocolo MCP real via JSON-RPC e a conectividade com a API Vista. Importante: Nunca utilize credenciais hardcoded. O runner lê as variáveis do ambiente.

# Windows PowerShell
$env:VISTA_URL="http://sandbox-rest.vistahost.com.br"; $env:VISTA_KEY="SUA_KEY"; python tests/integration/smoke_test_runner.py

---

🤖 Automação (CI/CD)

Este repositório possui uma infraestrutura de automação real via GitHub Actions:

CI (Build & Test): Localizado em .github/workflows/ci.yml.
Job 1 (Unit & Build): Valida tipos TypeScript, roda testes unitários e gera o build minificado.
Job 2 (Integration): Roda o Smoke Test Python em um ambiente Ubuntu isolado.
CD (Deploy): Localizado em .github/workflows/deploy.yml.
Configurado para rodar em push na main ou via disparo manual (workflow_dispatch).
Utiliza o ambiente production do GitHub para proteção de segredos.

🛡️ Configuração de Secrets no GitHub

Para que o pipeline de integração funcione, você deve adicionar os seguintes Secrets no seu repositório:

VISTA_URL_SANDBOX: URL da sandbox (ex: http://sandbox-rest.vistahost.com.br).
VISTA_KEY_SANDBOX: Sua chave de API da sandbox.

---

🐞 Solução de Problemas

Logs Detalhados: Os logs do servidor são enviados para stderr em formato JSON estruturado. Você pode visualizá-los no console do seu agente. Erros da API Vista são capturados e sanitizados para não vazar chaves de API em mensagens de erro.

--- Caminhos no Windows: Ao configurar no Claude/Cursor, utilize barras normais (/) ou barras invertidas duplas (\\) para evitar erros de escape no JSON.

---

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para detalhes.

👨‍💻 Autor

Fabio San - @fabiohsan-dev

--- Nota: Este projeto é uma implementação independente e não possui vínculo oficial com a Vista Software ou com a Loft.

MCP Vista CRM Loft