Twenty CRM MCP Server

# Twenty CRM + MCP Server Solução completa que combina o **Twenty CRM** com um **MCP Server** (Model Context Protocol) para integração avançada. ## O que é? Este projeto fornece uma stack containerizada que inclui: - **Twenty CRM** - Plataforma de CRM moderna e extensível - **Twenty Worker** - Processador de tarefas assíncronas - **MCP Server** - Servidor Model Context Protocol para integração com IA e automações ## Versão 0.2.0 O MCP Server foi refatorado com base no schema OpenAPI atual da aplicação Twenty CRM. ## Principais Mudanças ### Stack de Componentes A arquitetura do projeto é composta por 3 serviços containerizados: 1. **ambienz-twenty-server** - Twenty CRM (porta 3000) - Servidor principal da aplicação CRM - Interface web para gestão de clientes - API REST integrada 2. **ambienz-twenty-worker** - Twenty Worker - Processador de jobs assíncronos - Automações e workflows - Integração com Redis 3. **ambienz-twenty-mcp-server** - MCP Server (porta 3001) - Servidor Protocol Model Context - Integração com IA e automações inteligentes - Gerenciamento de ferramentas e contexto ### Base URL Atualizada - Agora usa `https://twenty.ambienz.com.br/rest` por padrão - Endpoints seguem o padrão REST do Twenty CRM ### Objetos Suportados 1. **People** - Gestão de pessoas - `list_people`, `create_person`, `get_person`, `update_person`, `delete_person` - Campos atualizados: `name` (objeto), `emails` (objeto), `phones` (objeto), `linkedinLink`, `xLink` 2. **Companies** - Gestão de empresas - `list_companies`, `create_company`, `get_company`, `update_company`, `delete_company` - Campos brasileiros: `cnpj`, `razaoSocial` 3. **Opportunities** - Gestão de oportunidades - `list_opportunities`, `create_opportunity`, `get_opportunity`, `update_opportunity`, `delete_opportunity` - Campos: `amount` (objeto), `closeDate`, `stage`, `companyId`, `pointOfContactId` 4. **Notes** - Gestão de notas - `list_notes`, `create_note`, `get_note`, `update_note`, `delete_note` - Campos: `title`, `body`, `position` 5. **Tasks** - Gestão de tarefas - `list_tasks`, `create_task`, `get_task`, `update_task`, `delete_task` - Campos: `title`, `body`, `dueAt`, `status`, `assigneeId` 6. **Conversas** - Objeto customizado - `list_conversas`, `create_conversa`, `get_conversa`, `update_conversa`, `delete_conversa` - Campos: `name`, `conversasId`, `agent`, `lead` 7. **Faturas** - Objeto customizado - `list_faturas`, `create_fatura`, `get_fatura`, `update_fatura`, `delete_fatura` - Campos: `name`, `status` ### Paginação e Filtros Todos os endpoints de listagem agora suportam: - `filter` - Query JSON para filtros - `orderBy` - Ordenação por campo - `limit` - Limite de resultados (max 100) - `depth` - Profundidade de relações - `startingAfter` / `endingBefore` - Cursores de paginação ## Uso ```bash # Configurar variáveis de ambiente export TWENTY_API_KEY="your-api-key" export TWENTY_BASE_URL="https://twenty.ambienz.com.br/rest" export PORT=3000 # Executar servidor node mcp/index.js ``` ## Deployment com Docker Compose Para deployar a stack completa localmente: ```bash # Copiar arquivo de ambiente cp .env.example .env # Iniciar todos os serviços docker-compose up -d # Verificar status docker-compose ps # Ver logs docker-compose logs -f ambienz-twenty-mcp-server ``` O serviço Twenty CRM estará disponível na URL configurada (ex: `https://twenty.ambienz.com.br`) e o MCP Server na porta 3001. ## Endpoints - `GET /health` - Health check - `POST /tools/:toolName` - Executar ferramenta específica - `POST /mcp` - Endpoint MCP via Server-Sent Events