@lionchat/mcp-server 0.4.3 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "MCP server for LionChat API — 547 tools + 10 resources + 9 prompts. Audit-log aware, completion API, progress notifications.",
   "type": "module",
   "main": "dist/index.js",