# 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