@lionchat/mcp-server 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.4.3 — 2026-05-20
+
+### Corrigido
+
+- **Doc do wrapper de body** (`api-conventions.md`, `troubleshooting.md`, `instructions.md`): auditoria empirica derrubou o claim falso de "HTTP 500 silencioso sem wrapper". O Rails do projeto roda com `wrap_parameters: [:json]` global, entao body raiz e auto-wrappado na maioria dos endpoints. Doc reescrita com base em testes curl reais contra os controllers (`kanban_config`, `funnels`, `labels`, `custom_attribute_definitions`, `kanban_items` aceitam ambos os formatos).
+- **Pegadinha do `/contacts`**: documentada nova armadilha real — `POST /contacts` com wrapper `{"contact": {...}}` retorna 200 mas cria contato com campos vazios. Causa: `ContactsController` usa `params.permit(:name, ...)` direto, sem `require(:contact)`. **Sempre enviar body raiz pro `/contacts`**.
+- **`findDocsPath` em `src/resources.ts`**: agora cobre 3 layouts (`dist/docs/resources/` publicado, monorepo legado, `src/docs/` dev) pra evitar `null` quando rodado via `npx`.
+
+### Mudado
+
+- `scripts/extract-endpoints.ts` migrado de `require()` pra `import` (ESM). Adicionadas sub-categorias `Validacao WhatsApp` e `Chat Interno` no mapeamento de slugs.
+
+## 0.4.0 / 0.4.1 / 0.4.2 — 2026-05-19
+
+### Adicionado
+
+- **Completion API** — sugestoes de auto-complete pros parametros das tools (ex: lista `account_id`/`inbox_id` disponiveis). Reduz erro de id inexistente.
+- **Progress notifications** — operacoes longas reportam progresso em tempo real (import de contatos, exports, etc), em vez de ficar em silencio ate terminar.
+- **User-Agent customizado** — requests do MCP agora marcam origem MCP no `audit_log` do LionChat, separando do trafego normal.
+
+## 0.3.2 — 2026-05-19
+
+### Adicionado
+
+- **FlowBuilder enrichment** — Resource `flowbuilder-design-guide` com schema completo de nodes, handles por tipo, layout/positioning e erros comuns + `flowbuilder-patterns` com 10 templates prontos (saudacao, captura, qualificacao, CSAT, IA, etc) + Prompt `create_flow_brainstorm` pra estruturar fluxos antes de criar. LLMs agora tem material concreto pra montar `flow_data` sem chutar.
+
+## 0.3.1 — 2026-05-18
+
+### Adicionado
+
+- **Sprint 3 do MCP Knowledge Enrichment** — +4 Resources (`conversation-flows`, `kanban-deep-dive`, `best-practices`, `troubleshooting`) e +4 Prompts (`inactive_contacts`, `team_load_balance`, `quality_audit`, `whatsapp_template_usage`). Total: 10 Resources + 9 Prompts no servidor.
+
+## 0.3.0 — 2026-05-18
+
+### Adicionado
+
+- **MCP Instructions** carregadas no boot do servidor (~3K tokens) explicando data model, status codes, convenções de API e workflows tipicos pra qualquer LLM que conectar entender o contexto antes de chamar tools.
+- **4 Resources iniciais**: `glossary`, `data-model`, `reports-guide`, `api-conventions`.
+- **4 Prompts iniciais**: `productivity_report`, `stuck_leads`, `weekly_recap`, `customer_health`.
+- **Enriquecimento de 547 descriptions** das tools (48 → 183 chars em media), com `returns`, `common_use_cases` e `related_tools` em cada uma.
+
 ## 0.2.1 — 2026-05-13
 
 ### Adicionado

package/dist/docs/instructions.md

@@ -78,18 +78,23 @@ Account (conta/empresa)
 - `display_id`: número visível na UI da conversa (use este pra falar com humanos)
 - `source_id`: ID externo da plataforma origem (ex: `wamid.xxx` do WhatsApp)
 
-### Body wrapper — CRÍTICO
+### Body wrapper — use raiz por padrão
 
-A maioria dos POST/PUT/PATCH exige o body **wrapped no nome do recurso** (padrão Rails strong params). Sem o wrapper retorna HTTP 500 silencioso.
+O Rails tem `wrap_parameters: [:json]` global. Body JSON raiz é auto-wrapped no nome do recurso, então ambas as formas funcionam na maioria dos endpoints:
 
 ```json
 PUT /api/v1/accounts/43/kanban_config
-{ "kanban_config": { "win_reasons": [...] } }   ✅
-
-{ "win_reasons": [...] }                        ❌ 500
+{ "win_reasons": [...] }                          ✅ raiz (recomendado)
+{ "kanban_config": { "win_reasons": [...] } }     ✅ explícito (também OK)
 ```
 
-Como saber: se o param da tool no MCP tem ponto no nome (`kanban_config.win_reasons`, `funnel.name`), o body precisa do wrapper. Sem ponto (`message`, `phone`), vai raiz.
+**Exceção importante — `/contacts` SÓ aceita raiz.** Com wrapper, o `name`/`email`/`phone_number` somem silenciosamente e o contato é criado vazio:
+
+```json
+POST /api/v1/accounts/43/contacts
+{ "name": "Fulano", "phone_number": "+5511..." }  ✅
+{ "contact": { "name": "Fulano" } }                ⚠️ cria contato com name vazio
+```
 
 Detalhes completos em `lionchat://docs/api-conventions` → "Wrapper de body".
 

package/dist/docs/resources/api-conventions.md

@@ -19,62 +19,61 @@ Pra você via MCP: tudo já tá resolvido. O servidor MCP injeta o token correto
 
 Tokens são **por usuário**, não por conta. O mesmo token funciona em qualquer conta que o usuário tem acesso. O scoping por conta acontece via `account_id` no path.
 
-## Wrapper de body — REGRA CRÍTICA
+## Wrapper de body — como o Rails interpreta
 
-A maioria dos endpoints `POST/PUT/PATCH` espera o body **wrapped no nome do recurso**, herdando o padrão `params.require(:recurso).permit(...)` do Rails strong params.
+O projeto roda com `wrap_parameters format: [:json]` no Rails (config global). Na prática:
 
-### Padrão geral
+- Bodies JSON raiz são **auto-wrapped** pelo Rails no nome do recurso (derivado do controller).
+- Mandar `{"enabled": true}` em `PUT /kanban_config` é equivalente a mandar `{"kanban_config": {"enabled": true}}`.
+- Ambas as formas funcionam na maioria dos endpoints. Não existe "HTTP 500 silencioso por falta de wrapper" — esse claim era impreciso.
+
+### Padrão recomendado
+
+Use **body raiz** (sem wrapper). É mais curto, funciona em todos os endpoints listados abaixo, e evita a pegadinha do `/contacts`.
 
 ```http
 PUT /api/v1/accounts/43/kanban_config
 Content-Type: application/json
 
-{
-  "kanban_config": {
-    "win_reasons": [...],
-    "enabled": true
-  }
-}
+{ "win_reasons": [{"id": "wr-1", "title": "Preço competitivo"}] }
 ```
 
-**Se você manda `{"win_reasons": [...]}` direto (sem o wrapper) → HTTP 500 silencioso.** Rails levanta `ActionController::ParameterMissing` que vira 500 sem mensagem útil.
+### Comportamento por endpoint (validado empiricamente)
 
-### Recursos que exigem wrapper
+| Endpoint | Raiz | Com wrapper | Observação |
+|---|---|---|---|
+| `POST/PUT /kanban_config` | ✅ | ✅ | qualquer um |
+| `POST/PATCH /funnels` | ✅ | ✅ | qualquer um |
+| `POST/PUT /kanban_items` | ✅ | ✅ | controller usa `require(:kanban_item)` mas auto-wrap resolve |
+| `POST/PATCH /labels` | ✅ | ✅ | qualquer um |
+| `POST/PATCH /custom_attribute_definitions` | ✅ | ✅ | qualquer um |
+| `POST/PATCH /contacts` | ✅ | ⚠️ **drop silencioso** | Controller usa `params.permit(...)` na raiz sem `require(:contact)`. Com wrapper, o auto-wrap não duplica e os campos do body raiz ficam ausentes — o contato é criado com `name` vazio. **USE RAIZ.** |
+| `POST/PATCH /conversations` | ✅ | varia | conversa aceita raiz |
+| `POST /captain/copilot_threads` | ✅ | n/a | só raiz (`message`, `assistant_id`, `conversation_id`) |
+| `POST /voip/settings/create_child_account` | ✅ | n/a | só raiz (`nome`, `login`, `senha`) |
 
-| Endpoint | Wrapper |
-|---|---|
-| `POST/PUT /kanban_config` | `kanban_config: {...}` |
-| `POST/PATCH /funnels` | `funnel: {...}` |
-| `POST/PUT /kanban_items` | `kanban_item: {...}` |
-| `POST/PATCH /contacts` | `contact: {...}` |
-| `POST/PATCH /conversations` | `conversation: {...}` ou direto (varia) |
-| `POST/PATCH /custom_attribute_definitions` | sem wrapper (params raiz) |
-| `POST/PATCH /labels` | sem wrapper |
-| `POST /captain/copilot_threads` | sem wrapper (params raiz: `message`, `assistant_id`) |
-| `POST /voip/settings/create_child_account` | sem wrapper (raiz: `nome`, `login`, `senha`) |
+### Quando WRAPPER é obrigatório
+
+Praticamente nunca — exceto se você está testando legacy/curl e quer ser explícito. As tools do MCP geram params com nome `recurso.campo` (ex: `kanban_config.win_reasons`) só pra organizar a UI; no body final qualquer formato roda.
 
-### Como saber se precisa wrapper?
+### Listas substituem, não fazem merge
 
-1. **Olha o nome do tool no MCP** — params nomeados `recurso.campo` (com ponto) significa que precisa wrapper.
-2. Params nomeados sem ponto (`message`, `phone`, `title`) ficam direto no body raiz.
-3. Em caso de dúvida: tentar **com wrapper primeiro** (mais comum). Se 500, tentar sem.
+`win_reasons`, `loss_reasons`, `stages`, `linked_conversations`, etc. — quando você manda a lista, ela **substitui** a anterior por inteiro. Pra preservar, leia com GET primeiro e mande a lista completa.
 
-### Exemplo de listas dentro de wrapper
+### Estrutura interna das listas
 
-`kanban_config.win_reasons` espera array de **objetos** `{id, title}`, NÃO strings:
+`win_reasons` / `loss_reasons` aceitam array de **objetos** `{id, title}`, NÃO strings:
 
 ```json
 {
-  "kanban_config": {
-    "win_reasons": [
-      {"id": "wr-1", "title": "Preço competitivo"},
-      {"id": "wr-2", "title": "Indicação forte"}
-    ]
-  }
+  "win_reasons": [
+    {"id": "wr-1", "title": "Preço competitivo"},
+    {"id": "wr-2", "title": "Indicação forte"}
+  ]
 }
 ```
 
-Quando você envia uma lista, ela **substitui** a anterior por inteiro (não faz merge). Pra preservar, leia primeiro com GET.
+Strings simples (`"win_reasons": ["motivo"]`) causam erro de serialização.
 
 ## Restrições de formato em campos comuns
 

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

@@ -95,6 +95,28 @@ Se receber `429 Too Many Requests`:
 
 IA é boa pra: triagem, classificação, resumo, sugestão de resposta, análise.
 
+## Botão de pânico: pausar/retomar AI Agente (2026-05-22)
+
+Pra parar IMEDIATAMENTE um AI Agente (todas as conversas dele) sem perder configuração:
+
+```
+lionchat_captain_assistants_update id=<id> paused=true
+```
+
+O campo `paused` é **top-level** (não vai em `config`). Quando `true`:
+- Jobs de resposta automática são curto-circuitados (não chamam o LLM)
+- Follow-ups agendados não disparam
+- Callbacks agendados são limpos
+
+Pra reativar: `paused=false`. Toggle é auditado (`audited only: [:paused]`).
+
+**Janela de inconsistência:** ~5-8s. Jobs que já estão dentro do LLM no momento da pausa enviam a resposta mesmo. Use o botão pra parar **novas** respostas, não pra cancelar uma que já saiu.
+
+## Limite do prompt e cache OpenAI (2026-05-22)
+
+- `config.instructions` (system prompt do agente) aceita até **20.000 caracteres** (antes 10k). Acima de 15k, o frontend mostra aviso "lost in the middle" — prefira colocar instruções críticas no início ou final.
+- **Cache automático** ativo em todos os 15 modelos suportados (GPT-4.1 Nano até GPT-5.2 Pro, o1, o3, o4-mini). Desconto 50-75% no input cachado, sem configuração. Reuso do prompt do agente em múltiplas conversas maximiza a economia.
+
 ## Variáveis de conta (account_variables)
 
 Pra dados que se repetem (slogans, endereços, horários):

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

@@ -203,6 +203,36 @@ Conversation
 | `conversation_opened` | Status volta pra open (reabertura) |
 | `conversation_resolved` | Agente resolve |
 | `conversation_pending` | Status muda pra pending |
-| `conversation_updated` | Qualquer update |
+| `conversation_updated` | Acao na conversa — filtrada por `action_types` (UI: "Acao na conversa") |
 | `message_created` | Nova mensagem (incoming ou outgoing) |
 | `first_reply_created` | Primeira resposta humana |
+
+### Subtipos de `conversation_updated` (campo `action_types`)
+
+Ao criar/atualizar uma `automation_rule` com `event_name: 'conversation_updated'`, envie tambem
+o campo `action_types` (array de strings) pra filtrar quais mudancas disparam a regra. Vazio/nulo
+mantem comportamento legado (qualquer mudanca dispara — retrocompat com regras antigas).
+
+| Subtipo | Detectado quando muda |
+|---|---|
+| `label_added` | `label_list` (apos - antes nao vazio) |
+| `label_removed` | `label_list` (antes - apos nao vazio) |
+| `status_changed` | `status` |
+| `priority_changed` | `priority` |
+| `agent_assigned` | `assignee_id` |
+| `team_assigned` | `team_id` |
+| `custom_attribute_changed` | `custom_attributes` |
+| `language_changed` | `additional_attributes.conversation_language` |
+| `ai_agent_assigned` | `captain_assistant_id` |
+
+Exemplo de criacao via API:
+```json
+POST /api/v1/accounts/{account_id}/automation_rules
+{
+  "name": "Notificar quando etiqueta VIP entra",
+  "event_name": "conversation_updated",
+  "action_types": ["label_added"],
+  "conditions": [{"attribute_key": "labels", "filter_operator": "contains", "values": ["vip"]}],
+  "actions": [{"action_name": "send_email_to_team", "action_params": {"team_ids": [1], "message": "VIP!"}}]
+}
+```

package/dist/docs/resources/data-model.md

@@ -216,6 +216,7 @@ Captain::Assistant
 ├── account_id (FK)
 ├── name
 ├── description
+├── paused (boolean, default false) — botao de panico (2026-05-22). true = pausa respostas, follow-up e callbacks. Auditado. Top-level, NAO mora em config.
 ├── config (jsonb: model, temperature, instructions, feature_memory, feature_faq, ...)
 ├── guardrails (string[])
 ├── response_guidelines (string[])
@@ -248,8 +249,13 @@ AutomationRule
 ├── account_id (FK)
 ├── name
 ├── event_name (conversation_created, conversation_resolved, message_created, conversation_opened, conversation_updated)
+├── action_types (jsonb array) — subtipos de conversation_updated:
+│     label_added, label_removed, status_changed, priority_changed,
+│     agent_assigned, team_assigned, custom_attribute_changed,
+│     language_changed, ai_agent_assigned. Vazio/nulo = retrocompat (dispara em qualquer)
 ├── conditions (jsonb array)
 ├── actions (jsonb array)
+├── inbox_id (FK, opcional — usado em event_name=webhook)
 └── active (bool)
 
 Macro

package/dist/docs/resources/troubleshooting.md

@@ -75,36 +75,30 @@ NÃO retry imediato — só piora.
 ### 500 Internal Server Error
 Erro do servidor LionChat.
 
-**Causa mais comum (90% dos casos):** body sem o wrapper do recurso.
-
-```http
-PUT /api/v1/accounts/43/kanban_config
-{"win_reasons": [...]}   // ❌ 500 silencioso
-```
-
-Rails levanta `ActionController::ParameterMissing` que vira 500 sem mensagem útil. A request precisa ser:
-
-```http
-PUT /api/v1/accounts/43/kanban_config
-{"kanban_config": {"win_reasons": [...]}}   // ✅
-```
-
-Veja `api-conventions.md → Wrapper de body` pra tabela completa de quais endpoints exigem wrapper.
-
-**Outras causas:**
-- Estrutura do array errada (ex: `win_reasons: ["str"]` em vez de `[{id, title}]`)
-- Validação de modelo falha (cheque se o controller tem `validate :*` que rejeita o input)
+**Causas comuns:**
+- Estrutura interna de lista errada (ex: `win_reasons: ["str"]` em vez de `[{id, title}]`)
+- Tipos errados em campos (string onde espera int, hash onde espera array, etc)
+- Validação de modelo lança exceção não tratada
 - Bug genuíno do servidor
 
 **Ação:**
-- Primeiro: revisar wrapper e estrutura do payload
-- Se OK: retry 1x após 2-5 segundos
+- Revisar tipos e estrutura do payload contra `api-conventions.md` e `data-model.md`
+- Retry 1x após 2-5 segundos
 - Se persiste: reportar pro usuário com timestamp/request ID
 
+> Nota: o Rails do projeto roda com `wrap_parameters: [:json]` global, então body raiz é auto-wrapped no nome do recurso. Falta de wrapper **não** gera 500 silencioso na maioria dos endpoints — descarte essa hipótese e foque em tipos/estrutura. Detalhes em `api-conventions.md → Wrapper de body`.
+
 ### "param is missing or the value is empty: <recurso>"
-Status: 400 (às vezes)
+Status: 400 (raro)
+
+Aparece em endpoints que rodam `params.require(:algo)` com nome não-padrão (fora da convenção REST que o auto-wrap deduz). Solução: enviar wrapper explícito `{"<recurso>": {...}}`.
+
+### Contato criado com `name`/`phone` vazios após POST /contacts
+Não é 5xx — request volta 200, mas o contato fica sem os dados que você mandou.
+
+**Causa:** body foi enviado com wrapper (`{"contact": {"name": "..."}}`). O `ContactsController` usa `params.permit(:name, ...)` direto na raiz, sem `require(:contact)`. Como o auto-wrap não duplica quando o wrapper já está presente, os campos ficam só dentro de `params[:contact]` e o `permit` na raiz não pega.
 
-Exatamente o erro do wrapper faltando. Mesma solução: wrapar o body em `{<recurso>: {...}}`.
+**Solução:** mandar body raiz: `{"name": "Fulano", "phone_number": "+5511..."}`.
 
 ### 502 Bad Gateway / 503 Service Unavailable
 Indisponibilidade temporária (deploy, manutenção, sobrecarga).