Servidor MCP (agentes de IA)

O LightNote inclui um servidor MCP (Model Context Protocol) headless que transforma o seu espaço numa ferramenta para agentes de IA (Claude Desktop, Claude Code, Cursor, e qualquer cliente que fale MCP). Com ele, o agente lê e escreve arquivos, faz buscas, consulta dados tabulares e bancos, manipula as tarefas, usa o Git e dispara requisições HTTP — tudo confinado à pasta (directory jail: caminhos com .. ou fora da raiz são recusados). O transporte é JSON-RPC 2.0 por stdin/stdout; cada sessão sobe um processo lnote.exe leve, separado da janela do editor.

Atalho de um clique: em IA → Ativar IA nesta pasta o LightNote habilita o MCP e escreve o .mcp.json de uma vez (o clique já é o consentimento). Se a IA já estiver ativa na pasta, o item vira Configurar IA desta pasta… e abre a Configuração do Espaço.

Segurança em duas camadas: (1) o servidor só inicia se você tiver dado opt-in naquela pasta; (2) toda ferramenta fica presa à raiz do espaço. Além disso, cada ferramenta é anunciada com anotações (somente-leitura, destrutiva, idempotente, "toca o mundo externo") para o cliente de IA avaliar o risco antes de chamar.

Passo a passo para configurar

1. Habilite o MCP na pasta. Em Ferramentas → Espaço → Configuração do Espaço..., marque Habilitar MCP para este espaço. Sem esse opt-in o servidor recusa iniciar (é a trava principal). Como alternativa, pela linha de comando: lnote --mcp-enable "C:\Caminho\do\espaco" (e --mcp-disable para desligar).
2. Descubra o caminho do lnote.exe. Ele fica na mesma pasta do lightnote.exe (a pasta de instalação do aplicativo). É o executável de console "slim", sem interface — é ele que o agente executa.
3. Registre o servidor no seu cliente de IA, apontando o comando para o lnote.exe e passando --mcp seguido da pasta do espaço. No formato usado por Claude Desktop / Cursor e semelhantes:

{
  "mcpServers": {
    "lightnote": {
      "command": "C:\\Caminho\\para\\lnote.exe",
      "args": ["--mcp", "C:\\Caminho\\do\\espaco"]
    }
  }
}

Dicas de configuração:

• Barras invertidas em JSON precisam ser duplicadas (C:\\Users\\...\\lnote.exe), como no exemplo.
• Para expor vários espaços, crie uma entrada por pasta, com nomes distintos ("lightnote-projetoA", "lightnote-projetoB"), cada uma apontando para a sua raiz.
• Depois de salvar a configuração, reinicie o cliente de IA para ele subir o servidor. Ao conectar, o agente deve listar as ferramentas lightnote_*; peça a ele um "liste os arquivos do espaço" para confirmar que está funcionando.
• Para o Claude Code (CLI), o mesmo servidor pode ser registrado com claude mcp add lightnote -- "C:\Caminho\para\lnote.exe" --mcp "C:\Caminho\do\espaco".

Senha de banco (opcional). A ferramenta db_query abre uma conexão .lnc. Se a senha estiver cifrada com a Frase-Segura, passe a frase pela variável de ambiente LNOTE_PASSPHRASE no bloco do servidor (nunca em argumentos de linha de comando) — conexões com senha em modo "perguntar" não podem ser usadas de forma desatendida.

Com o LightNote aberto, o banco passa pela janela. Uma CLI de IA rodando no terminal do app (o Claude Code, por exemplo) consulta pela sessão que você já abriu: vale para qualquer banco, inclusive Oracle, com a senha já digitada e o túnel SSH no ar. Se a conexão estiver fechada, a senha é pedida na janela — recusar ali é recusar a IA —, e a barra de status avisa quando uma ferramenta de IA consulta. Para escrever uma consulta num banco grande, a IA acha as tabelas pelo nome com db_search_objects (em todos os schemas), lê a lista com o comentário e as linhas estimadas (db_list_objects) e descreve várias tabelas de uma vez, com as chaves estrangeiras que dão os JOINs (db_describe). Com o app fechado, vale o que está acima.

Consulta por IA é opt-in por conexão. Ligar o MCP na pasta não expõe as conexões: cada .lnc só responde ao db_query quando a opção «Permitir consultas por IA (MCP)» está marcada no diálogo da conexão. O acesso é somente-leitura (SELECT). A permissão fica na configuração da pasta, nesta máquina: não vai no arquivo .lnc nem pelo Git, e a IA não consegue ligá-la editando o arquivo. Mudar o servidor, o banco, o usuário ou o túnel da conexão a suspende até você marcar a opção de novo. Um banco em arquivo (SQLite, DuckDB) precisa estar dentro do espaço, e pelo DuckDB a IA só lê arquivos de dentro do espaço — com o LightNote aberto, nenhum.

Exportar do banco pelo agente. Além de consultar, o agente pode materializar um SELECT num arquivo com db_export (Parquet, CSV, JSON ou .xlsx) — útil para resultados grandes demais para caber na resposta. Valem os mesmos três cuidados, nesta ordem: a consulta precisa ser somente-leitura, a conexão precisa do opt-in «Permitir consultas por IA (MCP)» (verificado antes de decifrar a senha) e o destino precisa ficar dentro do espaço. Exportações grandes usam a pasta temporária do sistema como área de apoio, em torno do tamanho do resultado — deixe espaço livre em disco.

Ferramentas disponíveis

O agente enxerga as ferramentas pelo prefixo do cliente (ex.: lightnote_read_file). Por categoria:

• Arquivos: read_file (com intervalo de linhas opcional), write_file, edit_file (substitui um trecho exato, sem reescrever o arquivo inteiro), append_file, list_files, move_file, make_dir e delete_file (vai para a Lixeira, não apaga de vez).
• Busca e navegação: search_files (ripgrep, com filtro por subpasta/glob e limite), list_symbols (outline de funções/classes de um arquivo) e open_in_editor (abre/foca um arquivo na janela do LightNote, se estiver aberta).
• Dados e SQL: query (SQL DuckDB sobre Parquet/CSV/JSON, saída em tsv/json/markdown), describe_table (esquema + estatísticas, sem despejar linhas), export_query (materializa um SELECT num arquivo via COPY), sqlite_query (SQL num .sqlite/.db), db_list_connections (lista os .lnc do espaço) e db_query (SQL somente-leitura numa conexão .lnc). Também: xlsx_read (lê uma planilha .xlsx como TSV, sem DuckDB), data_diff (compara dois arquivos tabulares — linhas só em A/só em B, alteradas por chave, ou deriva do esquema), e o catálogo de banco db_list_objects (tabelas/views) e db_describe (colunas, chaves e o CREATE — nativo ou reconstruído) — estes dois com os mesmos requisitos do db_query (opt-in por conexão + LNOTE_PASSPHRASE). Para levar o resultado para um arquivo em vez da resposta, db_export (Parquet/CSV/JSON/.xlsx).
• Além disso: search_notes (recupera os trechos mais relevantes das notas para uma pergunta — o mesmo motor do Perguntar às notas), list_links (os links de saída de uma nota, resolvidos ou quebrados), audit_vault_links (links quebrados e notas órfãs em todo o vault), list_note_templates e o parâmetro template do create_note, list_due_tasks (tarefas que vencem hoje ou atrasadas em todos os projetos), xlsx_read (lê uma planilha .xlsx como TSV), data_diff (compara dois arquivos tabulares) e o catálogo do banco db_list_objects/db_describe (tabelas/views e as colunas, chaves e DDL de uma tabela — os mesmos requisitos do db_query).
• Compactados: zip_list (lista os membros de um .zip/.isx) e zip_read (lê um membro como texto) — sem extrair o arquivo para o disco.
• Tarefas: list_task_projects (lista os projetos de tarefa .lnt do espaço), list_tasks, list_task_statuses (colunas do quadro), create_task, update_task (título, esforço, coluna, prioridade, datas, %, etiquetas, checklist e arquivar), update_task_status (mover de coluna), delete_task, task_note (ler/gravar a nota .md da tarefa) e list_due_tasks (tarefas vencendo hoje ou atrasadas em todos os projetos do espaço). Um espaço pode ter vários projetos .lnt: escolha qual pelo parâmetro project (o name devolvido por list_task_projects; dispensável se só houver um). Os id/status_id são identificadores da sessão — não leia os arquivos internos do .lnt para obtê-los; use as ferramentas de tarefa.
• Notas (PKM): create_note (cria uma nota .md), append_daily_note (acrescenta uma captura à nota do dia), remember (guarda um fato durável sobre você na nota de memória), list_backlinks (notas que apontam para uma nota), list_note_tags e search_by_tag (as #hashtags do vault e as notas que as usam) e add_task (cria tarefa com vencimento/etiquetas, aceitando linguagem natural no título). Também: search_notes (recupera os trechos mais relevantes das notas para uma pergunta — o mesmo motor do Chat com IA), list_links (os links de saída de uma nota, resolvidos ou quebrados), audit_vault_links (links quebrados e notas órfãs de todo o vault), list_note_templates e o parâmetro template do create_note (cria a nota já a partir de um modelo). E note_export (exporta uma nota para docx, odt, epub, LaTeX, Typst, HTML, reStructuredText, AsciiDoc, Org, MediaWiki, Notebook ou o Markdown de outro dialeto — sem janela nenhuma, e também pelo lnote note-export). E note_import (o caminho inverso: um docx, odt, epub, rtf, HTML ou tex vira nota ao lado do original, com títulos, listas, tabelas, ênfase, links, fórmulas e imagens — também pelo lnote note-import). E folder_export (a pasta inteira vira site HTML, conjunto de documentos ou Markdown, com os links reescritos — também pelo lnote folder-export).
• Git: git_status, git_log, git_diff e git_restore.
• Web e avisos: http_request (dispara uma requisição HTTP e devolve status/cabeçalhos/corpo) e notify (mostra um aviso na bandeja da janela aberta — útil para o agente sinalizar que terminou).
• Proxy de IA: list_ai_models e ask_ai (abaixo).
• O próprio LightNote: help_lookup (lê esta Ajuda por seção ou por termo, no idioma pedido) e markdown_reference (a sintaxe exata do Markdown que o app desenha). Ao se conectar, o cliente recebe também uma descrição do servidor com as ferramentas por categoria, e a Ajuda e a referência do Markdown aparecem como recursos (lightnote://help/… e lightnote://markdown/…).

O servidor também expõe os arquivos do espaço como recursos MCP (resources/list e resources/read), para clientes que preferem "anexar" arquivos em vez de chamar read_file.

A sua Biblioteca de prompts (a pasta Prompts/ do espaço) é exposta como prompts MCP (prompts/list e prompts/get). No Claude Code, cada prompt vira um comando de barra — /mcp__lightnote__<nome> — pronto para usar dentro da CLI de IA.

Rede de segurança das escritas. Antes de sobrescrever (write_file/edit_file) ou remover (delete_file) um arquivo, o servidor grava a versão anterior no Histórico Local — a mesma rede de segurança do editor —, para você poder desfazer uma mudança feita por um agente mesmo fora de um repositório Git.

Cada ferramenta declara se é de leitura ou escrita: além das annotations MCP (readOnlyHint/destructiveHint), a descrição começa com um selo [read-only], [writes] ou [destructive] — útil para montar listas de permissão com segurança.

Proxy de IA (delegar a outro modelo)

Os provedores de API que você cadastrou com a coluna MCP marcada ficam disponíveis ao agente por duas ferramentas: list_ai_models (lista os modelos liberados, com id, nome e modelo) e ask_ai ({model, prompt}). Assim o agente principal pode delegar uma sub-tarefa a um modelo mais barato ou especializado. A chamada é intermediada pelo LightNote aberto (o lnote.exe do MCP repassa o pedido à janela do aplicativo pela ponte interna): a chave de API nunca sai da sua máquina e nunca chega ao agente. Se o LightNote não estiver aberto, a ferramenta retorna um erro pedindo para abri-lo.