@lionchat/mcp-server 0.5.4 → 0.5.5

package/dist/docs/instructions.md

@@ -23,6 +23,7 @@ Account (conta/empresa)
  ├─ Funnel (funil Kanban) → FunnelStage (etapas)
  ├─ AutomationRule (regras de automação)
  ├─ Captain::Assistant (AI Agente / IA de atendimento)
+ │   └─ Captain::Scenario (instrução situacional; pode FIXAR parâmetro de tool em tool_bindings)
  ├─ AccountTask (agenda/tarefas)
  └─ Booking (agendamento de demonstração/reunião)
 ```
@@ -288,6 +289,8 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 | **Importar histórico** de caixa WhatsApp Cloud (QR) | `lionchat_inboxes_whatsapp_history_start` / `_status` / `_cancel` | Admin-only + flag `qr_history_import`; só caixa oficial. Acompanhe `state` no `_status` |
 | **Definir supervisor** de caixa | `lionchat_inbox_members_create` / `_update` com `supervisor_ids[]` | Supervisor vê TUDO da caixa mas fica fora do rodízio (ver abaixo) |
 | Saber se a IA deve TOCAR a ligação WP (Wavoip) / marcar recusada | `lionchat_wavoip_should_ring` / `lionchat_wavoip_flag_rejected` | Controle fino do toque de chamada na caixa QR Code |
+| Restringir agendas que a IA oferece | `lionchat_captain_assistants_update` (`config.booking_event_type_ids: [Int]`) | binding de agenda por cenário NÃO é settable via API |
+| Configurar o Copiloto (modelo/temperatura/prompt base) | `lionchat_copilot_settings_update` | admin-only; copiloto tem motor próprio (padrão temp 0.3) |
 
 ## 9. Quando NÃO chamar nenhuma ferramenta
 

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

@@ -161,6 +161,27 @@ Como a coleta de dados/cenários funciona hoje (importante pra diagnosticar "IA
   fica no "caderninho" da conversa (campo scenario_checklist, visível no card Raciocínio).
 - Sem AI Agente ativo na conversa = NENHUMA resposta de IA (motor V1 aposentado em 2026-06).
 
+## Cenários com parâmetro fixo e execução determinística (2026-06)
+
+- O admin pode FIXAR o parâmetro de uma ferramenta no cenário (campo scenario.tool_bindings): quais mídias enviar, qual funil+etapa do card, quais agendas no agendamento. "Deixar a IA decidir" = binding vazio.
+- Quando UM cenário fixa a tool, a execução vira determinística (a IA não escolhe): mídia e kanban são aplicados pós-turno pelo BindingResolver (ordem texto→ação, sem duplicar, idempotente); o agendamento força/restringe a agenda mas a IA ainda define data/hora.
+- Via MCP: scenarios_create/update persiste binding de send_media_asset e create_kanban_item/move_kanban_item (re-escopados por conta). O binding de create_booking NÃO é aceito pela API — pra limitar agendas via MCP, use config.booking_event_type_ids no assistente (captain_assistants_update).
+
+## Conhecimento passivo da IA: FAQ + artigos (RAG) (2026-06)
+
+- A IA já recebe no prompt a FAQ e os artigos da Central de Ajuda relevantes para a mensagem atual — automaticamente, sem chamar ferramenta. Só acontece quando há conteúdo cadastrado (FAQ/documento aprovado ou artigo publicado); sem conteúdo não gasta token nem embedding.
+- As ferramentas "Buscar FAQ" e "Buscar Artigos" são auto-gerenciadas: ligam sozinhas conforme o conteúdo e somem da tela de ferramentas (não são desligáveis por disabled_tools). Diagnóstico "IA não usa a base": confira se há FAQ APROVADA/documento, ou artigo PUBLICADO na Central de Ajuda.
+- A IA pode oferecer ao cliente o link do artigo (precisa de Portal com slug e domínio/FRONTEND_URL).
+
+## Anti-loop de ferramentas (custo) (2026-06)
+
+- Ferramentas (webhooks/custom tools e flows) que falham agora param sozinhas: a IA recebe aviso escalonado (1ª falha = no máximo 1 retry; 2ª+ da mesma tool = pare e siga sem ela ou transfira). Tetos por turno: 5 chamadas por ferramenta e 25 no total; ao estourar, a IA dá halt e cria nota mencionando um humano (sem desligar a IA).
+
+## Copilot age na conversa (2026-06)
+
+- O Copiloto do atendente tem motor próprio (modelo/temperatura da conta, padrão 0.3; prompt base em copilot_instructions), configurável em captain/copilot_settings (admin).
+- Ele EXECUTA ações na conversa aberta, dentro da permissão do atendente: ações reversíveis (kanban, etiqueta, nota, prioridade, atribuir, resolver, contato) na hora; ações que falam com o cliente (mídia, agendar mensagem, agendamento) viram proposta que o atendente confirma/cancela. Histórico é por conversa.
+
 ## Automações: atributo de Conversa vs de Contato (2026-06)
 
 Atributos customizados podem existir com o MESMO nome nos dois escopos (ex: utm_source).

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

@@ -118,6 +118,10 @@ Se `captain_assistant_id` foi setado (manual ou via automação):
 - 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`
+- Conhecimento passivo: a IA recebe FAQ + artigos relevantes no prompt sem chamar ferramenta (só se houver conteúdo).
+- Cenário pode FIXAR o parâmetro de uma tool (mídia/funil-etapa/agenda) → execução determinística (mídia/kanban pós-turno via BindingResolver).
+- Tool que falha aciona o anti-loop (aviso escalonado + tetos 5/tool e 25/turno).
+- Comentários do Instagram: chegam como mensagens (content_attributes.image_type='ig_comment' + in_reply_to_comment_id). Pra responder um comentário via API, mande a mensagem na conversa com content_attributes { reply_mode: 'private'|'public', in_reply_to_comment_id }. O AI Agente responde só DM (não comenta em post).
 
 **Quando IA é desativada manualmente:**
 - Agente clica em "Desativar AI" → `captain_assistant_id` vira null

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

@@ -163,6 +163,11 @@ o painel humano usa. IA e integrações NUNCA passam force_update. Endpoint dedi
 `PATCH /contacts/{id}/cadastral` (tool `contacts_update_cadastral`). NÃO grave cadastral como
 custom_attribute. Regra absoluta relacionada: NUNCA sobrescrever `phone_number` já preenchido.
 
+**Lead só com CPF (2026-06):** um lead só com CPF (sem telefone/email) agora vira contato real
+pesquisável — o CPF fica em `identifier` (único) com fallback em `additional_attributes.cadastral.cpf`.
+A identificação por CPF acontece na ingestão de webhooks (pagamento, Meta Lead Ads, webhook
+universal); a superfície REST de contatos não mudou.
+
 **Padrões de `source_id` por canal:**
 - Waha: `5511999999999@c.us` (1-on-1) ou `120363xxx@g.us` (grupo) ou `XXXX@lid` (LID)
 - WhatsApp Cloud: `5511999999999` (E.164 sem prefixo)
@@ -242,6 +247,8 @@ Captain::Assistant
 │     activation_label (etiqueta que ativa o agente — unica por conta),
 │     min_response_time / max_response_time (delay humanizado, 1-60s),
 │     disabled_tools (array de IDs de tools desativadas pro assistente),
+│     (faq_lookup/search_articles NÃO são desligáveis — auto-gerenciadas: carregam só quando há
+│       FAQ/documento ou artigo publicado, e são escondidas do endpoint captain_assistants_tools)
 │     offer_ids / media_asset_ids / booking_event_type_ids (arrays de IDs vinculados),
 │     products (array legado de produtos)
 ├── guardrails (jsonb array de strings — limites duros injetados no prompt, ex: anti-pitch)
@@ -257,10 +264,16 @@ Captain::Scenario (cenários do assistente — instruções inline, sem handoff)
 ├── instruction (text — tools referenciadas como links markdown [Titulo](tool://id))
 ├── tools (jsonb — auto-extraído da instruction)
 ├── enabled (bool)
-└── trigger_type (llm_interpreted [default] | on_assistant_activation | on_first_customer_message)
-      ⚠️ trigger_type NAO é editável via API hoje — todo cenário criado por API fica em
-      llm_interpreted (a IA decide aplicar lendo a conversa). Os modos programáticos só
-      via banco/console por enquanto.
+├── trigger_type (llm_interpreted [default] | on_assistant_activation | on_first_customer_message)
+│     ⚠️ trigger_type NAO é editável via API hoje — todo cenário criado por API fica em
+│     llm_interpreted (a IA decide aplicar lendo a conversa). Os modos programáticos só
+│     via banco/console por enquanto.
+└── tool_bindings (jsonb — parâmetro FIXADO pelo admin por tool; "IA decide" = ausente/vazio)
+      send_media_asset → { asset_ids: [Int] } | create_kanban_item / move_kanban_item →
+        { funnel_id: Int, stage: "<key>" } | create_booking → { event_type_ids: [Int] }
+      Obs: via API/MCP, scenarios_update SÓ persiste send_media_asset/create_kanban_item/
+        move_kanban_item. O binding create_booking é só de UI/runtime — NÃO round-trippa pela API.
+        Use config.booking_event_type_ids no assistente pra restringir agendas via MCP.
 
 Captain::AssistantResponse (FAQ)
 ├── assistant_id (FK)

package/dist/docs/resources/glossary.md

@@ -221,6 +221,15 @@ os de `user_ids` viram membros comuns. A resposta traz `is_supervisor` (boolean)
   aplicação fica no "caderninho do cenário" da conversa (scenario_checklist, card Raciocínio)
 - **Regra DITO ≠ SALVO**: a IA só considera coletado o dado que foi PERSISTIDO — salva cada dado
   na hora e não repergunta o que já salvou
+- **Cenário com parâmetro fixo (tool_bindings)**: o admin pode fixar o parâmetro de uma ferramenta do cenário — quais mídias enviar, qual funil+etapa criar/mover o card, quais agendas usar no agendamento. Com 1 cenário fixando a tool, a execução é DETERMINÍSTICA (a IA não escolhe): mídia/kanban rodam pós-turno (BindingResolver); o agendamento força/restringe a agenda mas a IA ainda escolhe a data/hora.
+- **Conhecimento passivo (RAG)**: a IA recebe automaticamente no prompt a FAQ e os artigos da Central de Ajuda relevantes para a mensagem — só quando a conta tem esse conteúdo (sem conteúdo = zero custo). Pode oferecer o link do artigo ao cliente. As ferramentas "Buscar FAQ"/"Buscar Artigos" são automáticas (não aparecem nem se ligam na tela de ferramentas).
+- **Anti-loop de ferramentas**: se uma ferramenta (webhook/custom tool ou flow) falha, a IA recebe aviso escalonado (1ª falha = tente 1x; 2ª = pare e siga/transfira) e para sozinha; tetos de 5 chamadas/ferramenta e 25/turno por mensagem.
+
+## Copilot (Copiloto do atendente)
+
+- Motor PRÓPRIO: usa account.custom_attributes['copilot_model'] e ['copilot_temperature'] (padrão 0.3), independente do agente conversacional. O agente selecionado dá só a base de conhecimento. Prompt base em copilot_instructions (admin, até 5000 chars). Config via endpoint captain/copilot_settings.
+- AGE na conversa aberta no painel (sem opt-in), dentro da permissão do atendente. Tools reversíveis (kanban, etiqueta, nota, prioridade, atribuir, resolver, contato/atributos) executam na hora; tools que falam com o cliente (enviar mídia, agendar mensagem, criar/reagendar agendamento) viram PROPOSTA e só executam quando o atendente confirma. Transferência/handoff/flows ficam de fora.
+- Histórico POR CONVERSA (copilot_threads.conversation_display_id): cada conversa mantém o seu Copiloto, não mistura.
 
 ## Account (Conta)
 

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

@@ -164,6 +164,12 @@ Um card individual dentro de uma etapa.
 
 Múltiplos agentes podem ter o mesmo card. `source` pode ser `manual`, `automation`, `inherited_from_conversation`.
 
+**Agente do card vira participante das conversas (2026-06):** atribuir um agente a um card do Kanban
+(via `kanban_agents` ou ao vincular uma conversa) agora também o adiciona como PARTICIPANTE de todas
+as conversas do card (a principal `conversation_display_id` + as de `linked_conversations`). É a 4ª
+forma de virar participante — aditivo e idempotente (não duplica nem remove os participantes que já
+existiam).
+
 ### linked_conversations — IMPORTANTE
 
 ```json

package/endpoints.json

@@ -7206,7 +7206,7 @@
     "description": "Lista todas as labels da conta. Lista labels/etiquetas paginados (per_page padrão 25, máximo 100). Retorna meta (contadores) + payload (array de label/etiqueta).",
     "category": "Labels",
     "params": [],
-    "returns": "{ payload: array de labels } (sem meta)",
+    "returns": "{ payload: array de labels, cada label com conversations_count e contacts_count (uso em conversas/contatos) }",
     "common_use_cases": [
       "Dashboard: contar/exibir labels/etiquetas",
       "Buscar com filtros antes de outra operação",
@@ -12052,7 +12052,7 @@
     "method": "POST",
     "path": "/api/v1/accounts/{account_id}/voip/calls",
     "title": "Iniciar Chamada",
-    "description": "Inicia uma chamada telefônica para um contato via Zenvia. Requer configuração VoIP ativa. Obrigatorios: contact_id.",
+    "description": "Inicia uma chamada telefônica para um contato via Zenvia. Requer configuração VoIP ativa. Obrigatorios: contact_id. Passe provider='vtcall' pra discar pelo PABX VTCall.",
     "category": "Chamadas",
     "params": [
       {
@@ -12075,6 +12075,13 @@
         "location": "body",
         "required": false,
         "description": "Número de origem"
+      },
+      {
+        "name": "provider",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Roteia o disparo: 'vtcall' disca pelo PABX VTCall (sem bina); ausente/outro = Zenvia"
       }
     ],
     "returns": "chamada VoIP criada",
@@ -14813,7 +14820,15 @@
     "title": "Conectar Google Calendar",
     "description": "Inicia o fluxo de conexao com Google Calendar. Lista configs Google Calendar paginados (per_page padrão 25, máximo 100). Retorna meta (contadores) + payload (array de config Google Calendar).",
     "category": "Google Calendar",
-    "params": [],
+    "params": [
+      {
+        "name": "return_to",
+        "type": "string",
+        "location": "query",
+        "required": false,
+        "description": "Pra onde voltar apos o OAuth (ex: 'agenda'); fora da whitelist = padrao"
+      }
+    ],
     "returns": "meta (contadores globais) + payload (array de configs Google Calendar)",
     "common_use_cases": [
       "Dashboard: contar/exibir configs Google Calendar",
@@ -24066,7 +24081,7 @@
     "method": "PATCH",
     "path": "/api/v1/accounts/{account_id}/inboxes/{id}",
     "title": "Atualizar Caixa de Entrada",
-    "description": "Atualiza configurações da caixa (nome, saudação, atribuição automática, atributos extras). MUDANÇA DE CONFIG — confirme com o usuário antes. additional_attributes.mark_as_seen (bool, default true, SÓ WhatsApp oficial, 2026-06-11): envia o visto/check azul quando o agente abre a conversa — desligar em coexistência app+API. ATENÇÃO: enviar additional_attributes substitui o objeto; para WAHA prefira não mexer nesse campo (config sensível).",
+    "description": "Atualiza configurações da caixa (nome, saudação, atribuição automática, atributos extras). MUDANÇA DE CONFIG — confirme com o usuário antes. additional_attributes.mark_as_seen (bool, default true, SÓ WhatsApp oficial, 2026-06-11): envia o visto/check azul quando o agente abre a conversa — desligar em coexistência app+API. ATENÇÃO: enviar additional_attributes substitui o objeto; para WAHA prefira não mexer nesse campo (config sensível). Email (sincronizacao de mao dupla, admin, via objeto channel): two_way_sync_enabled, sync_sent, sync_deletions, sync_read, delete_strategy.",
     "category": "Caixas de Entrada",
     "params": [
       {
@@ -24367,5 +24382,239 @@
       "lionchat_wavoip_should_ring",
       "lionchat_wavoip_calls"
     ]
+  },
+  {
+    "id": "lionchat_vtcall_settings_show",
+    "method": "GET",
+    "path": "/api/v1/accounts/{account_id}/voip/vtcall_settings",
+    "title": "Config VTCall (PABX)",
+    "description": "Mostra a configuracao do PABX VTCall da conta (servidor, gravacao, transcricao). Liberado pro agente saber se o botao de discar VTCall esta disponivel.",
+    "category": "Chamadas",
+    "params": [],
+    "returns": "{ configured, active, vtcall_server, gravar_audio, ai_summary_source, transcription_provider, transcription_language, has_transcription_key, auto_transcribe, current_user_has_ramal, webhook_url (admin) }",
+    "common_use_cases": [
+      "Saber se o VTCall esta configurado/ativo antes de discar",
+      "Conferir gravacao/transcricao da conta"
+    ],
+    "related_tools": [
+      "lionchat_vtcall_settings_update",
+      "lionchat_voip_calls_create"
+    ]
+  },
+  {
+    "id": "lionchat_vtcall_settings_update",
+    "method": "PATCH",
+    "path": "/api/v1/accounts/{account_id}/voip/vtcall_settings",
+    "title": "Salvar Config VTCall",
+    "description": "Salva a configuracao do PABX VTCall (admin). active e derivado no servidor (liga so quando ha servidor + token).",
+    "category": "Chamadas",
+    "params": [
+      {
+        "name": "vtcall_server",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Servidor do PABX VTCall"
+      },
+      {
+        "name": "vtcall_token",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Token de autenticacao do PABX"
+      },
+      {
+        "name": "gravar_audio",
+        "type": "boolean",
+        "location": "body",
+        "required": false,
+        "description": "Gravar audio das ligacoes"
+      },
+      {
+        "name": "auto_transcribe",
+        "type": "boolean",
+        "location": "body",
+        "required": false,
+        "description": "Transcrever automaticamente"
+      },
+      {
+        "name": "transcription_provider",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Provedor de transcricao"
+      },
+      {
+        "name": "transcription_api_key",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Chave da transcricao"
+      },
+      {
+        "name": "transcription_language",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Idioma da transcricao"
+      },
+      {
+        "name": "ai_summary_source",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Fonte do resumo por IA"
+      }
+    ],
+    "returns": "{ success: true } ou { error }",
+    "common_use_cases": [
+      "Configurar o PABX VTCall da conta"
+    ],
+    "related_tools": [
+      "lionchat_vtcall_settings_show",
+      "lionchat_vtcall_settings_test_connection"
+    ]
+  },
+  {
+    "id": "lionchat_vtcall_settings_test_connection",
+    "method": "POST",
+    "path": "/api/v1/accounts/{account_id}/voip/vtcall_settings/test_connection",
+    "title": "Testar Conexao VTCall",
+    "description": "Testa a conexao com o servidor VTCall configurado (admin).",
+    "category": "Chamadas",
+    "params": [],
+    "returns": "{ success: bool, error? }",
+    "common_use_cases": [
+      "Validar servidor/token do VTCall apos salvar"
+    ],
+    "related_tools": [
+      "lionchat_vtcall_settings_update"
+    ]
+  },
+  {
+    "id": "lionchat_vtcall_ramals_list",
+    "method": "GET",
+    "path": "/api/v1/accounts/{account_id}/voip/vtcall_ramals",
+    "title": "Listar Ramais VTCall",
+    "description": "Lista os agentes da conta com o ramal de cada um no VTCall (admin). 1 ramal por agente.",
+    "category": "Chamadas",
+    "params": [],
+    "returns": "{ agents: [{ user_id, name, email, ramal, ramal_id }] }",
+    "common_use_cases": [
+      "Montar a tela de mapeamento agente->ramal"
+    ],
+    "related_tools": [
+      "lionchat_vtcall_ramals_create"
+    ]
+  },
+  {
+    "id": "lionchat_vtcall_ramals_create",
+    "method": "POST",
+    "path": "/api/v1/accounts/{account_id}/voip/vtcall_ramals",
+    "title": "Definir Ramal VTCall",
+    "description": "Define/atualiza o ramal de um agente no VTCall (upsert por user_id, admin).",
+    "category": "Chamadas",
+    "params": [
+      {
+        "name": "user_id",
+        "type": "integer",
+        "location": "body",
+        "required": true,
+        "description": "ID do agente"
+      },
+      {
+        "name": "ramal",
+        "type": "string",
+        "location": "body",
+        "required": true,
+        "description": "Numero do ramal"
+      }
+    ],
+    "returns": "{ success: true, id }",
+    "common_use_cases": [
+      "Atribuir um ramal a um agente"
+    ],
+    "related_tools": [
+      "lionchat_vtcall_ramals_list",
+      "lionchat_vtcall_ramals_destroy"
+    ]
+  },
+  {
+    "id": "lionchat_vtcall_ramals_destroy",
+    "method": "DELETE",
+    "path": "/api/v1/accounts/{account_id}/voip/vtcall_ramals/{id}",
+    "title": "Remover Ramal VTCall",
+    "description": "Remove o ramal de um agente no VTCall (admin).",
+    "category": "Chamadas",
+    "params": [
+      {
+        "name": "id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID do registro de ramal"
+      }
+    ],
+    "returns": "{ success: true }",
+    "common_use_cases": [
+      "Tirar o ramal de um agente"
+    ],
+    "related_tools": [
+      "lionchat_vtcall_ramals_list"
+    ]
+  },
+  {
+    "id": "lionchat_copilot_settings_show",
+    "method": "GET",
+    "path": "/api/v1/accounts/{account_id}/captain/copilot_settings",
+    "title": "Config do Copiloto",
+    "description": "Mostra a config do motor do Copiloto do atendente (modelo, temperatura, prompt base). Admin-only.",
+    "category": "Assistentes",
+    "params": [],
+    "returns": "{ model, temperature, instructions }",
+    "common_use_cases": [
+      "Ver modelo/temperatura/prompt base do Copiloto"
+    ],
+    "related_tools": [
+      "lionchat_copilot_settings_update"
+    ]
+  },
+  {
+    "id": "lionchat_copilot_settings_update",
+    "method": "PATCH",
+    "path": "/api/v1/accounts/{account_id}/captain/copilot_settings",
+    "title": "Salvar Config do Copiloto",
+    "description": "Salva modelo, temperatura e prompt base do Copiloto (admin). Motor proprio, independente do agente conversacional (padrao temperatura 0.3).",
+    "category": "Assistentes",
+    "params": [
+      {
+        "name": "model",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Modelo de IA"
+      },
+      {
+        "name": "temperature",
+        "type": "number",
+        "location": "body",
+        "required": false,
+        "description": "Temperatura (0.0-2.0; padrao 0.3)"
+      },
+      {
+        "name": "instructions",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Prompt base do Copiloto (ate 5000 chars)"
+      }
+    ],
+    "returns": "{ model, temperature, instructions }",
+    "common_use_cases": [
+      "Ajustar o comportamento do Copiloto da conta"
+    ],
+    "related_tools": [
+      "lionchat_copilot_settings_show"
+    ]
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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",