@lionchat/mcp-server 0.3.0 → 0.3.2

package/dist/docs/resources/kanban-deep-dive.md

@@ -0,0 +1,295 @@
+# Kanban — Guia Profundo
+
+Tudo sobre o módulo Kanban/CRM do LionChat: funis, etapas, cards, valor, automações, integrações com conversação.
+
+## Estrutura
+
+### Funnel (Funil)
+Container de etapas. Conta pode ter vários funis (ex: "Vendas", "Pós-venda", "Renovação").
+
+| Campo | Descrição |
+|---|---|
+| `id` | Identificador |
+| `name` | Nome do funil (ex: "Vendas B2B") |
+| `description` | Descrição livre |
+| `stages` | jsonb com etapas (ver abaixo) |
+| `archived` | Boolean — funis arquivados não aparecem na UI ativa |
+| `active` | Boolean — controla se aceita movimentação |
+| `settings` | jsonb — config customizada (ex: cores, automações) |
+
+### Stages (Etapas) — dentro de `funnel.stages`
+
+Stages NÃO são tabela separada. São armazenadas como jsonb dentro do Funnel:
+
+```json
+{
+  "novo_lead": {
+    "name": "Novo Lead",
+    "color": "#3B82F6",
+    "position": 1,
+    "description": "Lead ainda não qualificado"
+  },
+  "qualificado": {
+    "name": "Qualificado",
+    "color": "#10B981",
+    "position": 2,
+    "description": "Lead com interesse confirmado"
+  },
+  "ganho": {
+    "name": "Ganho",
+    "color": "#22C55E",
+    "position": 99
+  },
+  "perdido": {
+    "name": "Perdido",
+    "color": "#EF4444",
+    "position": 100
+  }
+}
+```
+
+### KanbanItem (Card)
+Um card individual dentro de uma etapa.
+
+| Campo | Descrição |
+|---|---|
+| `id` | Identificador |
+| `funnel_id` | Funil ao qual pertence |
+| `funnel_stage` | Chave da etapa (ex: `"novo_lead"`) |
+| `position` | Ordem dentro da etapa |
+| `stage_entered_at` | Quando entrou na etapa atual (pra métrica de tempo) |
+| `conversation_display_id` | Conversa principal vinculada |
+| `linked_conversations` | jsonb array `[{display_id: 123}, {display_id: 456}]` — múltiplas conversas |
+| `item_details` | jsonb (ver abaixo) |
+| `custom_attributes` | jsonb — campos custom (igual contatos) |
+| `assigned_agents` | jsonb array de agentes responsáveis |
+| `activities` | jsonb array — log de atividades |
+| `checklist` | jsonb array de tarefas dentro do card |
+| `timer_started_at`, `timer_duration` | Timer interno do card |
+
+### item_details (detalhes do card)
+
+```json
+{
+  "title": "Cliente XYZ - Plano Pro",
+  "value": 5000.0,
+  "priority": "high",
+  "description": "Cliente interessado em upgrade",
+  "notes": [
+    {"text": "Ligou pedindo proposta", "created_at": "2026-05-15T10:00:00Z"}
+  ],
+  "offers": [
+    {"id": 12, "title": "Pro 12 meses", "value": 4800}
+  ],
+  "custom_attributes": {
+    "origem_lead": "Facebook Ads"
+  }
+}
+```
+
+**`value`** é onde fica o valor monetário do negócio (usado em pipelines).
+
+### assigned_agents
+
+```json
+[
+  {
+    "id": 5,
+    "name": "Maria Souza",
+    "email": "maria@empresa.com",
+    "avatar_url": "https://...",
+    "assigned_at": "2026-05-14T09:00:00Z",
+    "assigned_by": 1,
+    "source": "manual"
+  }
+]
+```
+
+Múltiplos agentes podem ter o mesmo card. `source` pode ser `manual`, `automation`, `inherited_from_conversation`.
+
+### linked_conversations — IMPORTANTE
+
+```json
+[{"display_id": 123}, {"display_id": 456}]
+```
+
+**NUNCA gravar inteiros direto** — sempre objetos com `{display_id: ...}`. Inteiros diretos causam TypeError no `as_json`.
+
+## Posição (ordering)
+
+Cada KanbanItem tem `position` (integer). Cards ordenados ASC dentro da etapa.
+
+Reordenação:
+- API endpoint: `POST /api/v2/kanban/items/reorder`
+- Recebe array com nova ordem `[{id: 5, position: 1}, {id: 8, position: 2}]`
+- Recalcula `position` em todas as etapas afetadas
+
+Mover entre etapas:
+- API endpoint: `POST /api/v2/kanban/items/{id}/move`
+- Body: `{funnel_stage: "qualificado", position: 1}`
+- Atualiza `funnel_stage`, `stage_entered_at`, e `position`
+
+## Atividades (activities)
+
+Log automático de eventos do card:
+
+```json
+[
+  {
+    "type": "stage_changed",
+    "from": "novo_lead",
+    "to": "qualificado",
+    "by_user_id": 1,
+    "at": "2026-05-15T10:00:00Z"
+  },
+  {
+    "type": "agent_assigned",
+    "agent_id": 5,
+    "by_user_id": 1,
+    "at": "2026-05-15T10:01:00Z"
+  },
+  {
+    "type": "note_added",
+    "note_id": 42,
+    "by_user_id": 5,
+    "at": "2026-05-15T10:05:00Z"
+  }
+]
+```
+
+Tipos comuns: `created`, `stage_changed`, `agent_assigned`, `agent_removed`, `note_added`, `value_changed`, `priority_changed`, `archived`.
+
+## Checklist (tarefas dentro do card)
+
+```json
+[
+  {
+    "id": "abc-123",
+    "title": "Enviar proposta por email",
+    "checked": true,
+    "completed_at": "2026-05-15T10:00:00Z",
+    "completed_by": 5
+  },
+  {
+    "id": "abc-124",
+    "title": "Agendar follow-up",
+    "checked": false
+  }
+]
+```
+
+Útil pra workflows internos. Não confundir com `tasks` (que é módulo separado de tarefas globais).
+
+## Pipeline (visão por valor)
+
+Pipeline = soma de `item_details.value` agrupado por etapa.
+
+Exemplo:
+```
+Funil "Vendas"
+├── Novo Lead: 12 cards | R$ 47.000
+├── Qualificado: 8 cards | R$ 38.000
+├── Negociação: 3 cards | R$ 22.000
+├── Ganho: 5 cards | R$ 28.000 (fechados no mês)
+└── Perdido: 2 cards | R$ 4.000
+```
+
+Endpoint: `GET /api/v2/kanban/items/counts` retorna contagem + soma por etapa.
+
+## Funil arquivado vs ativo
+
+- `archived = true`: funil escondido da UI principal. Cards ainda existem mas não aparecem nas listas
+- `active = false`: bloqueia movimentação (modo "somente leitura")
+
+Use cases:
+- Arquivar funis antigos no fim do ano
+- Pausar funil em manutenção sem deletar cards
+
+## Integração com Conversation
+
+### Quando uma conversa vincula a um card
+- Manual via UI ("vincular ao Kanban")
+- Automação via `automation_rule.actions` com action `add_to_kanban`
+- API call em `POST /api/v2/kanban/items` com `conversation_display_id`
+
+### Como o card "sabe" sobre o cliente
+
+```
+KanbanItem
+  └─ conversation_display_id → Conversation
+                                  └─ contact → Contact (nome, telefone, email)
+```
+
+NÃO existe `contact_id` direto no KanbanItem. Sempre via conversation_display_id.
+
+### Múltiplas conversas no mesmo card
+
+`linked_conversations` permite agrupar várias conversas (ex: cliente que falou em WhatsApp e Email):
+
+```json
+[
+  {"display_id": 100},
+  {"display_id": 101},
+  {"display_id": 105}
+]
+```
+
+A `conversation_display_id` (singular) ainda é a "principal" — mas todas as `linked_conversations` aparecem na sidebar do card.
+
+## Automações relacionadas a Kanban
+
+AutomationRule com evento `kanban_item_created`, `kanban_item_moved`, `kanban_item_stage_changed`:
+
+```json
+{
+  "event_name": "kanban_item_moved",
+  "conditions": [
+    {"attribute_key": "funnel_stage", "operator": "equal_to", "value": "ganho"}
+  ],
+  "actions": [
+    {"action_name": "send_message", "params": ["Parabéns pelo fechamento!"]},
+    {"action_name": "add_label", "params": ["cliente-pagante"]}
+  ]
+}
+```
+
+## Bulk operations
+
+- `POST /api/v2/kanban/items/bulk_actions` — operações em massa (mover, atribuir, arquivar)
+- `POST /api/v2/kanban/items/import` — importar CSV de cards
+- `GET /api/v2/kanban/items/export` — exportar funil completo
+
+## Custom attributes em cards
+
+Igual contatos, cards têm `custom_attributes` (jsonb):
+
+```json
+{
+  "origem_lead": "Google Ads",
+  "campanha": "Black Friday 2026",
+  "score": 85,
+  "produto_interesse": "Plano Pro"
+}
+```
+
+Configurar atributos no Super Admin ou via API `/api/v1/custom_attribute_definitions`.
+
+## Métricas úteis (via GET /api/v2/kanban/items)
+
+- Tempo médio em cada etapa: `stage_entered_at` vs agora
+- Taxa de conversão: cards em "ganho" vs total criado no período
+- Pipeline ativo: soma de `value` em etapas != ganho/perdido
+- Velocity: cards movidos pra "ganho" por mês
+
+## Diagnóstico: "Card sumiu do funil"
+
+1. Está arquivado? `archived = true` em algum nível?
+2. Etapa atual existe ainda? (etapa removida do funil deixa card "órfão")
+3. `position` está faltando? (cards sem position vão pro fim)
+4. Está em outro funil? (mover entre funis muda `funnel_id`)
+
+## Diagnóstico: "Valor do pipeline errado"
+
+1. Algum card sem `item_details.value`?
+2. Cards arquivados estão sendo contados?
+3. Etapas "ganho"/"perdido" estão incluídas no cálculo?

package/dist/docs/resources/troubleshooting.md

@@ -0,0 +1,248 @@
+# Troubleshooting — Códigos de Erro Comuns
+
+Como interpretar e responder a erros do MCP do LionChat.
+
+## HTTP Status Codes
+
+### 200 OK / 201 Created
+Tudo certo. Use o body.
+
+### 204 No Content
+Sucesso, mas sem corpo. Comum em DELETE e algumas updates. NÃO espere JSON de volta.
+
+### 400 Bad Request
+Input malformado. Causas comuns:
+- JSON inválido
+- Campo obrigatório faltando
+- Tipo errado (passou string onde esperava number)
+
+**Ação:** Releia a mensagem de erro. Corrija o payload. NÃO retry sem mudar nada.
+
+### 401 Unauthorized
+Token de API inválido ou expirado.
+
+**Ação:** Parar. Reportar pro usuário que precisa renovar credenciais. NÃO retry — vai falhar igual.
+
+### 403 Forbidden
+Token válido, mas SEM permissão pra essa ação.
+
+Causas:
+- Agente tentando ação de admin
+- Conta diferente do escopo do token
+- Feature flag desativada na conta
+- Recurso pertence a outra conta (multi-tenant)
+
+**Ação:** NÃO bypass. Informar limitação ao usuário.
+
+### 404 Not Found
+Recurso não existe.
+
+Causas comuns:
+- ID errado
+- Recurso foi deletado
+- Está em outra conta
+- Endpoint URL errado
+
+**Ação:** Verificar se ID está correto. Se foi deletado, informar.
+
+### 422 Unprocessable Entity
+Dados passaram na sintaxe mas falharam validação.
+
+Exemplo de response:
+```json
+{
+  "errors": {
+    "email": ["já está em uso"],
+    "phone_number": ["formato inválido"]
+  }
+}
+```
+
+**Ação:** Ler `errors`, ajustar dados, reenviar.
+
+### 429 Too Many Requests
+Rate limit estourado.
+
+Response inclui header `Retry-After: 60` (segundos).
+
+**Ação:**
+- Esperar o tempo indicado
+- Reduzir concorrência
+- Avaliar se está fazendo loop ineficiente
+
+NÃO retry imediato — só piora.
+
+### 500 Internal Server Error
+Erro do servidor LionChat.
+
+**Ação:**
+- Retry 1x após 2-5 segundos
+- Se persiste, reportar pro usuário com timestamp/request ID
+
+### 502 Bad Gateway / 503 Service Unavailable
+Indisponibilidade temporária (deploy, manutenção, sobrecarga).
+
+**Ação:** Retry com backoff exponencial (2s, 4s, 8s). Máx 3 tentativas.
+
+### 504 Gateway Timeout
+Operação demorou demais.
+
+Causas:
+- Query muito pesada (sem filtro)
+- Export grande (use exports assíncronos)
+
+**Ação:** Reformular a chamada com filtros mais agressivos.
+
+## Erros específicos do MCP
+
+### "mcp_not_enabled"
+Status: 403
+
+A conta não tem a feature MCP habilitada.
+
+**Ação:** Pedir admin pra ativar no plano ou via Super Admin.
+
+### "admin_required"
+Status: 403
+
+Só administradores podem usar essa funcionalidade.
+
+**Ação:** Usuário com role `agent` precisa pedir pro admin.
+
+### "invalid_account"
+Status: 400 ou 404
+
+`account_id` não pertence ao usuário autenticado.
+
+**Ação:** Listar contas do user (`list_my_accounts`) e usar uma válida.
+
+### "feature_disabled"
+Status: 403
+
+Feature flag específica (ex: `feature_kanban`, `feature_captain`) está OFF.
+
+**Ação:** Reportar qual feature precisa ser ativada.
+
+## Erros de validação comuns
+
+### Conversation
+- `"contact must exist"` — passou `contact_id` inválido
+- `"inbox must exist"` — `inbox_id` errado
+- `"status invalid"` — use 0, 1, 2 ou 3 (open/resolved/pending/snoozed)
+
+### Contact
+- `"email has already been taken"` — duplicado na conta
+- `"phone_number has already been taken"` — mesmo problema
+- `"phone_number must be a valid number with country code"` — formato E.164: `+5511999999999`
+
+### Message
+- `"content can't be blank"` — mensagem vazia (use template se for attachment-only)
+- `"private must be boolean"` — true/false, não string
+
+### KanbanItem
+- `"funnel_stage does not exist in funnel"` — etapa inválida pro funil
+- `"conversation_display_id must exist"` — conversa não existe ou foi deletada
+- `"position must be a positive integer"` — não pode ser negativo
+
+## Cenários problemáticos
+
+### "Estou recebendo 401 mesmo com token correto"
+Possíveis causas:
+- Token foi revogado
+- Conta foi suspensa (`feature_account_suspended`)
+- Token de outra conta
+
+Verificar: `GET /api/v1/profile` (se 401 aqui, token tá inválido)
+
+### "GET retorna 200 mas POST/PATCH retorna 403"
+Token tem `scope: read` apenas. Precisa de token com scope completo pra escritas.
+
+### "Operação foi pelo MCP mas não aparece na UI"
+- Frontend pode estar com cache (refresh)
+- WebSocket pode estar caído
+- Pode ter sido criado em outra conta (verificar `account_id`)
+
+### "Timer/job rodou mas dados estão errados"
+Sidekiq pode estar retry-ando. Verificar:
+- Job tem `discard_on` apropriado?
+- Status final no banco vs UI
+
+### "Tool não está disponível"
+Possíveis razões:
+- MCP server não foi atualizado (`npm install -g @lionchat/mcp-server@latest`)
+- Feature flag bloqueando endpoint
+- Plano do cliente não inclui a feature
+
+### "Rate limit constante"
+Padrões que causam:
+- Polling agressivo (use webhooks)
+- Listar tudo sem paginar
+- Não cache de dados estáticos
+- Loop sem `break` apropriado
+
+## Webhooks como alternativa a polling
+
+Se você precisa monitorar mudanças em conversas/mensagens, NÃO faça polling:
+
+```
+Polling errado:
+  while True: GET /conversations every 5s → MUITO ruim
+```
+
+Use webhooks (config na conta):
+- `conversation_created`
+- `message_created`
+- `conversation_resolved`
+- Etc
+
+LionChat envia POST pro seu endpoint quando o evento dispara.
+
+## OAuth (apenas MCP Remote)
+
+### "invalid_client_metadata"
+Cliente OAuth registrado errado. Verifique:
+- `token_endpoint_auth_method` = `none` (pra Claude/ChatGPT)
+- `redirect_uris` exato (https, sem trailing slash extra)
+
+### "invalid_grant"
+Auth code expirou (vida curta — segundos). Refazer login.
+
+### "Conector desconectou sozinho"
+Geralmente: refresh_token expirou (TTL passou).
+
+Hoje no LionChat: TTL é ~100 anos. Se desconectar, provavelmente:
+- Token revogado manualmente
+- Conta suspensa
+- Restart do serviço MCP Remote
+
+### "Consent loop infinito"
+Bug conhecido: `Grant` não criado explicitamente. Atualizar MCP Remote pra versão >= 0.3.0.
+
+## Logs e debugging
+
+### Como pegar request ID
+Toda resposta da API tem header `X-Request-ID`. Inclua no relatório se algo falhar.
+
+### Como ver logs do MCP Server local
+```bash
+# Stdio MCP imprime em stderr — capture no Claude Desktop logs:
+~/Library/Logs/Claude/mcp*.log
+```
+
+### Como ver logs do MCP Remote (servidor produção)
+- Painel Portainer → serviço `mcp_remote` → logs
+- Cloudflare Worker logs (se proxy)
+- Sentry pra exceptions
+
+## Quando reportar pro suporte
+
+Reporte se:
+- 500/502/503 persistente após 3 retries
+- 401 com token recém-gerado
+- Dados sumindo sem ação clara
+- Comportamento inconsistente entre contas
+
+NÃO precisa reportar:
+- 4xx (você fez algo errado)
+- Rate limit (esperado)
+- 404 de recurso deletado

package/dist/index.js

@@ -49,8 +49,8 @@ async function main() {
         console.error(`Base URL: ${config.baseUrl}`);
         console.error(`Account: ${config.accountId}`);
         console.error(`Tools registered: ${toolCount}`);
-        console.error(`Resources registered: 4 (glossary, data-model, reports-guide, api-conventions)`);
-        console.error(`Prompts registered: 4 (productivity_report, stuck_leads, weekly_recap, customer_health)`);
+        console.error(`Resources registered: 10 (glossary, data-model, reports-guide, api-conventions, conversation-flows, kanban-deep-dive, best-practices, troubleshooting, flowbuilder-design-guide, flowbuilder-patterns)`);
+        console.error(`Prompts registered: 9 (productivity_report, stuck_leads, weekly_recap, customer_health, inactive_contacts, team_load_balance, quality_audit, whatsapp_template_usage, create_flow_brainstorm)`);
         if (config.categories) {
             console.error(`Categories filter: ${config.categories.join(', ')}`);
         }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,oFAAoF;AACpF,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACxF,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC;AAEpC,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,6FAA6F;QAC7F,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAE5B,+EAA+E;QAC/E,IACE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;YACtC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;YACrC,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EACrC,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC9F,CAAC;QAED,0FAA0F;QAC1F,gFAAgF;QAChF,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;YACE,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,OAAO;SACjB,EACD;YACE,YAAY,EAAE,qBAAqB,EAAE;YACrC,YAAY,EAAE;gBACZ,KAAK,EAAE,EAAE;gBACT,SAAS,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE;gBACnD,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;aAChC;SACF,CACF,CAAC;QAEF,wEAAwE;QACxE,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAE1C,uFAAuF;QACvF,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAExD,6EAA6E;QAC7E,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAC1B,eAAe,CAAC,MAAM,CAAC,CAAC;QAExB,iFAAiF;QACjF,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,KAAK,CAAC,aAAa,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,KAAK,CAAC,YAAY,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QAC9C,OAAO,CAAC,KAAK,CAAC,qBAAqB,SAAS,EAAE,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,CAAC,wMAAwM,CAAC,CAAC;QACxN,OAAO,CAAC,KAAK,CAAC,+LAA+L,CAAC,CAAC;QAC/M,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,sBAAsB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,kEAAkE;QAClE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;QAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/resources.js

@@ -29,6 +29,42 @@ export const RESOURCES = [
         description: 'Auth, paginacao, filtros, datas, codigos HTTP, rate limits. Use quando tiver duvida sobre como chamar endpoint.',
         filename: 'api-conventions.md',
     },
+    {
+        name: 'Fluxos de Conversacao',
+        uri: 'lionchat://docs/conversation-flows',
+        description: 'Ciclo de vida de uma conversa: criacao, greeting, auto-assignment, Captain IA, resolucao, snooze. Use pra diagnosticar comportamento de conversas.',
+        filename: 'conversation-flows.md',
+    },
+    {
+        name: 'Kanban Detalhado',
+        uri: 'lionchat://docs/kanban-deep-dive',
+        description: 'Estrutura completa do Kanban: Funnel, stages, KanbanItem, item_details, pipeline, activities. Use ao trabalhar com cards ou funis.',
+        filename: 'kanban-deep-dive.md',
+    },
+    {
+        name: 'Boas Praticas',
+        uri: 'lionchat://docs/best-practices',
+        description: 'Como economizar tokens, evitar rate limits, usar filtros, paginar. Consulte antes de workflows pesados ou loops em massa.',
+        filename: 'best-practices.md',
+    },
+    {
+        name: 'Troubleshooting',
+        uri: 'lionchat://docs/troubleshooting',
+        description: 'Codigos HTTP, erros comuns (401/403/422/429), erros MCP, debugging, quando reportar suporte. Use pra interpretar erros.',
+        filename: 'troubleshooting.md',
+    },
+    {
+        name: 'FlowBuilder Design Guide',
+        uri: 'lionchat://docs/flowbuilder-design-guide',
+        description: 'OBRIGATORIO antes de criar/editar fluxo. Arvore de decisao por necessidade, schema por tipo de node (com handles expostos), regras de layout/positioning, erros comuns, checklist pre-submit.',
+        filename: 'flowbuilder-design-guide.md',
+    },
+    {
+        name: 'FlowBuilder Patterns',
+        uri: 'lionchat://docs/flowbuilder-patterns',
+        description: '10 templates de fluxos prontos pra adaptar: saudacao, captura, qualificacao BANT, CSAT, horario comercial, IA intent, re-engajamento, escalation, agendamento, webhook. Cada um com layout valido e handles certos.',
+        filename: 'flowbuilder-patterns.md',
+    },
 ];
 function findDocsPath(filename) {
     const candidates = [

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,iEAAiE;AAEjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAS1D,MAAM,CAAC,MAAM,SAAS,GAAkB;IACtC;QACE,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,0BAA0B;QAC/B,WAAW,EACT,mIAAmI;QACrI,QAAQ,EAAE,aAAa;KACxB;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,4BAA4B;QACjC,WAAW,EACT,sGAAsG;QACxG,QAAQ,EAAE,eAAe;KAC1B;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,+BAA+B;QACpC,WAAW,EACT,4GAA4G;QAC9G,QAAQ,EAAE,kBAAkB;KAC7B;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,GAAG,EAAE,iCAAiC;QACtC,WAAW,EACT,iHAAiH;QACnH,QAAQ,EAAE,oBAAoB;KAC/B;CACF,CAAC;AAEF,SAAS,YAAY,CAAC,QAAgB;IACpC,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,SAAS,EAAE,mBAAmB,EAAE,QAAQ,CAAC;QAC9C,IAAI,CAAC,SAAS,EAAE,0BAA0B,EAAE,QAAQ,CAAC;KACtD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,gBAAgB,CACrB,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,GAAG,EACP;YACE,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,QAAQ,EAAE,eAAe;SAC1B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;YACZ,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,GAAG,CAAC,IAAI;wBACb,QAAQ,EAAE,eAAe;wBACzB,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,iEAAiE;AAEjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAS1D,MAAM,CAAC,MAAM,SAAS,GAAkB;IACtC;QACE,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,0BAA0B;QAC/B,WAAW,EACT,mIAAmI;QACrI,QAAQ,EAAE,aAAa;KACxB;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,4BAA4B;QACjC,WAAW,EACT,sGAAsG;QACxG,QAAQ,EAAE,eAAe;KAC1B;IACD;QACE,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,+BAA+B;QACpC,WAAW,EACT,4GAA4G;QAC9G,QAAQ,EAAE,kBAAkB;KAC7B;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,GAAG,EAAE,iCAAiC;QACtC,WAAW,EACT,iHAAiH;QACnH,QAAQ,EAAE,oBAAoB;KAC/B;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,GAAG,EAAE,oCAAoC;QACzC,WAAW,EACT,oJAAoJ;QACtJ,QAAQ,EAAE,uBAAuB;KAClC;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,GAAG,EAAE,kCAAkC;QACvC,WAAW,EACT,oIAAoI;QACtI,QAAQ,EAAE,qBAAqB;KAChC;IACD;QACE,IAAI,EAAE,eAAe;QACrB,GAAG,EAAE,gCAAgC;QACrC,WAAW,EACT,2HAA2H;QAC7H,QAAQ,EAAE,mBAAmB;KAC9B;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,iCAAiC;QACtC,WAAW,EACT,yHAAyH;QAC3H,QAAQ,EAAE,oBAAoB;KAC/B;IACD;QACE,IAAI,EAAE,0BAA0B;QAChC,GAAG,EAAE,0CAA0C;QAC/C,WAAW,EACT,+LAA+L;QACjM,QAAQ,EAAE,6BAA6B;KACxC;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,GAAG,EAAE,sCAAsC;QAC3C,WAAW,EACT,qNAAqN;QACvN,QAAQ,EAAE,yBAAyB;KACpC;CACF,CAAC;AAEF,SAAS,YAAY,CAAC,QAAgB;IACpC,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,SAAS,EAAE,mBAAmB,EAAE,QAAQ,CAAC;QAC9C,IAAI,CAAC,SAAS,EAAE,0BAA0B,EAAE,QAAQ,CAAC;KACtD,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAiB;IACjD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,gBAAgB,CACrB,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,GAAG,EACP;YACE,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,QAAQ,EAAE,eAAe;SAC1B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;YACZ,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC5D,CAAC;YACD,OAAO;gBACL,QAAQ,EAAE;oBACR;wBACE,GAAG,EAAE,GAAG,CAAC,IAAI;wBACb,QAAQ,EAAE,eAAe;wBACzB,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC;qBACtC;iBACF;aACF,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/endpoints.json

@@ -8817,7 +8817,7 @@
     "method": "POST",
     "path": "/api/v1/accounts/{account_id}/flows",
     "title": "Criar Flow",
-    "description": "Cria um flow (FlowBuilder) na conta. Requer Admin. flow_data segue formato Vue Flow {nodes:[], edges:[]}. NODE SCHEMA — start: {label}. send_message: {label, messageItems:[{id, type:'text', content}]} handles: success/no_response/error. wait_response: {label, waitTime, waitUnit:'minutes'|'seconds', validation:'any'|'options'|'regex', acceptedOptions:['1','2'] (se options), regexPattern (se regex), invalidMessage, maxRetries:3, saveTo:'variable'|'attribute'|'', saveVariable, saveAttrKey} — quando validation='options' os handles ficam 'option_{val}' + 'timeout'; senão 'success' + 'timeout' — NUNCA precisa de condition node depois. condition: {label, conditions:[{id, label, field, operator, value}]} handles = id de cada condicao + 'default'. action: {label, items:[{key, config:{...}}]} keys comuns assign_team({team_id}), assign_agent({agent_id}), add_label({labels:['slug',...]}), remove_label({labels}), change_status({status}), change_priority({priority}), mute_conversation({}), add_private_note({content}), create_kanban_item({funnel_id, funnel_stage,...}), move_kanban_stage({funnel_id, funnel_stage}), deactivate_flow({}), assign_captain({assistant_id}). api: {label, method, url, headers:[{key,value}], body, apiResponseVar}. set_variable: {label, variables:[{name, value}]}. wait: {label, waitTime, waitUnit}. EDGE SCHEMA: {id, source, target, sourceHandle (opcional, OBRIGATORIO casar com handle exposto pelo node source), type:'deletable', animated:true}. ERROS COMUNS QUE DEVEM SER EVITADOS: (1) action usa items[].config NAO items[].params; (2) send_message usa messageItems NAO items; (3) wait_response com validation='options' NAO precisa de condition node — use sourceHandle='option_X' diretamente; (4) sourceHandle inventado tipo 'c1','c2' nao funciona — sempre usar o handle real; (5) inbox_ids precisa vir aninhado em {flow:{inbox_ids:[]}} no PUT bruto, mas no MCP basta inbox_ids no nivel raiz. Cria novo flow. Obrigatórios: name, channel_type. Valida unicidade quando aplicável. Retorna o flow criado com ID atribuído.",
+    "description": "Cria um flow (FlowBuilder) na conta. Requer Admin. flow_data segue formato Vue Flow {nodes:[], edges:[]}. NODE SCHEMA — start: {label}. send_message: {label, messageItems:[{id, type:'text', content}]} handles: success/no_response/error. wait_response: {label, waitTime, waitUnit:'minutes'|'seconds', validation:'any'|'options'|'regex', acceptedOptions:['1','2'] (se options), regexPattern (se regex), invalidMessage, maxRetries:3, saveTo:'variable'|'attribute'|'', saveVariable, saveAttrKey} — quando validation='options' os handles ficam 'option_{val}' + 'timeout'; senão 'success' + 'timeout' — NUNCA precisa de condition node depois. condition: {label, conditions:[{id, label, field, operator, value}]} handles = id de cada condicao + 'default'. action: {label, items:[{key, config:{...}}]} keys comuns assign_team({team_id}), assign_agent({agent_id}), add_label({labels:['slug',...]}), remove_label({labels}), change_status({status}), change_priority({priority}), mute_conversation({}), add_private_note({content}), create_kanban_item({funnel_id, funnel_stage,...}), move_kanban_stage({funnel_id, funnel_stage}), deactivate_flow({}), assign_captain({assistant_id}). api: {label, method, url, headers:[{key,value}], body, apiResponseVar}. set_variable: {label, variables:[{name, value}]}. wait: {label, waitTime, waitUnit}. EDGE SCHEMA: {id, source, target, sourceHandle (opcional, OBRIGATORIO casar com handle exposto pelo node source), type:'deletable', animated:true}. ERROS COMUNS QUE DEVEM SER EVITADOS: (1) action usa items[].config NAO items[].params; (2) send_message usa messageItems NAO items; (3) wait_response com validation='options' NAO precisa de condition node — use sourceHandle='option_X' diretamente; (4) sourceHandle inventado tipo 'c1','c2' nao funciona — sempre usar o handle real; (5) inbox_ids precisa vir aninhado em {flow:{inbox_ids:[]}} no PUT bruto, mas no MCP basta inbox_ids no nivel raiz. Cria novo flow. Obrigatórios: name, channel_type. Valida unicidade quando aplicável. Retorna o flow criado com ID atribuído. POSITIONING (CRITICO): cada node DEVE ter position:{x,y}. Sem isso, todos empilham no canvas no (0,0). Regra basica de layout: start em {x:50,y:300}, espaco horizontal +320 entre nodes sequenciais, ramificacoes em +/-150 vertical. ANTES DE GERAR JSON consulte o resource lionchat://docs/flowbuilder-design-guide (schema completo de cada tipo de node, handles expostos, erros comuns, checklist) e lionchat://docs/flowbuilder-patterns (10 templates prontos pra adaptar). BRAINSTORMING: se faltou info critica (canal, gatilho, conteudo), use o prompt create_flow_brainstorm como banco de perguntas sugeridas — pergunte SO o que falta, sem checklist forcado. APOS GERAR: rode o checklist da secao 6 do design guide antes de submeter (1 node start, todo node com id unico + position + data, todo edge com sourceHandle valido). NUNCA invente sourceHandle (no condition use cond_0/cond_1/default, no wait_response options use option_X, no AI intent use intent_<opcao>).",
     "category": "Flows",
     "params": [
       {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "0.3.0",
-  "description": "MCP server for LionChat API — 547 tools + 4 resources + 4 prompts for AI agents",
+  "version": "0.3.2",
+  "description": "MCP server for LionChat API — 547 tools + 10 resources + 9 prompts for AI agents (FlowBuilder enriched)",
   "type": "module",
   "main": "dist/index.js",
   "bin": {