Servidor MCP (agentes de IA)

LightNote incluye un servidor MCP (Model Context Protocol) sin interfaz que convierte tu espacio de trabajo en una herramienta para agentes de IA (Claude Desktop, Claude Code, Cursor, y cualquier cliente que hable MCP). El agente puede leer y escribir archivos, buscar, consultar datos tabulares y bases de datos, trabajar con las tareas, usar Git y lanzar solicitudes HTTP — todo confinado a la carpeta (directory jail: las rutas con .. o fuera de la raíz se rechazan). El transporte es JSON-RPC 2.0 sobre stdin/stdout; cada sesión levanta un proceso lnote.exe ligero, aparte de la ventana del editor.

Atajo de un clic: en IA → Activar la IA en esta carpeta, LightNote habilita el MCP y escribe el .mcp.json de una vez (el clic es el consentimiento). Si la IA ya está activa en la carpeta, el elemento pasa a Configurar la IA de esta carpeta… y abre los Ajustes del espacio de trabajo.

Seguridad en dos capas: (1) el servidor solo arranca si has dado el consentimiento para esa carpeta; (2) toda herramienta está atada a la raíz del espacio. Además, cada herramienta se anuncia con anotaciones (solo lectura, destructiva, idempotente, "toca el mundo externo") para que el cliente de IA evalúe el riesgo antes de llamarla.

Configuración paso a paso

1. Habilita el MCP en la carpeta. En Herramientas → Espacio de trabajo → Configuración del espacio de trabajo..., marca Habilitar MCP para este espacio de trabajo. Sin este consentimiento el servidor se niega a arrancar (es la traba principal). Como alternativa, desde la línea de comandos: lnote --mcp-enable "C:\Ruta\al\espacio-de-trabajo" (y --mcp-disable para desactivarlo).
2. Localiza la ruta de lnote.exe. Está en la misma carpeta que lightnote.exe (la carpeta de instalación de la aplicación). Es el ejecutable de consola "slim", sin interfaz — es lo que ejecuta el agente.
3. Registra el servidor en tu cliente de IA, apuntando el comando a lnote.exe y pasando --mcp seguido de la carpeta del espacio. En el formato que usan Claude Desktop / Cursor y similares:

{
  "mcpServers": {
    "lightnote": {
      "command": "C:\\Ruta\\a\\lnote.exe",
      "args": ["--mcp", "C:\\Ruta\\al\\espacio-de-trabajo"]
    }
  }
}

Consejos de configuración:

• Las barras invertidas en JSON deben duplicarse (C:\\Users\\...\\lnote.exe), como en el ejemplo.
• Para exponer varios espacios de trabajo, añade una entrada por carpeta, con nombres distintos ("lightnote-proyectoA", "lightnote-proyectoB"), cada una apuntando a su raíz.
• Tras guardar la configuración, reinicia el cliente de IA para que levante el servidor. Al conectar, el agente debería listar las herramientas lightnote_*; pídele "lista los archivos del espacio" para confirmar que funciona.
• Para Claude Code (CLI), el mismo servidor se registra con claude mcp add lightnote -- "C:\Ruta\a\lnote.exe" --mcp "C:\Ruta\al\espacio-de-trabajo".

Contraseña de base de datos (opcional). La herramienta db_query abre una conexión .lnc. Si la contraseña está cifrada con la Frase-Segura, pásala mediante la variable de entorno LNOTE_PASSPHRASE en el bloque del servidor (nunca en argumentos de línea de comandos) — las conexiones cuya contraseña está en modo "preguntar" no pueden usarse de forma desatendida.

Con LightNote abierto, la base de datos pasa por la ventana. Una CLI de IA que se ejecuta en el terminal de la aplicación (Claude Code, por ejemplo) consulta a través de la sesión que ya abriste: vale para cualquier base de datos, incluida Oracle, con la contraseña ya escrita y el túnel SSH activo. Si la conexión está cerrada, la contraseña se pide en la ventana —rechazarla allí es rechazar a la IA—, y la barra de estado avisa cuando una herramienta de IA consulta. Para escribir una consulta en una base grande, la IA encuentra las tablas por nombre con db_search_objects (en todos los esquemas), lee la lista con el comentario y las filas estimadas (db_list_objects) y describe varias tablas a la vez, con las claves foráneas que dan los JOIN (db_describe). Con la aplicación cerrada, vale lo anterior.

Las consultas de IA son opcionales por conexión. Activar el MCP en la carpeta no expone las conexiones: cada .lnc solo responde a db_query cuando la opción «Permitir consultas de IA (MCP)» está marcada en el diálogo de la conexión. El acceso es de solo lectura (SELECT). El permiso se guarda en la configuración de la carpeta, en esta máquina: no va en el archivo .lnc ni por Git, y la IA no puede activarlo editando el archivo. Cambiar el servidor, la base de datos, el usuario o el túnel de la conexión lo suspende hasta que vuelvas a marcar la opción. Una base de datos en archivo (SQLite, DuckDB) debe estar dentro del espacio de trabajo, y a través de DuckDB la IA solo lee archivos dentro del espacio de trabajo; con LightNote abierto, ninguno.

Exportar desde la base de datos con el agente. Ademas de consultar, el agente puede materializar un SELECT en un archivo con db_export (Parquet, CSV, JSON o .xlsx) — util para resultados demasiado grandes para caber en la respuesta. Rigen las mismas tres precauciones, en este orden: la consulta debe ser de solo lectura, la conexion necesita la opcion «Permitir consultas por IA (MCP)» (comprobada antes de descifrar la contraseña) y el destino debe quedar dentro del espacio de trabajo. Las exportaciones grandes usan la carpeta temporal del sistema como area de apoyo, aproximadamente del tamaño del resultado — deje espacio libre en disco.

Herramientas disponibles

El agente ve las herramientas bajo el prefijo del cliente (p. ej. lightnote_read_file). Por categoría:

• Archivos: read_file (con rango de líneas opcional), write_file, edit_file (reemplaza un fragmento exacto, sin reescribir el archivo entero), append_file, list_files, move_file, make_dir y delete_file (va a la Papelera de reciclaje, no borra del todo).
• Búsqueda y navegación: search_files (ripgrep, con filtro de subcarpeta/glob y límite), list_symbols (esquema de las funciones/clases de un archivo) y open_in_editor (abre/enfoca un archivo en la ventana de LightNote, si está abierta).
• Datos y SQL: query (SQL DuckDB sobre Parquet/CSV/JSON, salida tsv/json/markdown), describe_table (esquema + estadísticas, sin volcar filas), export_query (materializa un SELECT en un archivo vía COPY), sqlite_query (SQL en un .sqlite/.db), db_list_connections (lista los .lnc del espacio) y db_query (SQL de solo lectura en una conexión .lnc). Para llevar el resultado a un archivo en vez de la respuesta, db_export (Parquet/CSV/JSON/.xlsx).
• Además: search_notes (recupera los fragmentos más relevantes de las notas para una pregunta — el mismo motor de Preguntar a tus notas), list_links (los enlaces de salida de una nota, resueltos o rotos), audit_vault_links (enlaces rotos y notas huérfanas de todo el depósito), list_note_templates y el parámetro template de create_note, list_due_tasks (tareas que vencen hoy o atrasadas en todos los proyectos), xlsx_read (lee una hoja .xlsx como TSV), data_diff (compara dos archivos tabulares) y el catálogo de la base de datos db_list_objects/db_describe (tablas/vistas y las columnas, claves y DDL de una tabla — mismos requisitos que db_query). Y note_export (exporta una nota a docx, odt, epub, LaTeX, Typst, HTML, reStructuredText, AsciiDoc, Org, MediaWiki, Notebook u otro dialecto de Markdown — sin ninguna ventana, y también con lnote note-export). Y note_import (el camino inverso: un docx, odt, epub, rtf, HTML o tex se convierte en nota junto al original, con títulos, listas, tablas, énfasis, enlaces, fórmulas e imágenes — también con lnote note-import). Y folder_export (la carpeta entera se convierte en un sitio HTML, un conjunto de documentos o Markdown, con los enlaces reescritos — también con lnote folder-export).
• Comprimidos: zip_list (lista los miembros de un .zip/.isx) y zip_read (lee un miembro como texto) — sin extraer el archivo al disco.
• Tareas: list_task_projects (lista los proyectos de tarea .lnt del espacio), list_tasks, list_task_statuses (columnas del tablero), create_task, update_task (título, esfuerzo, columna, prioridad, fechas, %, etiquetas, checklist y archivar), update_task_status (mover de columna), delete_task y task_note (leer/escribir la nota .md de la tarea). Un espacio puede tener varios proyectos .lnt: elige cuál con el parámetro project (el name que devuelve list_task_projects; opcional si solo hay uno). Los id/status_id son identificadores de la sesión — no leas los archivos internos del .lnt para obtenerlos; usa las herramientas de tarea.
• Notas (PKM): create_note (crea una nota .md), append_daily_note (agrega una captura a la nota del día), remember (guarda un dato duradero sobre ti en la nota de memoria), list_backlinks (notas que apuntan a una nota), list_note_tags y search_by_tag (las #etiquetas del vault y las notas que las usan) y add_task (crea una tarea con vencimiento/etiquetas, aceptando lenguaje natural en el título).
• Git: git_status, git_log, git_diff y git_restore.
• Web y avisos: http_request (lanza una solicitud HTTP y devuelve estado/cabeceras/cuerpo) y notify (muestra un aviso en la bandeja de la ventana abierta — útil para que el agente señale que terminó).
• Proxy de IA: list_ai_models y ask_ai (abajo).
• El propio LightNote: help_lookup (lee esta Ayuda por sección o por término, en el idioma pedido) y markdown_reference (la sintaxis exacta del Markdown que dibuja la aplicación). Al conectarse, el cliente recibe también una descripción del servidor con las herramientas por categoría, y la Ayuda y la referencia del Markdown aparecen como recursos (lightnote://help/… y lightnote://markdown/…).

El servidor también expone los archivos del espacio como recursos MCP (resources/list y resources/read), para clientes que prefieren "adjuntar" archivos en vez de llamar a read_file.

Tu Biblioteca de prompts (la carpeta Prompts/ del espacio) se expone como prompts MCP (prompts/list y prompts/get). En Claude Code cada prompt se convierte en un comando de barra — /mcp__lightnote__<nombre> — listo para usar dentro de la CLI de IA.

Red de seguridad de las escrituras. Antes de sobrescribir (write_file/edit_file) o eliminar (delete_file) un archivo, el servidor guarda la versión anterior en el Historial local — la misma red de seguridad del editor —, para que puedas deshacer un cambio hecho por un agente incluso fuera de un repositorio Git.

Cada herramienta declara si es de lectura o escritura: además de las annotations MCP (readOnlyHint/destructiveHint), la descripción empieza con un distintivo [read-only], [writes] o [destructive] — útil para armar listas de permisos con seguridad.

Proxy de IA (delegar a otro modelo)

Los proveedores de API que registraste con la columna MCP marcada quedan disponibles para el agente mediante dos herramientas: list_ai_models (lista los modelos permitidos, con id, nombre y modelo) y ask_ai ({model, prompt}). Así el agente principal puede delegar una subtarea a un modelo más barato o especializado. La llamada la intermedia el LightNote abierto (el lnote.exe del MCP reenvía la petición a la ventana de la aplicación por el puente interno): la clave de API nunca sale de tu máquina y nunca llega al agente. Si LightNote no está abierto, la herramienta devuelve un error pidiendo que lo abras.