@lionchat/mcp-server 0.4.2 → 0.4.3

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/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).