Recordist Gateway

@recordist/gateway

Servidor MCP + agente A2A para Recordist, o anotador de reuniões que roda no seu próprio computador, sem bot na chamada e sem upload. Ele permite que Claude Desktop, Claude Code, Cursor e outros agentes leiam e ajam sobre as reuniões gravadas na sua máquina.

O próprio Recordist está abrindo em ondas: peça um lugar em https://recordist.app/early-access (Mac hoje; Windows e Linux em acesso antecipado).

• Leituras (listar, obter, transcrição, busca, itens de ação) funcionam com ou sem o aplicativo Recordist em execução: o gateway fala com a API local do aplicativo quando ele está ativo e, caso contrário, abre recordist.db somente leitura.
• Ações (iniciar/parar gravação, adicionar marcador, regenerar notas) precisam do aplicativo. Quando ele não está em execução, elas falham com Recordist app is not running.
• Tudo é restrito a loopback. Nada sai da sua máquina.

Instalação

npx -y @recordist/gateway --doctor     # check data dir, DB, token, app

Requer Node 20+. better-sqlite3 inclui binários pré-compilados para plataformas comuns.

Conecte um assistente

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "recordist": {
      "command": "npx",
      "args": ["-y", "@recordist/gateway"]
    }
  }
}

Claude Code

claude mcp add recordist -- npx -y @recordist/gateway

ou, para o transporte HTTP enquanto recordist-gateway --http estiver em execução:

claude mcp add --transport http recordist http://127.0.0.1:47322/mcp

Cursor

.cursor/mcp.json (projeto) ou ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "recordist": {
      "command": "npx",
      "args": ["-y", "@recordist/gateway"]
    }
  }
}

Qualquer cliente Streamable HTTP

recordist-gateway --http          # http://127.0.0.1:47322/mcp

O que o assistente recebe

Ferramentas

Ferramenta	Finalidade
list_meetings	Reuniões recentes; opcional q, from/to, limit/offset
get_meeting	Uma reunião com notas, itens de ação e marcadores
get_transcript	Transcrição como json | md | srt | vtt | txt
search_meetings	Busca de texto completo em transcrições e notas (FTS5)
get_action_items	Itens de ação, filtrar por meeting_id / open_only
regenerate_notes	Reexecutar notas de IA (summary, action_items, decisions, …) — precisa do aplicativo
start_recording	Iniciar gravação — precisa do aplicativo + configuração "permitir início remoto"
stop_recording	Parar a gravação atual — precisa do aplicativo
add_marker	Marcar o momento atual — precisa do aplicativo

Recursos: recordist://meeting/{id} (JSON) e recordist://meeting/{id}/transcript (Markdown). A lista de recursos mostra as 50 reuniões mais recentes.

Prompts: summarize_meeting, draft_followup_email, weekly_review.

Agente A2A

recordist-gateway --a2a           # http://127.0.0.1:47323/

Agent Card em http://127.0.0.1:47323/.well-known/agent.json; as habilidades espelham as ferramentas acima. JSON-RPC 2.0 em / com tasks/send, tasks/get, tasks/cancel e tasks/sendSubscribe (SSE).

Tarefas em linguagem natural são roteadas para uma habilidade com um pequeno roteador de palavras-chave; toda tarefa concluída retorna uma parte texto e uma parte dados com o resultado estruturado. Para pular o roteador, envie uma parte de dados {"skill": "...", "args": {...}}.

curl -s http://127.0.0.1:47323/ \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tasks/send",
    "params": {
      "id": "task-1",
      "message": { "role": "user", "parts": [
        { "type": "text", "text": "What are my open action items from this week?" }
      ]}
    }
  }' | jq .result.artifacts[0].parts

# explicit skill call
curl -s http://127.0.0.1:47323/ -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":2,"method":"tasks/send",
  "params":{"message":{"role":"user","parts":[
    {"type":"data","data":{"skill":"get_transcript","args":{"meeting_id":"01J…","format":"srt"}}}
  ]}}}'

# streaming
curl -N http://127.0.0.1:47323/ -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":3,"method":"tasks/sendSubscribe",
  "params":{"message":{"role":"user","parts":[{"type":"text","text":"list my meetings from today"}]}}}'

CLI

recordist-gateway                 MCP over stdio (default)
recordist-gateway --http          MCP over Streamable HTTP on 127.0.0.1:47322/mcp
recordist-gateway --a2a           A2A agent on 127.0.0.1:47323
recordist-gateway --all           stdio + --http + --a2a
recordist-gateway --doctor        diagnostics: data dir, DB, token, app reachability
recordist-gateway --version
  --http-port <n>  --a2a-port <n>  --host <addr>

Os logs vão para stderr; stdout é reservado para o transporte MCP stdio.

Variáveis de ambiente

Variável	Padrão	Finalidade
RECORDIST_DATA_DIR	macOS ~/Library/Application Support/app.recordist.desktop Windows %APPDATA%\app.recordist.desktop Linux ~/.local/share/app.recordist.desktop	Onde recordist.db e api_token ficam
RECORDIST_API_URL	http://127.0.0.1:47321	URL base da API local
RECORDIST_API_TOKEN	conteúdo de <data>/api_token	Token Bearer para a API local

Como funciona a seleção de backend

Em cada chamada, o gateway testa GET /v1/health (timeout de 800 ms, resultado em cache por 5 s). Se o aplicativo responder, a chamada vai para a API. Caso contrário, as leituras abrem <data>/recordist.db com readonly: true (o WAL do aplicativo nunca é gravado) e as ações retornam Recordist app is not running. FTS5 (segments_fts) é usado para busca quando presente, com um fallback de LIKE caso contrário.

Notas de segurança

• O gateway só vincula 127.0.0.1 (--host existe para contêineres; não o exponha em uma interface de rede). O transporte Streamable HTTP ativa proteção contra rebinding de DNS e só aceita Host: 127.0.0.1 / localhost.
• O token da API é lido de <data>/api_token, que o aplicativo grava com modo 0600. --doctor avisa se o arquivo estiver legível por grupo/mundo. Nunca faça commit ou compartilhe; qualquer pessoa com o token pode controlar a gravação na sua máquina.
• O banco de dados SQLite é aberto somente leitura; o gateway nunca o modifica.
• Sem telemetria, sem chamadas de rede de saída.

Desenvolvimento

npm install
npm run build      # tsc → dist/
npm test           # vitest
node dist/cli.js --doctor

Uso como biblioteca

import { createRecordistData, createMcpServer } from "@recordist/gateway";

const data = createRecordistData();          // API with SQLite fallback
const server = createMcpServer(data);        // McpServer — attach any transport

Sobre

O gateway é a pequena ponte aberta entre seu assistente de IA e a cópia do Recordist rodando no seu próprio computador. Ele não contém código do aplicativo nem chaves; só pode alcançar a API local na máquina em que roda. Problemas e perguntas: support@recordist.app. Relatórios de segurança: security@recordist.app (veja SECURITY.md). Feito por Recordist, um pequeno estúdio independente em Ontário, Canadá.