nb-mcp
MCP服务器包装 注意 CLI用于LLM友好的笔记记录。
动机
使用 nb 直接通过shell对LLM助理有两个问题：
- 退格符逃逸：带有反引号的Markdown内容会触发shell命令替换，破坏笔记。
- 笔记本上下文:
nb假设使用默认笔记本，使每个项目的使用变得尴尬。
此MCP服务器通过以下方式解决了这两个问题：
- 接受JSON参数形式的内容（无需shell转义）
- 使用显式记事本限定所有命令
快速开始
先决条件
安装 nb 按照官方指示： nb安装指南.
安装
自 克拉特斯.io:
cargo install nb-mcp-server或者从以下网址下载预构建的二进制文件 .
从源代码构建
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 --version显示已解析的笔记本路径和状态目录：
./target/release/nb-mcp --show-pathsMCP配置
添加到您的MCP客户端配置中（例如。， .mcp.json):
{
"mcpServers": {
"nb": {
"command": "/path/to/nb-mcp",
"args": ["--notebook", "myproject"]
}
}
}命令
所有命令均可通过以下方式访问 nb 工具与a command 参数到 减少MCP服务器的令牌占用空间。 这 args 字段必须是JSON对象。字符串化JSON有效载荷被拒绝。
备注
| 命令 | 描述 | 关键参数 |
|---|---|---|
nb.add | 创建注释 | title, content, tags[], folder |
nb.show | 阅读笔记 | id （别名： selector) |
nb.edit | 更新注释 | id （别名： selector), content, mode (replace 违约， append, prepend) |
nb.delete | 删除注释 | id （别名： selector) |
nb.move | 移动或重命名注释 | id （别名： selector), destination |
nb.list | 列出注释 | folder, tags[], limit ([ ] / [x] 指示todo状态；前导字形是项目标记） |
nb.search | 全文搜索 | queries[] （必填）， mode (any 违约， all), tags[] |
待办事项
| 命令 | 描述 | 关键参数 |
|---|---|---|
nb.todo | 创建待办事项 | description，可选 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, 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- | llm-claude, llm-gpt |
| 组件 | component- | component-api, component-ui |
| 任务类型 | task- | task-bug, task-feature |
| 状态 | status- | status-review, status-blocked |
配置
笔记本分辨率
优先级顺序：
- 根据命令
notebook论点（最高） - 命令行界面
--notebook旗帜 NB_MCP_NOTEBOOK环境变量- Git从主工作树路径派生的默认值
如果无法解析笔记本，则命令将失败并出现配置错误。这 服务器不会回退到 nb的默认笔记本。
如果解析的笔记本不存在，服务器会自动创建它。 使用 --no-create-notebook 禁用自动创建。
日志记录
日志被写入 ~/.local/state/nb-mcp/{project}--{worktree}.log （XDG兼容）。
对于Git工作树，日志以主项目和 工作树基名称，以避免多个MCP服务器实例之间的冲突。
使用 --show-paths 打印已解析的笔记本路径和状态目录。
控制日志级别 RUST_LOG:
RUST_LOG=debug nb-mcp --notebook myproject提交签名
使用 --no-commit-signing 在笔记本中禁用提交和标记签名 存储库。服务器更新笔记本存储库的本地Git配置，以便 签名提示不会阻止MCP工具调用。
贡献
请参阅捐款指南和行为准则：
