@lionchat/mcp-server 0.2.1 → 0.3.1

package/dist/docs/resources/best-practices.md

@@ -0,0 +1,166 @@
+# Boas Práticas — Uso Eficiente do MCP
+
+Como usar o MCP do LionChat sem desperdiçar tokens, sem cair em rate limits, e com respostas precisas.
+
+## Princípio geral: liste resumido, leia detalhado quando precisar
+
+Errado: pegar TODAS conversas + TODAS mensagens de cada uma logo de cara.
+
+Certo:
+1. `conversations_list` com filtros e `page=1` (paginado) → vê IDs + última mensagem
+2. Identifica candidatas (5-10 conversas)
+3. `conversations_messages_list` SÓ para as relevantes
+
+Resultado: 10x menos tokens.
+
+## Use filtros sempre que possível
+
+A maioria dos endpoints aceita parâmetros pra filtrar antes de retornar:
+
+| Endpoint | Filtros úteis |
+|---|---|
+| `conversations_list` | `status` (open/resolved), `assignee_type`, `inbox_id`, `team_id`, `labels`, `q` (busca) |
+| `contacts_list` | `q` (nome/email/telefone), `include_contact_inboxes` |
+| `messages_search` | `q`, `conversation_id`, `before`, `after` |
+| `kanban_items_list` | `funnel_id`, `funnel_stage`, `assigned_agent_id` |
+| `reports_list_*` | `since`, `until`, `metric`, `type` |
+
+**Dica:** sempre filtre por período (`since`/`until`) em relatórios — sem isso pode trazer anos de histórico.
+
+## Paginação
+
+Endpoints listáveis paginam em geral 25 itens. Use `page` parameter:
+
+```
+page=1 → primeiros 25
+page=2 → próximos 25
+```
+
+Pra contar total, use `meta.total_count` (vem no response). Não tente "paginar até zerar" se já tem o total — pode ser milhões.
+
+## Cache local mental
+
+Quando ler dados que provavelmente não mudam na sessão:
+- Lista de inboxes
+- Lista de agentes
+- Lista de times
+- Custom attribute definitions
+- Funnels
+
+Faça UMA chamada e use a info por toda a conversa. NÃO refaça `agents_list` 10x.
+
+## Use endpoints específicos > endpoints genéricos
+
+Quando existir endpoint específico, prefira:
+
+| Errado | Certo |
+|---|---|
+| `reports_list` filtrando manualmente | `reports_list_2` (já é "conversations_metrics") |
+| `conversations_list` + filtro de unread no cliente | `conversations_list` com `assignee_type=me&status=open` |
+| `messages_list` percorrendo conversas | `conversations_messages_search` com `q=...` |
+
+## Economia em conversas com muitas mensagens
+
+Conversa com 200 mensagens? **Não baixe tudo**:
+
+1. `conversations_show` (1 chamada) → metadata + última mensagem
+2. Se precisa contexto: pegue só as últimas 20-30 mensagens com `before` ou `page`
+3. Pra análise completa, use `conversations_transcript` (formato condensado)
+
+## Operações em massa
+
+Pra atribuir labels, mover cards, etc em vários itens:
+- `kanban_bulk_bulk_actions` (cards Kanban)
+- `kanban_items_kanban_agents_create` em massa (passar array)
+- `automation_rules_*` (criar regras em vez de fazer manualmente)
+
+NÃO faça 50 PATCH requests individuais — bate rate limit.
+
+## Rate limiting
+
+LionChat tem rate limit por API token. Limites típicos:
+- ~500 req/min para read
+- ~100 req/min para write
+
+Se receber `429 Too Many Requests`:
+- Espere o `Retry-After` header
+- Reduza concorrência
+- Reavalie estratégia (provavelmente está fazendo loop ineficiente)
+
+## Quando NÃO usar IA pra escrever mensagens
+
+- Mensagens de cobrança / financeiras → use templates aprovados
+- Confirmação de venda → template + variáveis
+- Comunicação legal → revisão humana obrigatória
+
+IA é boa pra: triagem, classificação, resumo, sugestão de resposta, análise.
+
+## Variáveis de conta (account_variables)
+
+Pra dados que se repetem (slogans, endereços, horários):
+- `account_variables_create` UMA vez
+- Use em templates com `{{slogan}}`, `{{endereco}}`
+- Atualiza UMA vez, propaga pra todo lugar
+
+Nunca hard-code esses dados em respostas geradas.
+
+## Status codes a respeitar
+
+| Code | O que fazer |
+|---|---|
+| 200/201 | OK, processar resposta |
+| 204 | OK, sem corpo (típico de DELETE) |
+| 400 | Erro de input — leia mensagem e ajuste |
+| 401 | Token inválido/expirado — NÃO retry |
+| 403 | Sem permissão — não tente bypass |
+| 404 | Recurso não existe — talvez foi deletado |
+| 422 | Validação falhou — leia errors[] |
+| 429 | Rate limited — espere e retry |
+| 500/502/503 | Servidor — retry 1-2x com backoff |
+
+## Ordem de operações típicas
+
+### "Buscar todas conversas de um cliente específico"
+1. `contacts_search` com `q=email` → pega contact_id
+2. `contacts_show` com `include=conversations` OU
+3. Filter conversations: `conversations_list` com `q=email`
+
+### "Criar um card Kanban a partir de uma conversa"
+1. `funnels_list` → pegar funnel_id certo
+2. `kanban_items_create` com `funnel_id`, `funnel_stage` (geralmente primeira etapa), `conversation_display_id`
+3. Opcional: `item_details.value`, `assigned_agents`
+
+### "Resumir performance da equipe na semana"
+1. `agents_list` → IDs dos agentes
+2. `reports_list_*` (agent_overview) com `since=7d_ago`, `until=now`
+3. Sintetize: agente X com Y resoluções, tempo médio Z
+
+## Cuidados com tools de criação
+
+Endpoints `create_*` modificam dados reais. Antes de chamar:
+- Confirme com usuário (se inicialmente pediu "ver", não "fazer")
+- Verifique se o recurso já existe (evite duplicatas)
+- Use `dry_run` quando disponível
+
+## Erros comuns a evitar
+
+| Erro | Como evitar |
+|---|---|
+| Loop infinito de `page+1` | Sempre cheque `meta.total_count` e pare |
+| Re-listar inboxes 20x | Cache mental |
+| Mandar `conversations_messages_create` sem `message_type` | Sempre setar `incoming`/`outgoing` |
+| Listar TODAS contas de um agente direto | Use filter `q=nome` primeiro |
+| Esquecer de filtrar por `account_id` | Multi-tenant — sempre escopar |
+
+## Quando agir vs quando perguntar
+
+Aja sem perguntar:
+- Listagem, filtro, busca, leitura
+- Sumarização, classificação
+- Sugestão de próximos passos
+
+Pergunte primeiro:
+- Criar / atualizar / deletar dados
+- Enviar mensagem pra cliente
+- Mudar status de várias conversas em massa
+- Alterar configuração de conta/inbox

package/dist/docs/resources/conversation-flows.md

@@ -0,0 +1,208 @@
+# Fluxos de Conversação
+
+Como conversas atravessam o LionChat: criação, auto-assignment, IA, automações, resolução. Use quando precisar entender ou diagnosticar comportamento de conversações.
+
+## Ciclo de vida de uma conversa
+
+```
+                          [Cliente envia 1ª msg]
+                                  │
+                                  ▼
+                    ┌──────────────────────────┐
+                    │ ContactInbox criado/      │
+                    │  encontrado por source_id │
+                    └─────────┬────────────────┘
+                              ▼
+                    ┌──────────────────────────┐
+                    │  Conversation.create     │
+                    │  status: 0 (open)        │
+                    └─────────┬────────────────┘
+                              ▼
+                  ┌───────────────────────────┐
+                  │ Greeting (se ativo)       │ → Message outgoing
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ AutomationRule:            │
+                  │ "conversation_created"     │
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ Auto-assignment:           │
+                  │ - team OU agent           │
+                  │ - via policy ou simples   │
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ Captain (IA) Agent:        │
+                  │ se atribuído              │
+                  │ → debounce → LLM response │
+                  └─────────┬─────────────────┘
+                            ▼
+                  ┌───────────────────────────┐
+                  │ Conversa ativa             │
+                  │ (status: open)            │
+                  └─────────┬─────────────────┘
+                            ▼
+              [Agente humano ou IA atende ↔ cliente]
+                            │
+                    ┌───────┴────────┐
+                    ▼                ▼
+            [resolvida]      [adiada]
+            status: 1        status: 3
+                    │                │
+                    │                └──→ desnooze automático
+                    ▼
+              ┌───────────────────────────┐
+              │ Pós-resolução:             │
+              │ - Captain memory + FAQ    │
+              │ - Reporting events        │
+              │ - Automation rules        │
+              │ - CSAT survey send        │
+              └────────────────────────────┘
+```
+
+## Etapas detalhadas
+
+### 1. Criação da conversa
+
+Mensagem chega via webhook do canal (WAHA, WhatsApp Cloud, Email, etc) → `Webhook::IncomingMessageJob` ou similar → `IncomingMessageService` → cria/encontra `Contact`, `ContactInbox`, `Conversation`, `Message`.
+
+**Pontos importantes:**
+- `Conversation` sempre criada com `status = 0` (open)
+- `inbox_id` setado direto
+- `assignee_id` começa `null` (pendente atribuição)
+- `captain_assistant_id` começa `null` (a menos que automação atribua)
+
+### 2. Greeting (mensagem de boas-vindas)
+
+Se `inbox.greeting_enabled = true`:
+- Após criar a conversa, envia `inbox.greeting_message`
+- Vira `Message` outgoing automática
+- NÃO substitui resposta humana — só inicia a conversa
+
+### 3. AutomationRule: "conversation_created"
+
+Cada inbox/conta pode ter regras com `event_name: 'conversation_created'`. Elas rodam **antes** do auto-assignment.
+
+Ações comuns:
+- Atribuir agente/time específico
+- Adicionar labels
+- Marcar prioridade
+- Atribuir Captain Assistant (`captain_assistant_id`)
+
+Avaliação:
+- Condições combinadas com AND
+- Operadores: `equal_to`, `contains`, `includes`, `is_present`
+- Pode usar `inbox`, `content`, `country_code`, `email`, custom_attributes
+
+### 4. Auto-assignment
+
+Roda após automation rules. Lógica simplificada:
+
+```
+SE inbox.enable_auto_assignment_v2:
+  SE inbox.assignment_policy associada:
+    → Política decide (round-robin, balanced, etc)
+  SENAO:
+    → assignee_id fica null (manual)
+```
+
+V2 (Assignment Policy) é o motor moderno. V1 (campo `auto_assignment` simples) é legado.
+
+### 5. Captain (IA Agente)
+
+Se `captain_assistant_id` foi setado (manual ou via automação):
+- Mensagem incoming dispara `Captain::ResponseBuilderJob`
+- Job tem **debounce** (~10s) — agrupa mensagens em rajada
+- Chama LLM com prompt do assistant + histórico
+- LLM pode invocar tools (FAQ, update_contact, create_booking, etc)
+- Resposta vira `Message` outgoing com `sender_type: Captain::Assistant`
+
+**Quando IA é desativada manualmente:**
+- Agente clica em "Desativar AI" → `captain_assistant_id` vira null
+- `custom_attributes.captain_manually_disabled = true`
+- IA não responde mais nessa conversa (mesmo se nova msg)
+
+### 6. Estado "pending" (status 2)
+
+Conversa em "pending" significa "aguardando algo":
+- Cliente respondeu mas agente ainda não viu
+- OU agente respondeu e tá aguardando cliente
+- Geralmente movida automaticamente por automação ("se 24h sem resposta → pending")
+
+### 7. Resolução (status 1)
+
+Agente clica em "Resolver":
+- `status` → 1 (resolved)
+- `resolved_at` setado
+- Dispara `conversation_resolved` event
+- Listeners agem:
+  - `CaptainListener`: gera memory + FAQ se IA atendeu
+  - `HookListener`: dispara webhooks
+  - `AutomationRuleListener`: regras de `conversation_resolved`
+  - `ReportingEventListener`: salva métricas
+  - `CsatSurveyJob` (se config ativa): envia pesquisa CSAT
+
+### 8. Snoozed (status 3)
+
+Adia conversa:
+- `status` → 3 (snoozed)
+- `snoozed_until` setado (datetime futuro)
+- Job periódico `ReopenSnoozedConversationsJob` roda e reabre quando passa do `snoozed_until`
+
+### 9. Reopen
+
+Conversa resolvida que recebe nova mensagem do cliente:
+- Comportamento depende de config `inbox.lock_to_single_conversation`
+- Default: cria NOVA conversa (mantém histórico)
+- Se locked: reabre a mesma conversa (`status` volta a 0)
+
+## Estado relacional
+
+```
+Conversation
+  ├─ messages: array em ordem cronológica
+  ├─ contact: quem é o cliente
+  ├─ inbox: canal de origem
+  ├─ assignee: agente humano atual (null OK)
+  ├─ team: time atribuído (null OK)
+  ├─ captain_assistant: IA atribuída (null OK)
+  ├─ kanban_item: card vinculado (null OK)
+  └─ labels: tags aplicadas
+```
+
+## Como diagnosticar problemas
+
+### "Conversa não atribuiu ninguém"
+
+1. `inbox.enable_auto_assignment_v2` está true?
+2. `inbox.assignment_policy` está setado?
+3. Tem `InboxMember` ativos pra essa inbox?
+4. Tem `automation_rule` que poderia ter atribuído antes?
+
+### "IA não respondeu"
+
+1. `conversation.captain_assistant_id` está setado?
+2. Account tem OpenAI hook configurado?
+3. Captain feature ativa na conta? (`feature_captain_integration`)
+4. Custom attr `captain_manually_disabled = true`?
+5. Sidekiq job `Captain::ResponseBuilderJob` rodou? Tem erro no log?
+
+### "Conversa marcada como pending sem motivo"
+
+1. Tem automation rule com `event_name: conversation_updated` ou similar?
+2. Tem SLA policy ativando state change?
+3. Veio de external API call?
+
+## Eventos importantes (pra automation)
+
+| Evento | Quando dispara |
+|---|---|
+| `conversation_created` | Nova conversa |
+| `conversation_opened` | Status volta pra open (reabertura) |
+| `conversation_resolved` | Agente resolve |
+| `conversation_pending` | Status muda pra pending |
+| `conversation_updated` | Qualquer update |
+| `message_created` | Nova mensagem (incoming ou outgoing) |
+| `first_reply_created` | Primeira resposta humana |