@lionchat/mcp-server 0.2.0 → 0.3.0

package/dist/docs/resources/reports-guide.md

@@ -0,0 +1,219 @@
+# Guia de Relatórios e Métricas
+
+Como interpretar cada um dos endpoints de relatório (`lionchat_reports_*`) e métricas correlatas. Use sempre que o usuário pedir métricas, KPIs, dashboards ou comparativos.
+
+## ⚠️ Unidades de tempo
+
+**TODOS os tempos médios são retornados em SEGUNDOS.** Sempre converta antes de exibir:
+
+```
+245 segundos → "4 min 5 seg" ou "4:05"
+3600 segundos → "1 hora"
+86400 segundos → "24 horas" ou "1 dia"
+```
+
+## Endpoints disponíveis (19 total)
+
+### 1. `lionchat_reports_summary` — Resumo geral
+**Use quando o usuário pedir:** "como tá o desempenho?", "resumo da semana", "visão geral"
+
+**Retorna:**
+```json
+{
+  "conversations_count": 142,
+  "incoming_messages_count": 1250,
+  "outgoing_messages_count": 980,
+  "resolutions_count": 98,
+  "avg_first_response_time": 245,       // segundos
+  "avg_resolution_time": 7200,          // segundos
+  "previous": { ...mesma estrutura para comparativo... }
+}
+```
+
+**Parâmetros principais:**
+- `type`: `account` (padrão), `agent`, `inbox`, `label`, `team`
+- `since` / `until`: Unix timestamp (segundos) — período
+- `business_hours`: `true` excluí horários fora do expediente
+
+**Exemplo de uso:**
+```
+since = 7 dias atrás
+until = agora
+type = account
+→ retorna resumo dos últimos 7 dias da conta toda
+```
+
+### 2. `lionchat_reports_list` — Por agente
+**Use quando:** "produtividade por atendente", "ranking de agentes"
+
+Retorna array de métricas, uma por agente. Cada item:
+```json
+{
+  "id": 6,
+  "name": "Elvis",
+  "conversations_count": 23,
+  "avg_first_response_time": 180,
+  "avg_resolution_time": 5400,
+  "csat_score_average": 4.3,
+  "online_at_total": 28800   // segundos online no período
+}
+```
+
+### 3. `lionchat_reports_list_1` — Por time
+**Use quando:** "comparar times", "como está o time Premium vs Standard"
+
+Mesma estrutura por team_id.
+
+### 4. `lionchat_reports_list_2` — Por inbox
+**Use quando:** "qual canal está com mais demanda", "comparar WhatsApp vs Email"
+
+Mesma estrutura por inbox_id.
+
+### 5. `lionchat_reports_list_3` — Por label
+**Use quando:** "quantas conversas urgentes", "comparativo por label"
+
+Mesma estrutura por label.
+
+### 6. `lionchat_reports_list_4` — Por canal
+**Use quando:** "WhatsApp vs Email vs Webchat"
+
+Agrupa por `channel_type`.
+
+### 7. `lionchat_reports_list_5` — Relatórios detalhados
+**Use quando:** "dia a dia da última semana", "evolução temporal"
+
+Retorna timeseries (data + valor) para um metric específico:
+- `metric`: `conversations_count`, `incoming_messages_count`, `outgoing_messages_count`, `resolutions_count`, `avg_first_response_time`, `avg_resolution_time`, `reply_time`, `resolutions_count`
+- `group_by`: `day`, `week`, `month`, `year`
+- `since`/`until`: período
+
+### 8. `lionchat_reports_list_6` — Resumo do Bot
+**Use quando:** "como tá o bot resolvendo", "% de handoff pra humano"
+
+```json
+{
+  "bot_resolutions_count": 45,
+  "bot_handoffs_count": 12,
+  "bot_resolution_rate": 0.79
+}
+```
+
+### 9. `lionchat_reports_list_7` — Conversation Traffic (tráfego)
+**Use quando:** "horário de pico", "quando tem mais demanda"
+
+Retorna heatmap por hora do dia ou dia da semana:
+```json
+[
+  { "hour": 9, "conversations_count": 18 },
+  { "hour": 10, "conversations_count": 25 },
+  ...
+]
+```
+
+### 10. `lionchat_reports_list_8` — Agente em tempo real
+**Use quando:** "quem tá online agora", "carga atual"
+
+```json
+[
+  { "id": 6, "name": "Elvis", "status": "online", "open_count": 5, "unattended_count": 2 }
+]
+```
+
+### 11-15. CSAT
+- `lionchat_csat_metrics`: agregação (média, distribuição)
+- `lionchat_csat_list`: respostas individuais
+- `lionchat_csat_download`: CSV pra download
+
+### 16-18. SLA
+- `lionchat_sla_metrics`: hits / breaches por período
+- `lionchat_sla_list`: SLAs aplicadas a conversas
+- `lionchat_sla_download`: CSV
+
+### 19. `lionchat_reports_list_9` — Aggregated agent overview
+**Use quando:** combinação de tudo: produtividade + CSAT + SLA por agente
+
+## Padrões de interpretação
+
+### Comparando períodos
+Quando passa `since/until`, a maioria dos endpoints retorna `previous` com o período anterior de mesmo tamanho:
+
+```
+Esta semana: 142 conversas
+Semana anterior: 120 conversas
+→ Crescimento de 18%
+```
+
+**Dica:** sempre apresente comparativos pra dar contexto.
+
+### Business hours
+- Sem `business_hours: true`: tempos médios incluem madrugada/feriado (puxa pra cima)
+- Com `business_hours: true`: só conta período de atendimento configurado (mais preciso pra SLA)
+
+**Use business_hours: true** quando o usuário perguntar de "produtividade real" ou comparar com SLA.
+
+### CSAT
+- Score: 1-5 estrelas
+- Médias típicas: 4.0+ é bom, 3.5-4.0 é OK, abaixo de 3.5 é alerta
+- `csat_response_rate`: % de conversas resolvidas que ganharam resposta CSAT (taxa baixa = pouco feedback)
+
+### SLA
+- `breach_count` alto = problema sério, agentes não cumprindo prazos
+- Sempre olhar `hit_rate` (hits / (hits + breaches)) — meta 95%+
+
+## Workflows comuns
+
+### "Relatório semanal completo"
+```
+1. reports_summary com since=7d, type=account → visão geral
+2. reports_list (por agente) → ranking
+3. reports_list_3 (por label) → tipos de demanda
+4. csat_metrics → satisfação
+5. sla_metrics → cumprimento
+6. Compilar resumo em markdown
+```
+
+### "Quem tá com gargalo"
+```
+1. reports_list_8 (real-time) → quem tá com muita conversa aberta
+2. reports_list (por agente, últimos 7d) → quem tá com avg_first_response alto
+3. Cruzar: agente sobrecarregado E com tempo médio alto
+```
+
+### "Mês a mês evolução"
+```
+reports_list_5 com group_by=month, metric=conversations_count, since=12 meses atrás
+```
+
+## Pegadinhas comuns
+
+### ⚠️ Comparar agente "online_at_total"
+Tempo online inclui breaks, almoço, etc. Pra produtividade real, prefira:
+- `conversations_count / online_at_total` = conversas por hora online
+
+### ⚠️ Avg time pode ser enganador
+Mediana é mais representativa que média (1 conversa que durou 5 dias puxa tudo).
+**Mas o LionChat hoje só retorna média.** Reporte com ressalva: "Tempo MÉDIO de X — pode ter outliers."
+
+### ⚠️ Reports não pegam conversas em tempo real
+A maioria dos endpoints é eventually consistent (cache 5min). Pra info real-time use `conversations_meta`.
+
+### ⚠️ Comparativos de período
+`previous` tem o MESMO tamanho do período atual. Se since-until = 7d, previous = 7d antes.
+NÃO compare manualmente "esse mês vs mês passado" — passe `since/until` com mês inteiro e use o `previous` retornado.
+
+## Quando o usuário pede algo MUITO específico que não existe num endpoint
+
+Se a pergunta requer cálculos custom (ex: "conversas por agente que duraram mais de X minutos"):
+1. Liste as conversations com filtros
+2. Filtre no client-side
+3. Agrege e apresente
+
+Mas avise: "essa métrica não existe pronta — vou compor a partir de dados crus"
+
+## Custos de chamadas (importante!)
+
+Endpoints de relatório podem retornar **MUITOS** dados:
+- `reports_list_5` com `group_by=day, since=1 ano` → 365 datapoints
+- `csat_list` sem filtro → milhares
+
+**Sempre limite período** quando o usuário não foi específico. Se pediu "esta semana", use 7d. Se pediu "vamos ver tudo", confirme antes (ano inteiro pode ser muito).

package/dist/index.js

@@ -7,6 +7,9 @@ import { dirname, resolve } from 'path';
 import { loadConfig } from './config.js';
 import { LionChatClient } from './client.js';
 import { registerTools } from './tools.js';
+import { getServerInstructions } from './instructions.js';
+import { registerResources } from './resources.js';
+import { registerPrompts } from './prompts.js';
 // AIDEV-NOTE: Read version from package.json to avoid hardcoding in multiple places
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'));
@@ -21,20 +24,33 @@ async function main() {
             !config.baseUrl.includes('127.0.0.1')) {
             console.error('WARNING: Base URL is not HTTPS. API token may be transmitted in cleartext.');
         }
-        // AIDEV-NOTE: Create MCP server instance with name and version from package.json
+        // AIDEV-NOTE: Create MCP server com instructions, capabilities (tools/resources/prompts).
+        // Instructions explica modelo de dados, convencoes, glossario pra IA conectada.
         const server = new McpServer({
             name: 'lionchat-mcp-server',
             version: VERSION,
+        }, {
+            instructions: getServerInstructions(),
+            capabilities: {
+                tools: {},
+                resources: { subscribe: false, listChanged: false },
+                prompts: { listChanged: false },
+            },
         });
         // AIDEV-NOTE: Create HTTP client that wraps fetch calls to LionChat API
         const client = new LionChatClient(config);
         // AIDEV-NOTE: Register tools from endpoints.json, filtered by config.categories if set
         const toolCount = registerTools(server, config, client);
+        // AIDEV-NOTE: Resources (docs sob demanda) + Prompts (templates de workflow)
+        registerResources(server);
+        registerPrompts(server);
         // AIDEV-NOTE: Use stderr for logs — stdout is reserved for MCP JSON-RPC protocol
         console.error(`LionChat MCP Server v${VERSION}`);
         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)`);
         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":";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;AAE3C,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,iFAAiF;QACjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;YAC3B,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QAEH,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,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,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare function getServerInstructions(): string;

package/dist/instructions.js

@@ -0,0 +1,26 @@
+// AIDEV-NOTE: Carrega instructions.md de src/docs (dev) ou dist/docs (prod).
+// Sincronizado de docs-lionchat/mcp/instructions.md via sync-to-mcps.sh.
+// Conteudo enviado pra IA conectada via McpServer instructions option.
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let cachedInstructions = null;
+export function getServerInstructions() {
+    if (cachedInstructions !== null)
+        return cachedInstructions;
+    const candidates = [
+        join(__dirname, '../docs/instructions.md'),
+        join(__dirname, '../../src/docs/instructions.md'),
+    ];
+    for (const filepath of candidates) {
+        if (existsSync(filepath)) {
+            cachedInstructions = readFileSync(filepath, 'utf-8');
+            return cachedInstructions;
+        }
+    }
+    cachedInstructions =
+        'LionChat MCP Server — Plataforma brasileira de atendimento. Consulte resources/list pra mais info.';
+    return cachedInstructions;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,yEAAyE;AACzE,uEAAuE;AAEvE,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;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,IAAI,kBAAkB,GAAkB,IAAI,CAAC;AAE7C,MAAM,UAAU,qBAAqB;IACnC,IAAI,kBAAkB,KAAK,IAAI;QAAE,OAAO,kBAAkB,CAAC;IAE3D,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC;QAC1C,IAAI,CAAC,SAAS,EAAE,gCAAgC,CAAC;KAClD,CAAC;IAEF,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,kBAAkB,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACrD,OAAO,kBAAkB,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,kBAAkB;QAChB,oGAAoG,CAAC;IACvG,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,70 @@
+// AIDEV-NOTE: Registra MCP Prompts no McpServer (high-level SDK).
+// Templates JSON sincronizados de docs-lionchat/mcp/prompts/.
+// Cada prompt declara argumentos opcionais e um template Mustache-style ({{var|default}}).
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function findPromptsDir() {
+    const candidates = [
+        join(__dirname, '../docs/prompts'),
+        join(__dirname, '../../src/docs/prompts'),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+function loadPrompts() {
+    const dir = findPromptsDir();
+    if (!dir) {
+        console.error('[mcp] prompts directory not found');
+        return [];
+    }
+    const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    const prompts = [];
+    for (const file of files) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+            if (parsed.name && parsed.template)
+                prompts.push(parsed);
+        }
+        catch (err) {
+            console.error(`[mcp] failed to parse ${file}: ${err.message}`);
+        }
+    }
+    return prompts;
+}
+function renderTemplate(template, args) {
+    return template.replace(/\{\{(\w+)(?:\|([^}]*))?\}\}/g, (_m, name, fallback) => {
+        const value = args[name];
+        if (value !== undefined && value !== '')
+            return String(value);
+        return fallback ?? '';
+    });
+}
+export function registerPrompts(server) {
+    const prompts = loadPrompts();
+    for (const prompt of prompts) {
+        // Build Zod schema from argument list (all optional)
+        const argsSchema = {};
+        for (const arg of prompt.arguments) {
+            argsSchema[arg.name] = z.string().optional().describe(arg.description);
+        }
+        server.prompt(prompt.name, prompt.description, argsSchema, async (args) => {
+            const rendered = renderTemplate(prompt.template, args);
+            return {
+                description: prompt.title,
+                messages: [
+                    {
+                        role: 'user',
+                        content: { type: 'text', text: rendered },
+                    },
+                ],
+            };
+        });
+    }
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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"}

package/dist/resources.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+interface ResourceDef {
+    name: string;
+    uri: string;
+    description: string;
+    filename: string;
+}
+export declare const RESOURCES: ResourceDef[];
+export declare function registerResources(server: McpServer): void;
+export {};

package/dist/resources.js

@@ -0,0 +1,66 @@
+// AIDEV-NOTE: Registra MCP Resources no McpServer (high-level SDK).
+// 4 docs Markdown sincronizados de docs-lionchat/mcp/resources/.
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const RESOURCES = [
+    {
+        name: 'Glossario LionChat',
+        uri: 'lionchat://docs/glossary',
+        description: 'Glossario completo de termos, status codes, enums e conceitos. Consulte sempre que encontrar campo numerico ou enum desconhecido.',
+        filename: 'glossary.md',
+    },
+    {
+        name: 'Modelo de Dados',
+        uri: 'lionchat://docs/data-model',
+        description: 'Mapa completo de entidades, relacionamentos e FKs. Use quando precisar entender como dados conectam.',
+        filename: 'data-model.md',
+    },
+    {
+        name: 'Guia de Relatorios',
+        uri: 'lionchat://docs/reports-guide',
+        description: 'Como interpretar cada um dos 19 endpoints de relatorio. Unidades, comparativos, business hours, CSAT, SLA.',
+        filename: 'reports-guide.md',
+    },
+    {
+        name: 'Convencoes da API',
+        uri: 'lionchat://docs/api-conventions',
+        description: 'Auth, paginacao, filtros, datas, codigos HTTP, rate limits. Use quando tiver duvida sobre como chamar endpoint.',
+        filename: 'api-conventions.md',
+    },
+];
+function findDocsPath(filename) {
+    const candidates = [
+        join(__dirname, '../docs/resources', filename),
+        join(__dirname, '../../src/docs/resources', filename),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function registerResources(server) {
+    for (const res of RESOURCES) {
+        server.registerResource(res.name, res.uri, {
+            description: res.description,
+            mimeType: 'text/markdown',
+        }, async (uri) => {
+            const filepath = findDocsPath(res.filename);
+            if (!filepath) {
+                throw new Error(`Resource file missing: ${res.filename}`);
+            }
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'text/markdown',
+                        text: readFileSync(filepath, 'utf-8'),
+                    },
+                ],
+            };
+        });
+    }
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +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"}

package/dist/tools.js

@@ -270,6 +270,137 @@ function registerListCategoriesTool(server, allEndpoints) {
         };
     });
 }
+// AIDEV-NOTE: Meta tool — returns full Flow Builder schema reference (no API call).
+// Helps LLMs build correct flow_data without hitting trial-and-error on
+// node types, action keys, source handles, etc.
+function registerFlowsSchemaReferenceTool(server) {
+    const reference = `LIONCHAT FLOW BUILDER — SCHEMA REFERENCE
+
+flow_data tem o formato Vue Flow: { nodes: [...], edges: [...] }.
+
+═══ NODE GERAL ═══
+{ "id": "string-unico", "type": "start|send_message|wait_response|condition|action|api|set_variable|wait|randomizer|update_group|ai|end", "position": {"x":0,"y":0}, "data": { ... } }
+
+═══ NODE TYPES + source handles ═══
+
+▸ start
+  data: { label }
+  (sem handles — start tem so output default pro proximo node)
+
+▸ send_message
+  data: { label, messageItems: [
+    { id, type:"text", content },
+    { id, type:"image", url, caption },
+    { id, type:"template", template_name, ... }
+  ]}
+  Handles: "success", "no_response" (se timeout), "error", "window_closed" (WhatsApp API Official).
+  Se messageItem text com buttons_enabled=true: gera "button_{value}" por botao.
+
+▸ wait_response
+  data: {
+    label, waitTime, waitUnit: "minutes"|"seconds",
+    validation: "any"|"options"|"regex",
+    acceptedOptions: ["1","2"],     // se validation='options'
+    regexPattern,                    // se validation='regex'
+    invalidMessage, maxRetries,
+    saveTo: "variable"|"attribute"|"",
+    saveVariable, saveAttrKey
+  }
+  Handles validation='options': "option_{val}" por opcao + "timeout"
+  Handles outros: "success" + "timeout"
+  IMPORTANTE: validation='options' ja roteia por opcao — NAO precisa condition depois.
+
+▸ condition
+  data: { label, conditions: [
+    { id, label, field, operator, value, valueType }
+  ]}
+  Handles: id de cada condicao + "default" (fallback).
+
+▸ action
+  data: { label, items: [
+    { key, config: {...} }
+  ]}
+  ATENCAO: items[].config NAO items[].params.
+  Keys validas:
+    Conversa: assign_agent({agent_id}), assign_team({team_id}),
+      change_status({status,snooze_option}), change_priority({priority}),
+      mute_conversation({}), add_private_note({content}),
+      send_email_transcript({email}), deactivate_flow({}),
+      assign_captain({assistant_id}), deactivate_captain({})
+    Contato: add_label({labels:[...]}), remove_label({labels:[...]}),
+      update_attribute({attr_source,attr_key,attr_value})
+    Kanban: create_kanban_item({funnel_id,funnel_stage,...}),
+      move_kanban_stage({funnel_id,funnel_stage}),
+      set_won({funnel_id}), set_lost({funnel_id,lost_reason}),
+      assign_agent_card({funnel_id,agent_id}),
+      add_card_note({funnel_id,text})
+  Handles: "success", "error"
+
+▸ api
+  data: { label, method, url, headers:[{key,value}], body, apiResponseVar }
+  Handles: "success", "error"
+
+▸ set_variable
+  data: { label, variables: [{name,value}] }
+
+▸ wait
+  data: { label, waitTime, waitUnit }
+
+▸ randomizer
+  data: { label, branches:[{id,percent}] }
+  Handles: id de cada branch.
+
+═══ EDGES ═══
+[{ "id", "source", "target", "sourceHandle", "type":"deletable", "animated":true }]
+sourceHandle OBRIGATORIO casar com handle exposto pelo node source.
+
+═══ ERROS COMUNS ═══
+1. action items[].config (nao params)
+2. send_message messageItems (nao items)
+3. wait_response validation='options' roteia por handle 'option_X' — NAO use condition depois
+4. sourceHandle precisa ser o handle REAL do node source ('success', 'option_1', 'timeout', 'no_response', 'c1' do condition, etc)
+5. inbox_ids no MCP vai no nivel raiz; no PUT bruto vai em {flow:{inbox_ids:[]}}
+6. send_message com buttons gera 'button_{value}' (value do botao, nao titulo)
+7. condition.field aceita liquid: '{{conversation.team_id}}', '{{contact.attributes.cpf}}', '{{var_nome}}'
+
+═══ EXEMPLO MINIMO — Menu 3 opcoes ═══
+{
+  "nodes": [
+    {"id":"s1","type":"start","position":{"x":50,"y":200},"data":{"label":"Inicio"}},
+    {"id":"m1","type":"send_message","position":{"x":300,"y":200},"data":{
+      "label":"Menu",
+      "messageItems":[{"id":"t1","type":"text","content":"Digite:\\n1 - Vendas\\n2 - Suporte\\n3 - Financeiro"}]
+    }},
+    {"id":"w1","type":"wait_response","position":{"x":600,"y":200},"data":{
+      "label":"Aguarda","waitTime":60,"waitUnit":"minutes",
+      "validation":"options","acceptedOptions":["1","2","3"],
+      "invalidMessage":"Digite 1, 2 ou 3.","maxRetries":3,
+      "saveTo":"variable","saveVariable":"menu"
+    }},
+    {"id":"a1","type":"action","position":{"x":900,"y":50},"data":{
+      "label":"Vendas","items":[{"key":"assign_team","config":{"team_id":24}}]
+    }},
+    {"id":"a2","type":"action","position":{"x":900,"y":200},"data":{
+      "label":"Suporte","items":[{"key":"assign_team","config":{"team_id":23}}]
+    }},
+    {"id":"a3","type":"action","position":{"x":900,"y":350},"data":{
+      "label":"Financeiro","items":[{"key":"assign_team","config":{"team_id":25}}]
+    }}
+  ],
+  "edges":[
+    {"id":"e1","source":"s1","target":"m1","type":"deletable","animated":true},
+    {"id":"e2","source":"m1","target":"w1","type":"deletable","animated":true},
+    {"id":"e3","source":"w1","sourceHandle":"option_1","target":"a1","type":"deletable","animated":true},
+    {"id":"e4","source":"w1","sourceHandle":"option_2","target":"a2","type":"deletable","animated":true},
+    {"id":"e5","source":"w1","sourceHandle":"option_3","target":"a3","type":"deletable","animated":true}
+  ]
+}`;
+    server.tool('lionchat_flows_schema_reference', 'Returns the full Flow Builder schema reference: node types, action keys, source handles, edge format, common pitfalls and a minimal working example. CALL THIS BEFORE building or editing a flow_data via lionchat_flows_create or lionchat_flows_update.', {}, { readOnlyHint: true, destructiveHint: false, idempotentHint: true }, async () => {
+        return {
+            content: [{ type: 'text', text: reference }],
+        };
+    });
+}
 // AIDEV-NOTE: Main entry point — reads endpoints.json, filters, and registers all tools + meta tools
 export function registerTools(server, config, client) {
     // AIDEV-NOTE: Resolve endpoints.json relative to compiled dist/ directory (one level up)
@@ -301,6 +432,7 @@ export function registerTools(server, config, client) {
     // AIDEV-NOTE: Always register meta tools regardless of category filters
     registerPingTool(server, config, client);
     registerListCategoriesTool(server, endpoints);
-    return filtered.length + 2; // +2 for ping and list_categories
+    registerFlowsSchemaReferenceTool(server);
+    return filtered.length + 3; // +3 for ping, list_categories, flows_schema_reference
 }
 //# sourceMappingURL=tools.js.map