@lionchat/mcp-server 0.2.1 → 0.3.1

package/dist/docs/resources/troubleshooting.md

@@ -0,0 +1,248 @@
+# Troubleshooting — Códigos de Erro Comuns
+
+Como interpretar e responder a erros do MCP do LionChat.
+
+## HTTP Status Codes
+
+### 200 OK / 201 Created
+Tudo certo. Use o body.
+
+### 204 No Content
+Sucesso, mas sem corpo. Comum em DELETE e algumas updates. NÃO espere JSON de volta.
+
+### 400 Bad Request
+Input malformado. Causas comuns:
+- JSON inválido
+- Campo obrigatório faltando
+- Tipo errado (passou string onde esperava number)
+
+**Ação:** Releia a mensagem de erro. Corrija o payload. NÃO retry sem mudar nada.
+
+### 401 Unauthorized
+Token de API inválido ou expirado.
+
+**Ação:** Parar. Reportar pro usuário que precisa renovar credenciais. NÃO retry — vai falhar igual.
+
+### 403 Forbidden
+Token válido, mas SEM permissão pra essa ação.
+
+Causas:
+- Agente tentando ação de admin
+- Conta diferente do escopo do token
+- Feature flag desativada na conta
+- Recurso pertence a outra conta (multi-tenant)
+
+**Ação:** NÃO bypass. Informar limitação ao usuário.
+
+### 404 Not Found
+Recurso não existe.
+
+Causas comuns:
+- ID errado
+- Recurso foi deletado
+- Está em outra conta
+- Endpoint URL errado
+
+**Ação:** Verificar se ID está correto. Se foi deletado, informar.
+
+### 422 Unprocessable Entity
+Dados passaram na sintaxe mas falharam validação.
+
+Exemplo de response:
+```json
+{
+  "errors": {
+    "email": ["já está em uso"],
+    "phone_number": ["formato inválido"]
+  }
+}
+```
+
+**Ação:** Ler `errors`, ajustar dados, reenviar.
+
+### 429 Too Many Requests
+Rate limit estourado.
+
+Response inclui header `Retry-After: 60` (segundos).
+
+**Ação:**
+- Esperar o tempo indicado
+- Reduzir concorrência
+- Avaliar se está fazendo loop ineficiente
+
+NÃO retry imediato — só piora.
+
+### 500 Internal Server Error
+Erro do servidor LionChat.
+
+**Ação:**
+- Retry 1x após 2-5 segundos
+- Se persiste, reportar pro usuário com timestamp/request ID
+
+### 502 Bad Gateway / 503 Service Unavailable
+Indisponibilidade temporária (deploy, manutenção, sobrecarga).
+
+**Ação:** Retry com backoff exponencial (2s, 4s, 8s). Máx 3 tentativas.
+
+### 504 Gateway Timeout
+Operação demorou demais.
+
+Causas:
+- Query muito pesada (sem filtro)
+- Export grande (use exports assíncronos)
+
+**Ação:** Reformular a chamada com filtros mais agressivos.
+
+## Erros específicos do MCP
+
+### "mcp_not_enabled"
+Status: 403
+
+A conta não tem a feature MCP habilitada.
+
+**Ação:** Pedir admin pra ativar no plano ou via Super Admin.
+
+### "admin_required"
+Status: 403
+
+Só administradores podem usar essa funcionalidade.
+
+**Ação:** Usuário com role `agent` precisa pedir pro admin.
+
+### "invalid_account"
+Status: 400 ou 404
+
+`account_id` não pertence ao usuário autenticado.
+
+**Ação:** Listar contas do user (`list_my_accounts`) e usar uma válida.
+
+### "feature_disabled"
+Status: 403
+
+Feature flag específica (ex: `feature_kanban`, `feature_captain`) está OFF.
+
+**Ação:** Reportar qual feature precisa ser ativada.
+
+## Erros de validação comuns
+
+### Conversation
+- `"contact must exist"` — passou `contact_id` inválido
+- `"inbox must exist"` — `inbox_id` errado
+- `"status invalid"` — use 0, 1, 2 ou 3 (open/resolved/pending/snoozed)
+
+### Contact
+- `"email has already been taken"` — duplicado na conta
+- `"phone_number has already been taken"` — mesmo problema
+- `"phone_number must be a valid number with country code"` — formato E.164: `+5511999999999`
+
+### Message
+- `"content can't be blank"` — mensagem vazia (use template se for attachment-only)
+- `"private must be boolean"` — true/false, não string
+
+### KanbanItem
+- `"funnel_stage does not exist in funnel"` — etapa inválida pro funil
+- `"conversation_display_id must exist"` — conversa não existe ou foi deletada
+- `"position must be a positive integer"` — não pode ser negativo
+
+## Cenários problemáticos
+
+### "Estou recebendo 401 mesmo com token correto"
+Possíveis causas:
+- Token foi revogado
+- Conta foi suspensa (`feature_account_suspended`)
+- Token de outra conta
+
+Verificar: `GET /api/v1/profile` (se 401 aqui, token tá inválido)
+
+### "GET retorna 200 mas POST/PATCH retorna 403"
+Token tem `scope: read` apenas. Precisa de token com scope completo pra escritas.
+
+### "Operação foi pelo MCP mas não aparece na UI"
+- Frontend pode estar com cache (refresh)
+- WebSocket pode estar caído
+- Pode ter sido criado em outra conta (verificar `account_id`)
+
+### "Timer/job rodou mas dados estão errados"
+Sidekiq pode estar retry-ando. Verificar:
+- Job tem `discard_on` apropriado?
+- Status final no banco vs UI
+
+### "Tool não está disponível"
+Possíveis razões:
+- MCP server não foi atualizado (`npm install -g @lionchat/mcp-server@latest`)
+- Feature flag bloqueando endpoint
+- Plano do cliente não inclui a feature
+
+### "Rate limit constante"
+Padrões que causam:
+- Polling agressivo (use webhooks)
+- Listar tudo sem paginar
+- Não cache de dados estáticos
+- Loop sem `break` apropriado
+
+## Webhooks como alternativa a polling
+
+Se você precisa monitorar mudanças em conversas/mensagens, NÃO faça polling:
+
+```
+Polling errado:
+  while True: GET /conversations every 5s → MUITO ruim
+```
+
+Use webhooks (config na conta):
+- `conversation_created`
+- `message_created`
+- `conversation_resolved`
+- Etc
+
+LionChat envia POST pro seu endpoint quando o evento dispara.
+
+## OAuth (apenas MCP Remote)
+
+### "invalid_client_metadata"
+Cliente OAuth registrado errado. Verifique:
+- `token_endpoint_auth_method` = `none` (pra Claude/ChatGPT)
+- `redirect_uris` exato (https, sem trailing slash extra)
+
+### "invalid_grant"
+Auth code expirou (vida curta — segundos). Refazer login.
+
+### "Conector desconectou sozinho"
+Geralmente: refresh_token expirou (TTL passou).
+
+Hoje no LionChat: TTL é ~100 anos. Se desconectar, provavelmente:
+- Token revogado manualmente
+- Conta suspensa
+- Restart do serviço MCP Remote
+
+### "Consent loop infinito"
+Bug conhecido: `Grant` não criado explicitamente. Atualizar MCP Remote pra versão >= 0.3.0.
+
+## Logs e debugging
+
+### Como pegar request ID
+Toda resposta da API tem header `X-Request-ID`. Inclua no relatório se algo falhar.
+
+### Como ver logs do MCP Server local
+```bash
+# Stdio MCP imprime em stderr — capture no Claude Desktop logs:
+~/Library/Logs/Claude/mcp*.log
+```
+
+### Como ver logs do MCP Remote (servidor produção)
+- Painel Portainer → serviço `mcp_remote` → logs
+- Cloudflare Worker logs (se proxy)
+- Sentry pra exceptions
+
+## Quando reportar pro suporte
+
+Reporte se:
+- 500/502/503 persistente após 3 retries
+- 401 com token recém-gerado
+- Dados sumindo sem ação clara
+- Comportamento inconsistente entre contas
+
+NÃO precisa reportar:
+- 4xx (você fez algo errado)
+- Rate limit (esperado)
+- 404 de recurso deletado

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: 8 (glossary, data-model, reports-guide, api-conventions, conversation-flows, kanban-deep-dive, best-practices, troubleshooting)`);
+        console.error(`Prompts registered: 8 (productivity_report, stuck_leads, weekly_recap, customer_health, inactive_contacts, team_load_balance, quality_audit, whatsapp_template_usage)`);
         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,90 @@
+// 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',
+    },
+    {
+        name: 'Fluxos de Conversacao',
+        uri: 'lionchat://docs/conversation-flows',
+        description: 'Ciclo de vida de uma conversa: criacao, greeting, auto-assignment, Captain IA, resolucao, snooze. Use pra diagnosticar comportamento de conversas.',
+        filename: 'conversation-flows.md',
+    },
+    {
+        name: 'Kanban Detalhado',
+        uri: 'lionchat://docs/kanban-deep-dive',
+        description: 'Estrutura completa do Kanban: Funnel, stages, KanbanItem, item_details, pipeline, activities. Use ao trabalhar com cards ou funis.',
+        filename: 'kanban-deep-dive.md',
+    },
+    {
+        name: 'Boas Praticas',
+        uri: 'lionchat://docs/best-practices',
+        description: 'Como economizar tokens, evitar rate limits, usar filtros, paginar. Consulte antes de workflows pesados ou loops em massa.',
+        filename: 'best-practices.md',
+    },
+    {
+        name: 'Troubleshooting',
+        uri: 'lionchat://docs/troubleshooting',
+        description: 'Codigos HTTP, erros comuns (401/403/422/429), erros MCP, debugging, quando reportar suporte. Use pra interpretar erros.',
+        filename: 'troubleshooting.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;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,GAAG,EAAE,oCAAoC;QACzC,WAAW,EACT,oJAAoJ;QACtJ,QAAQ,EAAE,uBAAuB;KAClC;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,GAAG,EAAE,kCAAkC;QACvC,WAAW,EACT,oIAAoI;QACtI,QAAQ,EAAE,qBAAqB;KAChC;IACD;QACE,IAAI,EAAE,eAAe;QACrB,GAAG,EAAE,gCAAgC;QACrC,WAAW,EACT,2HAA2H;QAC7H,QAAQ,EAAE,mBAAmB;KAC9B;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,GAAG,EAAE,iCAAiC;QACtC,WAAW,EACT,yHAAyH;QAC3H,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"}