MCP 服务器（AI 代理）

LightNote 包含一个无界面的 MCP（Model Context Protocol）服务器，可把你的 工作区变成一个供 AI 代理使用的工具（Claude Desktop、Claude Code、Cursor， 以及任何支持 MCP 的客户端）。代理可以读写文件、搜索、查询表格数据和数据库、 操作任务、使用 Git，并发起 HTTP 请求 — 全部限定在该文件夹内 （目录监狱：含 .. 或超出根目录的路径会被拒绝）。传输是基于 stdin/stdout 的 JSON-RPC 2.0；每个会话会启动一个轻量的 lnote.exe 进程，独立于编辑器窗口。

一键快捷方式： 通过 AI → 在此文件夹中启用 AI，LightNote 会一次性启用 MCP 并写入 .mcp.json（点击即表示同意）。如果该文件夹已启用 AI，该项会变为 配置此文件夹的 AI… 并打开 工作区设置。

两层安全:（1）只有当你为该文件夹启用了选择加入时，服务器才会 启动；（2）每个工具都锁定在工作区的根目录内。此外，每个工具都带有注解 （只读、破坏性、幂等、“触及外部世界”），使 AI 客户端在调用前能评估风险。

逐步配置

1. 为文件夹启用 MCP。在工具 → 工作区 → 工作区配置...中勾选为此工作区启用 MCP。没有这一选择加入，服务器会拒绝启动（这是主要的关卡）。也可从命令行： lnote --mcp-enable "C:\Path\to\workspace" （关闭用 --mcp-disable）。
2. 找到 lnote.exe 的路径。它与 lightnote.exe 在同一文件夹（应用的安装文件夹）内。它是无界面的“精简”控制台可执行文件 — 代理运行的就是它。
3. 在你的 AI 客户端中注册该服务器，把命令指向 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"），各自 指向自己的根目录。
• 保存配置后，重启 AI 客户端以让它启动服务器。连接后，代理应列出 lightnote_* 工具；让它“列出工作区的文件”来确认是否可用。
• 对于 Claude Code（CLI），可用以下命令注册同一服务器： claude mcp add lightnote -- "C:\Path\to\lnote.exe" --mcp "C:\Path\to\workspace"。

数据库密码（可选）。db_query 工具会打开一个 .lnc 连接。如果密码用安全口令加密，请在服务器块中通过环境变量 LNOTE_PASSPHRASE 传入短语（切勿放在命令行参数中）—— 密码为“询问” 模式的连接无法在无人值守下使用。

LightNote 打开时，数据库经由窗口访问。在应用终端中运行的 AI CLI（例如 Claude Code）会通过你已经打开的会话查询：适用于任何数据库，包括 Oracle，沿用已输入的密码和已建立的 SSH 隧道。如果连接已关闭，会在窗口中询问密码——在那里拒绝即拒绝 AI——，并且 AI 工具查询时状态栏会提示。要为大型数据库编写查询，AI 会用 db_search_objects 按名称查找表（覆盖所有模式），用 db_list_objects 读取带注释和估计行数的列表，并用 db_describe 一次描述多个表，其中的外键给出 JOIN。应用关闭时，适用上述说明。

AI 查询按连接选择启用。在文件夹中启用 MCP 不会公开连接：只有在连接对话框中勾选“允许 AI 查询 (MCP)”时，相应的 .lnc 才会响应 db_query。访问为只读（SELECT）。该许可保存在本机的文件夹设置中：不写入 .lnc 文件，也不会经由 Git 同步，AI 无法通过编辑文件来开启它。更改连接的服务器、数据库、用户或隧道后，许可会暂停，直到你再次勾选该选项。文件型数据库（SQLite、DuckDB）必须位于工作区内，并且 AI 通过 DuckDB 只能读取工作区内的文件；LightNote 打开时则完全不能读取文件。

通过代理从数据库导出。 除了查询，代理还可以用 db_export 将 SELECT 实体化为文件（Parquet、CSV、JSON 或 .xlsx）—适用于大到无法放入回复的结果。同样的三道防线按此顺序生效：查询必须是只读的，连接需要勾选 “允许 AI 查询 (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（在 Parquet/CSV/JSON 上的 DuckDB SQL，tsv/json/markdown 输出）、describe_table（架构 + 统计，不输出 行）、export_query（用 COPY 把 SELECT 实体化为文件）、 sqlite_query（在 .sqlite/.db 上的 SQL）、 db_list_connections（列出工作区的 .lnc）、 db_query（在 .lnc 连接上的只读 SQL）。 若要将结果写入文件而非回复，使用 db_export（Parquet/CSV/JSON/.xlsx）。
• 还有：search_notes（针对一个问题检索最相关的笔记片段 —— 与AI 聊天相同的引擎）、list_links（一条笔记的出站链接，已解析或已失效）、audit_vault_links（整个知识库的失效链接和孤立笔记）、list_note_templates 以及 create_note 的 template 参数、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 参数选择要操作哪个 （即 list_task_projects 返回的 name；只有一个时可省略）。 id/status_id 是会话内的标识符——不要直接读取 .lnt 的内部文件来获取它们，请使用任务工具。
• 笔记（PKM）：create_note（创建 .md 笔记）、 append_daily_note（向当天的日记追加一条捕获）、 remember (把关于你的一条持久事实存入记忆笔记), list_backlinks（指向某条笔记的笔记）、list_note_tags 与 search_by_tag（vault 中的 #标签 及使用它们的笔记）， 以及 add_task（创建带截止日期/标签的任务，标题可用自然语言）。
• Git：git_status、git_log、 git_diff、git_restore。
• Web 与通知：http_request（发起 HTTP 请求并返回 状态/头部/正文）、notify（在已打开窗口的托盘显示通知 —— 便于代理 提示已完成）。
• AI 代理：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__<名称>，可直接在 AI CLI 中使用。

写入安全网。在覆盖（write_file/edit_file）或删除（delete_file）文件之前，服务器会把旧版本保存到本地历史（与编辑器相同的安全网），这样即使不在 Git 仓库中，你也能撤销代理所做的更改。

每个工具都会声明它是读取还是写入：除了 MCP 注解 （readOnlyHint/destructiveHint）之外，描述开头还带有 [read-only]、[writes] 或 [destructive] 标记——便于安全地构建允许列表。

AI 代理（委托给另一个模型）

你用勾选 MCP 列注册的 API 提供商会通过两个工具向代理 开放：list_ai_models（列出允许的模型，含 id、名称和模型）和 ask_ai（{model, prompt}）。这样主代理就能把子任务 委托给更便宜或更专业的模型。调用由正在运行的 LightNote 中转（MCP 的 lnote.exe 通过内部桥把请求转发到应用窗口）：API 密钥绝不离开你的 本机，也绝不到达代理。如果 LightNote 未打开，该工具会返回一个提示你打开它的 错误。