Server MCP (agenti IA)

LightNote include un server MCP (Model Context Protocol) headless che trasforma il tuo spazio di lavoro in uno strumento per agenti IA (Claude Desktop, Claude Code, Cursor e qualsiasi client che parli MCP). L'agente può leggere e scrivere file, cercare, interrogare dati tabellari e database, lavorare con le attività, usare Git e lanciare richieste HTTP — tutto confinato alla cartella (directory jail: i percorsi con .. o fuori dalla radice vengono rifiutati). Il trasporto è JSON-RPC 2.0 su stdin/stdout; ogni sessione avvia un processo leggero lnote.exe, separato dalla finestra dell'editor.

Scorciatoia con un clic: da IA → Attiva l'IA in questa cartella, LightNote abilita l'MCP e scrive il .mcp.json in una volta (il clic è il consenso). Se l'IA è già attiva nella cartella, la voce diventa Configura l'IA di questa cartella… e apre le Configurazione dello spazio di lavoro.

Due livelli di sicurezza: (1) il server si avvia solo se hai fatto opt-in per quella cartella; (2) ogni strumento è vincolato alla radice dello spazio di lavoro. In più, ogni strumento è annunciato con annotazioni (sola lettura, distruttivo, idempotente, "tocca il mondo esterno") così il client IA può valutare il rischio prima di chiamarlo.

Configurazione passo dopo passo

1. Abilita l'MCP per la cartella. In Strumenti → Spazio di lavoro → Configurazione dello spazio di lavoro..., spunta Abilita MCP per questo spazio di lavoro. Senza questo opt-in il server si rifiuta di avviarsi (è la porta principale). In alternativa, dalla riga di comando: lnote --mcp-enable "C:\Percorso\allo\spazio-di-lavoro" (e --mcp-disable per disattivarlo).
2. Trova il percorso di lnote.exe. Si trova nella stessa cartella di lightnote.exe (la cartella di installazione dell'app). È l'eseguibile console "snello", senza interfaccia grafica — è quello che esegue l'agente.
3. Registra il server nel tuo client IA, puntando il comando a lnote.exe e passando --mcp seguito dalla cartella dello spazio di lavoro. Nel formato usato da Claude Desktop / Cursor e simili:

{
  "mcpServers": {
    "lightnote": {
      "command": "C:\\Percorso\\a\\lnote.exe",
      "args": ["--mcp", "C:\\Percorso\\allo\\spazio-di-lavoro"]
    }
  }
}

Suggerimenti per la configurazione:

• Le barre rovesciate nel JSON vanno raddoppiate (C:\\Users\\...\\lnote.exe), come nell'esempio.
• Per esporre più spazi di lavoro, aggiungi una voce per ogni cartella, con nomi distinti ("lightnote-progettoA", "lightnote-progettoB"), ciascuna che punta alla propria radice.
• Dopo aver salvato la configurazione, riavvia il client IA così avvia il server. Una volta connesso, l'agente dovrebbe elencare gli strumenti lightnote_*; chiedigli di "elencare i file dello spazio di lavoro" per confermare che funziona.
• Per Claude Code (CLI), lo stesso server può essere registrato con claude mcp add lightnote -- "C:\Percorso\a\lnote.exe" --mcp "C:\Percorso\allo\spazio-di-lavoro".

Password del database (opzionale). Lo strumento db_query apre una connessione .lnc. Se la password è cifrata con la Passphrase, passala tramite la variabile d'ambiente LNOTE_PASSPHRASE nel blocco del server (mai come argomento sulla riga di comando) — le connessioni con password in modalità "chiedi" non possono essere usate in modo automatizzato.

Con LightNote aperto, il database passa per la finestra. Una CLI di IA eseguita nel terminale dell'app (Claude Code, per esempio) interroga tramite la sessione che hai già aperto: vale per qualsiasi database, incluso Oracle, con la password già digitata e il tunnel SSH attivo. Se la connessione è chiusa, la password viene chiesta nella finestra — rifiutare lì significa rifiutare l'IA —, e la barra di stato avvisa quando uno strumento di IA esegue una query. Per scrivere una query su un database grande, l'IA trova le tabelle per nome con db_search_objects (in tutti gli schemi), legge l'elenco con il commento e le righe stimate (db_list_objects) e descrive più tabelle insieme, con le chiavi esterne che danno i JOIN (db_describe). Con l'app chiusa, vale quanto sopra.

Le query dell'IA sono opt-in per connessione. Abilitare l'MCP nella cartella non espone le connessioni: ogni .lnc risponde a db_query solo quando l'opzione «Consenti query dell'IA (MCP)» è selezionata nella finestra della connessione. L'accesso è di sola lettura (SELECT). Il permesso resta nelle impostazioni della cartella, su questo computer: non è salvato nel file .lnc né trasferito da Git, e l'IA non può attivarlo modificando il file. Cambiare il server, il database, l'utente o il tunnel della connessione lo sospende finché non selezioni di nuovo l'opzione. Un database su file (SQLite, DuckDB) deve trovarsi nello spazio di lavoro, e tramite DuckDB l'IA legge solo i file dentro lo spazio di lavoro; con LightNote aperto, nessuno.

Esportare dal database tramite l'agente. Oltre a interrogare, l'agente può materializzare una SELECT in un file con db_export (Parquet, CSV, JSON o .xlsx) — utile per risultati troppo grandi per stare in una risposta. Valgono le stesse tre cautele, in quest'ordine: la query deve essere di sola lettura, la connessione richiede l'opzione «Consenti query IA (MCP)» (verificata prima di decifrare la password) e la destinazione deve restare dentro lo spazio di lavoro. Le esportazioni grandi usano la cartella temporanea di sistema come area di appoggio, all'incirca quanto il risultato — lasciare spazio libero su disco.

Strumenti disponibili

L'agente vede gli strumenti sotto il prefisso del client (es. lightnote_read_file). Per categoria:

• File: read_file (con intervallo di righe opzionale), write_file, edit_file (sostituisce un frammento esatto, senza riscrivere l'intero file), append_file, list_files, move_file, make_dir e delete_file (va nel Cestino, non un'eliminazione definitiva).
• Ricerca e navigazione: search_files (ripgrep, con filtro per sottocartella/glob e limite), list_symbols (struttura delle funzioni/classi di un file) e open_in_editor (apre/mette a fuoco un file nella finestra di LightNote, se è aperta).
• Dati e SQL: query (SQL DuckDB su Parquet/CSV/JSON, output tsv/json/markdown), describe_table (schema + statistiche, senza scaricare le righe), export_query (materializza una SELECT in un file tramite COPY), sqlite_query (SQL su un .sqlite/.db), db_list_connections (elenca i file .lnc dello spazio di lavoro) e db_query (SQL di sola lettura su una connessione .lnc). Per portare il risultato in un file invece che nella risposta, db_export (Parquet/CSV/JSON/.xlsx).
• Inoltre: search_notes (recupera i frammenti di note più pertinenti per una domanda — lo stesso motore di Chat IA), list_links (i link in uscita di una nota, risolti o interrotti), audit_vault_links (link interrotti e note orfane di tutto il vault), list_note_templates e il parametro template di create_note, list_due_tasks (attività in scadenza oggi o in ritardo in tutti i progetti), xlsx_read (legge un foglio .xlsx come TSV), data_diff (confronta due file tabellari) e il catalogo del database db_list_objects/db_describe (tabelle/viste e le colonne, chiavi e DDL di una tabella — stessi requisiti di db_query). E note_export (esporta una nota in docx, odt, epub, LaTeX, Typst, HTML, reStructuredText, AsciiDoc, Org, MediaWiki, Notebook o in un altro dialetto Markdown — senza alcuna finestra, e anche da lnote note-export). E note_import (il percorso inverso: un docx, odt, epub, rtf, HTML o tex diventa una nota accanto all’originale, con titoli, elenchi, tabelle, enfasi, link, formule e immagini — anche da lnote note-import). E folder_export (una cartella intera diventa un sito HTML, un insieme di documenti o Markdown, con i link riscritti — anche da lnote folder-export).
• Archivi: zip_list (elenca i membri di un .zip/.isx) e zip_read (legge un membro come testo) — senza estrarre l'archivio su disco.
• Attività: list_task_projects (elenca i progetti di attività .lnt dello spazio di lavoro), list_tasks, list_task_statuses (colonne della bacheca), create_task, update_task (titolo, impegno, colonna, priorità, date, %, etichette, checklist e archiviazione), update_task_status (sposta tra colonne), delete_task e task_note (legge/scrive la nota .md dell'attività). Uno spazio di lavoro può contenere diversi progetti .lnt: scegline uno con il parametro project (il name restituito da list_task_projects; opzionale quando ce n'è solo uno). Gli id/status_id sono identificatori di sessione — non leggere i file .lnt interni per ottenerli; usa gli strumenti delle attività.
• Note (PKM): create_note (crea una nota .md), append_daily_note (aggiunge una cattura alla nota di oggi), remember (salva un fatto duraturo su di te nella nota di memoria), list_backlinks (note che puntano a una nota), list_note_tags e search_by_tag (gli #hashtag del vault e le note che li usano) e add_task (crea un'attività con data di scadenza/tag, accetta linguaggio naturale nel titolo).
• Git: git_status, git_log, git_diff e git_restore.
• Web e avvisi: http_request (lancia una richiesta HTTP e restituisce stato/intestazioni/corpo) e notify (mostra una notifica nel tray sulla finestra aperta — comodo perché l'agente segnali di aver finito).
• Proxy IA: list_ai_models e ask_ai (di seguito).
• LightNote stesso: help_lookup (legge questa Guida per sezione o per termine, nella lingua richiesta) e markdown_reference (la sintassi esatta del Markdown che l'app disegna). Alla connessione il client riceve anche una descrizione del server con gli strumenti per categoria, e la Guida e il riferimento del Markdown compaiono come risorse (lightnote://help/… e lightnote://markdown/…).

Il server espone anche i file dello spazio di lavoro come risorse MCP (resources/list e resources/read), per i client che preferiscono "allegare" i file invece di chiamare read_file.

La tua Libreria di prompt (la cartella Prompts/ dello spazio) è esposta come prompt MCP (prompts/list e prompts/get). In Claude Code ogni prompt diventa un comando slash — /mcp__lightnote__<nome> — pronto all'uso nella CLI di IA.

Rete di sicurezza delle scritture. Prima di sovrascrivere (write_file/edit_file) o rimuovere (delete_file) un file, il server salva la versione precedente nella Cronologia locale — la rete di sicurezza dell'editor —, così puoi annullare una modifica fatta da un agente anche fuori da un repository Git.

Ogni strumento dichiara se legge o scrive: oltre alle annotazioni MCP (readOnlyHint/destructiveHint), la descrizione inizia con un badge [read-only], [writes] o [destructive] — comodo per costruire allowlist in modo sicuro.

Proxy IA (delega a un altro modello)

I provider API che hai registrato con la colonna MCP spuntata sono esposti all'agente tramite due strumenti: list_ai_models (elenca i modelli consentiti, con id, nome e modello) e ask_ai ({model, prompt}). Questo permette all'agente principale di delegare un sotto-compito a un modello più economico o specializzato. La chiamata è intermediata dal LightNote in esecuzione (l'lnote.exe dell'MCP inoltra la richiesta alla finestra dell'app tramite il ponte interno): la chiave API non lascia mai la tua macchina e non raggiunge mai l'agente. Se LightNote non è aperto, lo strumento restituisce un errore chiedendo di aprirlo.