nb-mcp-server

nb-mcp

基于 nb CLI 封装的 MCP 服务，为大模型提供友好的笔记记录功能。

动机

对于 LLM 助手，通过 shell 直接使用 nb 有两个问题：

1. 反引号转义：Markdown 内容中的反引号会触发 shell 命令替换，导致笔记内容损坏。

2. 笔记本上下文：nb 假定使用默认笔记本，因此难以按项目使用。

此 MCP 服务通过以下方式解决这两个问题：

• 将内容作为 JSON 参数接收（无需 shell 转义）
• 为所有命令指定明确的笔记本

快速开始

先决条件

按照官方说明安装 nb： nb 安装指南。

安装

从 crates.io 安装：

cargo install nb-mcp-server

有关发行历史和升级说明，请参阅更新日志。

或者从 GitHub Releases 下载预构建二进制文件。

从源代码构建

cargo build --release

运行

使用环境变量中的默认笔记本：

NB_MCP_NOTEBOOK=myproject ./target/release/nb-mcp

或者通过 CLI 参数指定（优先级更高）：

./target/release/nb-mcp --notebook myproject

在笔记本仓库中禁用提交和标签签名：

./target/release/nb-mcp --notebook myproject --no-commit-signing

允许在笔记本根目录中新建笔记，而不要求指定文件夹：

./target/release/nb-mcp --notebook myproject --allow-top-level-notes

打印已安装的版本：

./target/release/nb-mcp --version

显示解析后的笔记本路径和状态目录：

./target/release/nb-mcp --show-paths

MCP 配置

添加到 MCP 客户端配置中（例如 .mcp.json）：

{
  "mcpServers": {
    "nb": {
      "command": "/path/to/nb-mcp",
      "args": ["--notebook", "myproject"]
    }
  }
}

命令

规范的访问方式是使用带有 command 参数的多路复用 nb 工具，以减少 MCP 服务占用的令牌。 args 字段必须是 JSON 对象。字符串化的 JSON 负载会被拒绝。 未知的 args 字段会被拒绝，而非忽略；请使用准确的命令 schema 字段或文档中说明的别名。 返回的标识符（例如 coordination/mcp/1 或 myproject:coordination/mcp/1）是 nb 选择器，而非当前仓库中的文件系统路径。笔记本存储由 nb 配置管理。 notebook 参数必须是纯笔记本名称。文件夹路径请使用 folder，笔记选择器请使用 id / selector。操作现有项目的命令接受复制的选择器（例如 myproject:coordination/mcp/1），但如果它与单独的 notebook 参数冲突，则会被拒绝。

一等工具

所有命令也都可作为带类型 schema 的直接一等工具使用：add、show、delete、move、list、search、todo、do、undo、tasks、bookmark、folders、mkdir、import、status、notebooks，以及支持正文操作的工具 replace_note_body、edit_note_substring、edit_note_lines、retitle_note、edit_note_tags，和行操作工具 show_note_lines、search_note_lines。这些工具会绕过多路复用命令分发。多路复用 nb 工具仍作为精简的兼容接口，供保留的命令使用。

笔记

命令	描述	关键参数
nb.add	创建笔记	默认必需：title、content、tags[]、folder
nb.show	读取笔记（结构化信封）	id（别名：selector）
nb.delete	删除笔记	id（别名：selector）
nb.move	移动或重命名笔记	id（别名：selector）、destination
nb.list	列出笔记	folder、tags[]、limit（[ ] / [x] 表示待办事项状态；前导符号为条目标记）
nb.search	全文搜索	queries[]（必需）、mode（默认为 any，可选 all）、tags[]

待办事项

命令	描述	关键参数
nb.todo	创建待办事项	默认必需：folder；title、可选的 description（别名：content）、可选的 tasks[]、tags[]
nb.do	标记为已完成	id（别名：selector）、可选的 task_number
nb.undo	重新打开	id（别名：selector）、可选的 task_number
nb.tasks	列出待办事项	可选的 status（open 或 closed）、可选的 recursive（默认为 true）

组织

命令	描述	关键参数
nb.bookmark	保存 URL	url、默认必填的 folder、title、tags[]、comment
nb.import	导入文件/URL	source、默认必填的 folder、filename、convert
nb.folders	列出文件夹	parent
nb.mkdir	创建文件夹	path
nb.notebooks	仅列出笔记本	（无）
nb.status	笔记本信息	（无）

示例

创建一条包含代码的笔记：

{
  "command": "nb.add",
  "args": {
    "title": "API Design Notes",
    "content": "# API Design\n\nUse `GET /items` for listing.\n\n```python\nresponse = client.get('/items')\n```",
    "tags": ["design", "api"],
    "folder": "docs"
  }
}

搜索笔记：

{
  "command": "nb.search",
  "args": {
    "queries": ["API", "design"],
    "mode": "any",
    "tags": ["design"]
  }
}

标签建议

对于多 LLM 项目，可以考虑使用一致的标签前缀（可选）。 类别和前缀示例：

类别	模式	示例
协作者	llm-<name>	llm-claude、llm-gpt
组件	component-<name>	component-api、component-ui
任务类型	task-<type>	task-bug、task-feature
状态	status-<state>	status-review、status-blocked

感知正文的编辑

旧版 nb.edit 工具（及其 overwrite/append/prepend 模式） 已在 nb-api 0.3 切换时移除。感知正文的替换工具 只能直接调用（没有多路复用的 nb.* 别名），旨在防止旧版接口 所允许的破坏性整篇笔记覆盖问题：

• replace_note_body — 用纯 UTF-8 new_body 替换整篇笔记正文。需要提供此前 show 返回的正文 fingerprint；如果指纹已过期，系统会拒绝操作并提示重新读取， 因此你无法覆盖刚刚未读取过的笔记。
• edit_note_substring — 将纯文本 pattern 的一个或多个匹配项替换为 replacement。expected_count 必须与实际匹配数一致；可选的指纹可防止编辑过期内容。
• edit_note_lines — 根据一个原始快照中的行锚点，对互不重叠的 edits 批量执行插入/删除/替换操作； content 为裸文本（不含终止字节；库会追加文档的行尾符，因此单行 替换不会与下一行合并）。
• retitle_note — 修改标题而不更改路径。
• edit_note_tags — 在一次原子操作中添加和/或移除标签。

这些工具通过扁平的 id 字符串（别名为 selector）定位笔记， 与 show/delete/move 完全相同；不会公开相对于笔记本的文件名， 而 show/show_note_lines/ search_note_lines 返回的限定选择器可直接作为 id 使用。从 nb-api 0.4 起，也会提供数字型 .index id：读取结果和变更结果包含 selector 和 numeric_id，且 <folder>/<id> / <id> 均可作为 id（id 在文件夹内有效、按位置分配且永不重用；路径保持规范形式）。 正文内容（pattern、replacement、title、 new_body、行编辑的 content）以及行级/搜索的 text/title 都是原生 UTF-8 字符串，传输内容中完全不使用 base64。可通过 show_note_lines 读取行级内容（带边界、锚定的窗口，并提供文档级 eol 声明——lf/crlf 以及 has_final_eol，而不是逐行提供终止符），也可通过 search_note_lines 搜索（锚定匹配，按设计不包含 EOL 字段），从而支持 无需读取整篇笔记即可完成搜索到编辑的流程。新笔记会根据标题生成符合 nb 规则的文件名（Hello World Title → hello_world_title.md）。

add 仅创建笔记：如果内容呈待办事项形式（复选框行，或围栏代码块之外的 Tasks 标题），则会拒绝创建并提示改用 todo 工具。

调用多路复用的 nb.edit 会被拒绝，并提供说明替代工具的恢复指引。感知正文的工具和行级工具只能直接调用： 通过多路复用的 nb 工具调用它们会被拒绝。

结构化结果

• show 返回一个以文本为主的精简结构化封装：selector、path、 kind、todo_state、title（规范化的 Option<String>）、tags、body （完整的 UTF-8 文本）、body_contiguous、fingerprint 和 numeric_id。 不会暴露 base64 字段。如果源内容不是有效的 UTF-8，show 会返回一个类型化的 NonUtf8 错误，其中包含 MIME 提示，以及关于如何使用 MCP 之外的外部原始内容检索设施（nb CLI）的说明；非文本目标则返回 UnsupportedShowTarget。两种情况都不会返回 base64 字节。
• 修改类工具（add、todo、bookmark、mkdir、delete、move、 do、undo 以及支持正文操作的工具）会返回结构化的 CommitOutcome：commit_created、revision_id、pre_revision，以及每项操作的 path/selector/numeric_id/noop/fingerprint。幂等的无操作 修改会报告 commit_created: false。

类型化错误

nb-api 0.4 引入了类型化故障，MCP 层会将其转换为可执行的诊断信息，同时覆盖多路复用的 nb.* 接口和一等工具接口。现有错误类型新增了 NonUtf8 和 IndexLockTimeout（.index 锁繁忙；请稍后重试，未进行任何修改）：

• 对非文本选择器（文件夹、归档、图像等）调用 show：错误会指出选择器和实际的非文本类型，说明 show 仅读取文本笔记，并提示调用方使用 folders/list。服务绝不会将 show 静默转交给其他命令。
• 调用 add 时，同时提供 title 和 content，且 content 的首个非空行是与标题重复的 H1：错误会指出标题和检测到的标题行，并提示调用方删除重复的 H1，或省略单独的 title。
• 过期编辑保护：FingerprintMismatch、AnchorMismatch 和 OccurrenceMismatch 会提示调用方重新读取笔记，并使用最新的指纹、锚点和计数重试。
• FragmentedBody：如果正文包含多个片段（例如，书签包含多个正文片段），则不允许执行行、子字符串或正文替换操作；元数据操作（retitle_note、edit_note_tags）仍可执行。
• DirtyBaseline：笔记本工作树或索引处于脏状态时，修改操作会被拒绝；诊断信息会提示调用方先提交或清理。
• IndeterminateCommit / RecoveryRequired：提交结果未知或需要恢复；诊断信息会指示调用方不要自动重试，并在采取操作前检查 HEAD/状态。
• GateTimeout：笔记本正忙；请稍后重试。
• PathCollision / PathIgnored / UnsupportedStructure / PlanValidation：提供针对具体路径或计划的指导。

配置

笔记本解析

优先级顺序：

1. 每条命令的 notebook 参数（最高）
2. CLI 的 --notebook 标志
3. NB_MCP_NOTEBOOK 环境变量
4. 根据主工作树路径从 Git 派生的默认值

如果无法解析出笔记本，命令会因配置错误而失败。服务不会回退到 nb 的默认笔记本。

如果解析出的笔记本不存在，服务会自动创建。使用 --no-create-notebook 可禁用自动创建。

日志记录

日志写入 ~/.local/state/nb-mcp/{project}--{worktree}.log（符合 XDG 规范）。

对于 Git 工作树，日志名称同时包含主项目和工作树的基本名称，以避免多个 MCP 服务实例之间发生冲突。

使用 --show-paths 可输出解析出的笔记本路径和状态目录。

文件夹要求

默认情况下，创建笔记的命令必须提供 folder 参数，以免 Agent 意外将笔记散落在项目笔记本的根目录中。此要求适用于 nb.add、nb.todo、nb.bookmark 和 nb.import。使用 nb.mkdir 创建新文件夹，使用 nb.folders 列出现有文件夹。

设置 NB_MCP_ALLOW_TOP_LEVEL_NOTES=true 或传入 --allow-top-level-notes，即可允许在根目录创建笔记。

Notebook 覆盖设置

当变更命令成功写入后，如果 notebook 参数指向的笔记本不是项目默认笔记本，命令会发出警告。跨笔记本写入仍然允许，以便团队间协作；此警告有助于避免意外混淆笔记本与文件夹。

notebook 参数只接受笔记本名称，不接受选择器语法。例如，使用 notebook: "other-team" 和 folder: "todos/mcp"，而不是 notebook: "other-team:todos/mcp"。

使用 RUST_LOG 控制日志级别：

RUST_LOG=debug nb-mcp --notebook myproject

提交签名

使用 --no-commit-signing 禁用笔记本仓库中的提交和标签签名。服务会更新笔记本仓库的本地 Git 配置，避免签名提示阻塞 MCP 工具调用。

相关项目

• nb-api — nb CLI 的类型化 Rust 接口。发布于 crates.io。此 MCP 服务的所有笔记功能原语都依赖 nb-api；支持正文的编辑界面、类型化错误、结构化结果和经过清理的空列表均来自 nb-api 0.4。

贡献

请参阅贡献指南和行为准则：

• 贡献指南
• 行为准则

许可证

Apache 2.0