Сервер MCP (ИИ-агенты)

LightNote включает автономный сервер MCP (Model Context Protocol), превращающий рабочее пространство в инструмент для ИИ-агентов (Claude Desktop, Claude Code, Cursor и любой клиент, понимающий MCP). Агент может читать и писать файлы, искать, запрашивать табличные данные и базы данных, работать с задачами, использовать Git и отправлять HTTP-запросы — всё в пределах папки (изоляция каталога: пути с .. или вне корня отклоняются). Транспорт — JSON-RPC 2.0 через stdin/stdout; каждая сессия запускает отдельный лёгкий процесс lnote.exe, независимый от окна редактора.

Ярлык в один клик: через ИИ → Включить ИИ в этой папке LightNote включает MCP и записывает .mcp.json сразу (клик и есть согласие). Если ИИ в папке уже включён, пункт превращается в Настроить ИИ этой папки… и открывает Настройки рабочего пространства.

Два уровня защиты: (1) сервер запускается, только если вы явно включили эту опцию для данной папки; (2) каждый инструмент привязан к корню рабочего пространства. Кроме того, каждый инструмент объявляется с аннотациями (только чтение, деструктивный, идемпотентный, «затрагивает внешний мир»), чтобы ИИ-клиент мог оценить риск перед вызовом.

Пошаговая настройка

1. Включите MCP для папки. В Инструменты → Рабочее пространство → Настройка рабочего пространства... отметьте Включить MCP для этого рабочего пространства. Без этого явного включения сервер отказывается запускаться (это главный барьер). Либо через командную строку: lnote --mcp-enable "C:\Path\to\workspace" (и --mcp-disable, чтобы выключить).
2. Найдите путь к lnote.exe. Он находится в той же папке, что и lightnote.exe (папка установки приложения). Это «облегчённый» консольный исполняемый файл без интерфейса — именно его запускает агент.
3. Зарегистрируйте сервер в вашем ИИ-клиенте, указав в качестве команды lnote.exe и передав --mcp, а затем папку рабочего пространства. В формате, используемом Claude Desktop / Cursor и подобными:

{
  "mcpServers": {
    "lightnote": {
      "command": "C:\\Path\\to\\lnote.exe",
      "args": ["--mcp", "C:\\Path\\to\\workspace"]
    }
  }
}

Советы по настройке:

• Обратные слэши в JSON нужно удваивать (C:\\Users\\...\\lnote.exe), как в примере.
• Чтобы открыть несколько рабочих пространств, добавьте по одной записи на папку, с разными именами ("lightnote-projectA", "lightnote-projectB"), каждая указывает на свой корень.
• После сохранения конфигурации перезапустите ИИ-клиент, чтобы он запустил сервер. После подключения агент должен увидеть инструменты lightnote_*; попросите его «вывести список файлов рабочего пространства», чтобы подтвердить работу.
• Для Claude Code (CLI) тот же сервер можно зарегистрировать командой claude mcp add lightnote -- "C:\Path\to\lnote.exe" --mcp "C:\Path\to\workspace".

Пароль базы данных (необязательно). Инструмент db_query открывает подключение .lnc. Если пароль зашифрован секретной фразой, передайте её через переменную окружения LNOTE_PASSPHRASE в блоке сервера (никогда — в аргументах командной строки) — подключения с паролем в режиме «запрашивать» нельзя использовать без присмотра.

Когда LightNote открыт, база данных идёт через окно. CLI ИИ, запущенный в терминале приложения (например, Claude Code), выполняет запросы через уже открытую вами сессию: это работает с любой базой, включая Oracle, с уже введённым паролем и поднятым SSH-туннелем. Если подключение закрыто, пароль запрашивается в окне — отказ там означает отказ ИИ, — а строка состояния сообщает, когда инструмент ИИ выполняет запрос. Чтобы написать запрос к большой базе, ИИ находит таблицы по имени через db_search_objects (во всех схемах), читает список с комментарием и оценкой числа строк (db_list_objects) и описывает сразу несколько таблиц вместе с внешними ключами, которые дают JOIN (db_describe). Когда приложение закрыто, действует сказанное выше.

Запросы ИИ включаются для каждого подключения отдельно. Включение MCP в папке не открывает подключения: каждый .lnc отвечает на db_query только если в диалоге подключения отмечено «Разрешить запросы ИИ (MCP)». Доступ — только для чтения (SELECT). Разрешение хранится в настройках папки на этом компьютере: оно не записывается в файл .lnc и не передаётся через Git, и ИИ не может включить его, отредактировав файл. Если изменить сервер, базу, пользователя или туннель подключения, разрешение приостанавливается, пока вы снова не отметите этот параметр. База данных в файле (SQLite, DuckDB) должна находиться внутри рабочего пространства, а через DuckDB ИИ читает только файлы внутри рабочего пространства (пока LightNote открыт — вообще никаких).

Экспорт из базы данных через агента. Помимо запросов агент может материализовать SELECT в файл с помощью db_export (Parquet, CSV, JSON или .xlsx) — удобно для результатов, которые не помещаются в ответ. Действуют те же три защиты, именно в этом порядке: запрос должен быть только на чтение, для подключения нужен флажок «Разрешить запросы ИИ (MCP)» (проверяется до расшифровки пароля), а файл назначения должен оставаться внутри рабочего пространства. Большие экспорты используют системную временную папку как промежуточное хранилище, примерно в размер результата — оставляйте свободное место на диске.

Доступные инструменты

Агент видит инструменты с префиксом клиента (например, lightnote_read_file). По категориям:

• Файлы: read_file (с необязательным диапазоном строк), write_file, edit_file (заменяет точный фрагмент, без перезаписи всего файла), append_file, list_files, move_file, make_dir и delete_file (перемещает в корзину, а не удаляет безвозвратно).
• Поиск и навигация: search_files (ripgrep, с фильтром по подпапке/glob и ограничением), list_symbols (структура функций/классов файла) и open_in_editor (открывает/ фокусирует файл в окне LightNote, если оно открыто).
• Данные и SQL: query (SQL DuckDB по Parquet/CSV/JSON, вывод tsv/json/markdown), describe_table (схема + статистика, без вывода строк), export_query (сохраняет SELECT в файл через COPY), sqlite_query (SQL по .sqlite/.db), db_list_connections (список файлов .lnc рабочего пространства) и db_query (SQL только для чтения по подключению .lnc). Чтобы вывести результат в файл, а не в ответ, — db_export (Parquet/CSV/JSON/.xlsx).
• Также: search_notes (извлекает наиболее релевантные фрагменты заметок по вопросу — тот же движок, что и Чат с ИИ), list_links (исходящие ссылки заметки, разрешённые или битые), audit_vault_links (битые ссылки и заметки-сироты по всему хранилищу), list_note_templates и параметр template у create_note, list_due_tasks (задачи со сроком сегодня или просроченные во всех проектах), xlsx_read (читает лист .xlsx как TSV), data_diff (сравнивает два табличных файла) и каталог базы данных db_list_objects/db_describe (таблицы/представления и столбцы, ключи и DDL таблицы — те же требования, что и у db_query). И note_export (экспортирует заметку в docx, odt, epub, LaTeX, Typst, HTML, reStructuredText, AsciiDoc, Org, MediaWiki, Notebook или другой диалект Markdown — без всякого окна, и также через lnote note-export). И note_import (обратный путь: docx, odt, epub, rtf, HTML или tex становится заметкой рядом с оригиналом — с заголовками, списками, таблицами, выделением, ссылками, формулами и изображениями; также через lnote note-import). И folder_export (папка целиком становится сайтом HTML, набором документов или Markdown, со ссылками, переписанными под вышедшие файлы — также через lnote folder-export).
• Архивы: zip_list (список элементов .zip/.isx) и zip_read (читает элемент как текст) — без извлечения архива на диск.
• Задачи: list_task_projects (список проектов задач .lnt в рабочем пространстве), list_tasks, list_task_statuses (колонки доски), create_task, update_task (название, трудозатраты, колонка, приоритет, даты, %, теги, чек-лист и архивирование), update_task_status (перемещение между колонками), delete_task и task_note (чтение/ запись заметки задачи .md). Рабочее пространство может содержать несколько проектов .lnt: выбирайте нужный параметром project (имя name, возвращаемое list_task_projects; необязателен, если проект только один). id/status_id — это идентификаторы сессии — не читайте внутренние файлы .lnt, чтобы их получить, используйте инструменты задач.
• Заметки (PKM): create_note (создать заметку .md), append_daily_note (добавить запись в сегодняшнюю заметку), remember (сохраняет устойчивый факт о вас в заметке памяти), list_backlinks (заметки, ссылающиеся на заметку), list_note_tags и search_by_tag (хэштеги # хранилища и заметки, их использующие) и add_task (создать задачу со сроком/тегами, принимает естественный язык в заголовке).
• Git: git_status, git_log, git_diff и git_restore.
• Веб и уведомления: http_request (выполняет HTTP-запрос и возвращает статус/заголовки/тело) и notify (показывает уведомление в трее открытого окна — удобно, чтобы агент сообщил о завершении работы).
• Прокси ИИ: list_ai_models и ask_ai (ниже).
• Сам LightNote: help_lookup (читает эту справку по разделу или по слову, на нужном языке) и markdown_reference (точный синтаксис Markdown, который отображает приложение). При подключении клиент получает и описание сервера с инструментами по категориям, а справка и описание Markdown видны как ресурсы (lightnote://help/… и lightnote://markdown/…).

Сервер также предоставляет файлы рабочего пространства как MCP ресурсы (resources/list и resources/read) — для клиентов, предпочитающих «прикреплять» файлы вместо вызова read_file.

Ваша Библиотека промптов (папка Prompts/ рабочего пространства) публикуется как промпты MCP (prompts/list и prompts/get). В Claude Code каждый промпт становится слэш-командой — /mcp__lightnote__<имя> — готовой к использованию в CLI ИИ.

Страховка при записи. Перед перезаписью (write_file/edit_file) или удалением (delete_file) файла сервер сохраняет предыдущую версию в Локальную историю — ту же страховку, что и у редактора, — чтобы вы могли отменить изменение, сделанное агентом, даже вне репозитория Git.

Каждый инструмент объявляет, читает он или пишет: помимо MCP аннотаций (readOnlyHint/destructiveHint), описание начинается со значка [read-only], [writes] или [destructive] — удобно для безопасного построения списков разрешений.

Прокси ИИ (делегирование другой модели)

API-провайдеры, зарегистрированные с отмеченным столбцом MCP, доступны агенту через два инструмента: list_ai_models (список разрешённых моделей с id, именем и моделью) и ask_ai ({model, prompt}). Это позволяет основному агенту делегировать подзадачу более дешёвой или специализированной модели. Вызов проходит через запущенный LightNote (lnote.exe из MCP пересылает запрос окну приложения через внутренний мост): ключ API никогда не покидает вашу машину и никогда не доходит до агента. Если LightNote не открыт, инструмент возвращает ошибку с просьбой его открыть.