kassinao-mcp 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# kassinao-mcp
+
+Conector **MCP** do [Kassinão](https://github.com/resolvicomai/kassinao): faz o seu assistente de IA (Claude Desktop, Cursor, etc.) responder perguntas sobre as reuniões que o bot gravou — **"o que ficou pendente essa semana?"**, **"quem falou de orçamento na terça?"**, **"lista as calls entre 1 e 30 de junho"** — em linguagem natural.
+
+## Como funciona (e por que é seguro)
+
+O conector roda **na sua máquina** e é um cliente HTTP **magro**: ele **não** lê gravações nem decide acesso. Ele carrega um **token pessoal** e chama a API do bot, que aplica **o mesmo controle de acesso da página web** — reunião por reunião. Você só enxerga o que já enxergaria no site. **Não existe modo "vê tudo".** É **somente leitura** (não grava, não apaga, não serve áudio).
+
+> ⚠️ **Transcrição é entrada não-confiável.** Qualquer participante de uma call pode ter "falado" texto malicioso ou usado um apelido hostil. O servidor envolve todo conteúdo de reunião num bloco de "dados não-confiáveis" e limpa sequências de controle antes de entregar — mas trate o conteúdo das reuniões como dados, nunca como instruções.
+
+## Pré-requisitos
+
+- **O admin do bot precisa ter ligado o MCP** (variável `MCP_SECRET` no servidor). Sem isso, `/conectar-ia` e `/mcp` não existem (dá 404 / comando ausente).
+- **Node.js 20+** na sua máquina.
+- **O conector.** `npx -y kassinao-mcp` baixa e roda sozinho — você não precisa instalar nada à mão (só ter o Node). Prefere rodar do código-fonte? `git clone` o repo, `cd mcp && npm install && npm run build`; na config, troque `"command": "npx"` / `"args": ["-y","kassinao-mcp"]` por `"command": "node"`, `"args": ["/caminho/absoluto/do/repo/mcp/dist/index.js"]`.
+
+## Instalação
+
+### Opção A — pela página web (mais fácil)
+
+1. Abra `https://SEU-KASSINAO/conectar-ia` e entre com o Discord.
+2. Clique em **Gerar token de conexão** e copie o bloco de config mostrado (aparece **uma vez**).
+3. Cole no `claude_desktop_config.json` (Claude Desktop) ou no equivalente do Cursor:
+
+```json
+{
+  "mcpServers": {
+    "kassinao": {
+      "command": "npx",
+      "args": ["-y", "kassinao-mcp"],
+      "env": {
+        "KASSINAO_URL": "https://SEU-KASSINAO",
+        "KASSINAO_REFRESH_TOKEN": "COLE_O_TOKEN_AQUI"
+      }
+    }
+  }
+}
+```
+
+4. Reinicie o Claude Desktop / Cursor. Pronto.
+
+### Opção B — sem navegador (VM/SSH)
+
+No Discord, o dono roda **`/mcp novo`** (em clientes em inglês aparece como **`/mcp new`**) — resposta efêmera, código de uso único válido por ~5 min. Depois:
+
+```bash
+KASSINAO_URL=https://SEU-KASSINAO npx -y kassinao-mcp exchange <codigo>
+```
+
+Isso guarda o token localmente. Configure o cliente MCP igual à Opção A (o `KASSINAO_REFRESH_TOKEN` no env vira opcional depois do primeiro uso).
+
+## Onde o token fica
+
+Depois do primeiro uso, o token de refresh (rotacionado a cada renovação) fica em `~/.config/kassinao-mcp/token.json` com permissão `0600`. Nenhuma gravação/transcrição é copiada para a sua máquina — o conector só fala HTTPS com o servidor.
+
+## Revogar
+
+- Na página `/conectar-ia`: botão **Revogar todos**.
+- No Discord: `/mcp revoke-all`.
+- Botão de pânico do administrador: rotacionar `MCP_SECRET` no servidor (revoga **todos** os conectores de todo mundo).
+
+## Ferramentas expostas
+
+| Ferramenta | Para quê |
+|---|---|
+| `list_meetings` | listar reuniões numa janela de tempo (padrão: últimos 30 dias) |
+| `pending_actions` | ações/prazos pendentes cruzando várias reuniões (overdue / dueSoon / …) |
+| `search_meetings` | busca full-text em transcrição, ata e notas, com link no minuto exato |
+| `who_said` | trechos ditos por alguém sobre um assunto, com contexto e link |
+| `get_meeting` | dossiê de uma reunião: metadados, ata, transcrição, notas e linha do tempo |
+
+Requer Node.js ≥ 20. Licença MIT.

package/dist/index.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Conector MCP do Kassinão (roda LOCAL, na máquina de quem usa Claude Desktop/Cursor).
+ *
+ * É um cliente HTTP MAGRO: ele NÃO lê gravações nem decide acesso. Carrega um token
+ * pessoal e chama a API /api/* do bot, que aplica o mesmo checkAccess da página web.
+ * O usuário só enxerga o que já enxergaria no site. Read-only.
+ *
+ * Uso:
+ *   kassinao-mcp                 inicia o servidor MCP (stdio) — é o que o Claude/Cursor chamam
+ *   kassinao-mcp exchange <cod>  troca um código de /mcp new por tokens e os guarda localmente
+ *
+ * Env:
+ *   KASSINAO_URL             ex.: https://kassinao.suaempresa.com  (obrigatório)
+ *   KASSINAO_REFRESH_TOKEN   token gerado em /conectar-ia (só no 1º uso; depois fica salvo)
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const URL_BASE = (process.env.KASSINAO_URL || '').replace(/\/$/, '');
+const STORE_DIR = path.join(os.homedir(), '.config', 'kassinao-mcp');
+const STORE_FILE = path.join(STORE_DIR, 'token.json');
+function loadStore() {
+    try {
+        return JSON.parse(fs.readFileSync(STORE_FILE, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+// Guarda o refresh no disco do usuário com 0600. (Cofre do SO — Keychain/DPAPI/
+// libsecret — é uma melhoria futura; por ora, 0600 com aviso no README.)
+function saveStore(s) {
+    fs.mkdirSync(STORE_DIR, { recursive: true, mode: 0o700 });
+    const tmp = `${STORE_FILE}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(s), { mode: 0o600 });
+    fs.renameSync(tmp, STORE_FILE);
+}
+// Precedência: token salvo (rotacionado) > env (só bootstrap). Reusar o token do
+// env depois de já ter rotacionado dispararia a detecção de reuso no servidor.
+let refreshToken = loadStore().refreshToken || process.env.KASSINAO_REFRESH_TOKEN || '';
+let accessToken = '';
+let accessExpMs = 0;
+async function refreshTokens() {
+    if (!URL_BASE)
+        throw new Error('Defina KASSINAO_URL (ex.: https://kassinao.suaempresa.com).');
+    if (!refreshToken) {
+        const base = URL_BASE || '<sua URL do Kassinão>';
+        throw new Error(`Sem token. Gere um em ${base}/conectar-ia ou rode: kassinao-mcp exchange <codigo>.`);
+    }
+    const r = await fetch(`${URL_BASE}/api/mcp/refresh`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ refresh_token: refreshToken }),
+    });
+    if (!r.ok) {
+        const base = URL_BASE || '<sua URL do Kassinão>';
+        throw new Error(`Não consegui renovar o token (HTTP ${r.status}). Gere um novo em ${base}/conectar-ia.`);
+    }
+    const data = (await r.json());
+    refreshToken = data.refresh_token; // rotação: guarda o novo imediatamente
+    accessToken = data.access_token;
+    accessExpMs = Date.parse(data.access_expires_at) || Date.now() + 10 * 60 * 1000;
+    saveStore({ url: URL_BASE, refreshToken });
+}
+async function getAccess() {
+    if (accessToken && Date.now() < accessExpMs - 30_000)
+        return accessToken;
+    await refreshTokens();
+    return accessToken;
+}
+async function apiGet(pathname, params) {
+    const url = new URL(`${URL_BASE}${pathname}`);
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null && v !== '')
+            url.searchParams.set(k, String(v));
+    }
+    let token = await getAccess();
+    let r = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+    if (r.status === 401) {
+        await refreshTokens(); // access venceu/rotacionou — renova uma vez e tenta de novo
+        token = accessToken;
+        r = await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+    }
+    if (r.status === 503) {
+        throw new Error('O Kassinão está iniciando ou o Discord está indisponível. Tente de novo em instantes.');
+    }
+    if (!r.ok)
+        throw new Error(`Erro ${r.status} em ${pathname}: ${(await r.text()).slice(0, 200)}`);
+    return r.json();
+}
+// ---------- definição das ferramentas ----------
+const rangeProps = {
+    preset: {
+        type: 'string',
+        description: 'today | yesterday | this_week | last_week | this_month | last_month | last_7_days | last_30_days',
+    },
+    from: { type: 'string', description: 'início: "YYYY-MM-DD" (data civil no fuso) ou ISO-8601' },
+    to: { type: 'string', description: 'fim (inclusivo): "YYYY-MM-DD" ou ISO-8601' },
+    last: { type: 'string', description: 'janela rolante: "7d", "48h", "2w"' },
+};
+const TOOLS = [
+    {
+        name: 'list_meetings',
+        description: 'List recorded meetings in a time window (defaults to the last 30 days). Only meetings the user can access are returned. Use for "what meetings happened between X and Y" / "list this week\'s calls".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ...rangeProps,
+                guildId: { type: 'string' },
+                channelId: { type: 'string' },
+                participantId: { type: 'string' },
+                status: { type: 'string', enum: ['done', 'recording'] },
+                limit: { type: 'number' },
+                cursor: { type: 'string' },
+            },
+        },
+        call: (a) => apiGet('/api/meetings', a),
+    },
+    {
+        name: 'pending_actions',
+        description: 'Aggregate action items (task + owner + deadline) across meetings, bucketed by deadline: overdue, dueSoon, later, noDeadline, unparseable. Use for "what is pending this week" / "my open action items". assignee="me" matches the token owner.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                withinDays: { type: 'number', description: 'janela de "dueSoon" em dias (padrão 7)' },
+                assignee: { type: 'string', description: '"me" ou parte do nome do responsável' },
+                meetingsWithin: { type: 'string', description: 'quão longe varrer reuniões (ex.: "60d")' },
+                guildId: { type: 'string' },
+            },
+        },
+        call: (a) => apiGet('/api/actions', a),
+    },
+    {
+        name: 'search_meetings',
+        description: 'Full-text search across transcripts, minutes and notes of accessible meetings, with deep links to the exact moment. Use for "find where we discussed X".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string' },
+                mode: { type: 'string', enum: ['all', 'any', 'phrase'], description: 'padrão: all' },
+                scope: { type: 'string', description: 'CSV de transcript,minutes,notes (padrão: todos)' },
+                ...rangeProps,
+                guildId: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['query'],
+        },
+        call: (a) => apiGet('/api/search', a),
+    },
+    {
+        name: 'who_said',
+        description: 'Find transcript segments matching a query, with speaker, timestamp, surrounding context and a deep link. Use for "when did Ana talk about budget".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string' },
+                speaker: { type: 'string' },
+                meetingId: { type: 'string', description: 'restringe a uma reunião' },
+                contextSegments: { type: 'number', description: 'segmentos de contexto antes/depois (padrão 1)' },
+                ...rangeProps,
+                guildId: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['query'],
+        },
+        call: (a) => apiGet('/api/said', a),
+    },
+    {
+        name: 'get_meeting',
+        description: 'Full dossier of one meeting: metadata, minutes (summary/decisions/actions/topics/per-participant), transcript, notes and a merged timeline. include is a CSV of meta,minutes,transcript,notes,timeline.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                meetingId: { type: 'string' },
+                include: { type: 'string', description: 'CSV: meta,minutes,transcript,notes,timeline' },
+                transcriptLimit: { type: 'number' },
+            },
+            required: ['meetingId'],
+        },
+        call: (a) => {
+            const id = encodeURIComponent(String(a.meetingId));
+            const { meetingId: _omit, ...rest } = a;
+            void _omit;
+            return apiGet(`/api/meetings/${id}`, rest);
+        },
+    },
+];
+// ---------- CLI: exchange ----------
+async function runExchange(code) {
+    if (!URL_BASE) {
+        console.error('Defina KASSINAO_URL antes (ex.: KASSINAO_URL=https://kassinao.suaempresa.com).');
+        process.exit(1);
+    }
+    const r = await fetch(`${URL_BASE}/api/mcp/exchange`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ code }),
+    });
+    if (!r.ok) {
+        console.error(`Falha ao trocar o código (HTTP ${r.status}). Ele expira em ~5 min e é de uso único — gere outro com /mcp new.`);
+        process.exit(1);
+    }
+    const data = (await r.json());
+    saveStore({ url: URL_BASE, refreshToken: data.refresh_token });
+    // O token de refresh já ficou salvo em disco (0600) — a config NÃO precisa dele.
+    const cfg = JSON.stringify({ mcpServers: { kassinao: { command: 'npx', args: ['-y', 'kassinao-mcp'], env: { KASSINAO_URL: URL_BASE } } } }, null, 2);
+    console.error('✅ Conectado! Token salvo em ~/.config/kassinao-mcp/token.json (0600).');
+    console.error('Cole este bloco no claude_desktop_config.json (ou no equivalente do Cursor) e reinicie o app:\n');
+    console.log(cfg); // stdout = a config, pronta pra copiar
+}
+// ---------- servidor MCP ----------
+async function runServer() {
+    const server = new Server({ name: 'kassinao', version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = TOOLS.find((t) => t.name === req.params.name);
+        if (!tool)
+            return { content: [{ type: 'text', text: `Ferramenta desconhecida: ${req.params.name}` }], isError: true };
+        try {
+            const result = await tool.call((req.params.arguments ?? {}));
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Erro: ${err.message}` }], isError: true };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('kassinao-mcp: conectado (stdio). Ferramentas disponíveis para o assistente.');
+}
+async function main() {
+    const [cmd, arg] = process.argv.slice(2);
+    if (cmd === 'exchange') {
+        if (!arg) {
+            console.error('Uso: kassinao-mcp exchange <codigo>');
+            process.exit(1);
+        }
+        await runExchange(arg);
+        return;
+    }
+    await runServer();
+}
+main().catch((err) => {
+    console.error('kassinao-mcp falhou:', err.message);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "kassinao-mcp",
+  "version": "1.0.0",
+  "description": "MCP connector for Kassinão — ask your Discord meeting recordings (transcripts, minutes, action items) from Claude Desktop, Cursor and other MCP clients.",
+  "type": "module",
+  "bin": {
+    "kassinao-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "discord",
+    "kassinao",
+    "meetings",
+    "transcription"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT"
+}