MCP 服务器

MCP Vista CRM Loft

Enterprise-level MCP server integrating with Vista CRM (Loft Edition) for real estate operations, offering 40+ tools for property search, pipeline management, lead capture, and agenda control.

README

MCP Server - Vista CRM 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:

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:

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.