vaultnotes

vaultnotes

vaultnotes 是一组小型工具，用于处理存储在本地磁盘某个文件夹中的纯文本笔记库：列出笔记库中的内容、读取笔记、搜索 Markdown 文件，以及追加、修补或删除笔记。它可以通过命令行运行，也可以作为面向 Agent 的 MCP 服务运行。

本地模式。 vaultnotes 直接操作本地目录。它不需要正在运行的笔记应用或插件 API：只需指定存放笔记的文件夹，所有工具都会操作其中的文件。路径始终相对于笔记库；任何会解析到笔记库之外的路径——.. 路径穿越、指向其他位置的绝对路径、指向外部的符号链接——都会在触及文件前被拒绝。

安装

npx @reneturcios/vaultnotes list --vault ~/notes

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/vaultnotes

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

选择笔记库

笔记库目录按以下顺序确定：

1. 命令行中的 --vault <dir> 标志，
2. VAULTNOTES_DIR 环境变量，
3. 当前工作目录。

CLI

vaultnotes list --vault ~/notes                 # every file in the vault
vaultnotes list-dir projects --vault ~/notes    # files under one directory
vaultnotes read projects/alpha.md --vault ~/notes
vaultnotes search "launch checklist" --vault ~/notes
vaultnotes append inbox.md "Call Sam on Tuesday." --vault ~/notes
vaultnotes patch inbox.md "Tuesday" "Wednesday" --vault ~/notes
vaultnotes delete drafts/old.md --vault ~/notes

vaultnotes --version

退出码：成功时为 0，操作失败时为 1（错误信息会指出问题），用法错误时为 2。

MCP 服务

一个可执行文件同时支持两种模式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/vaultnotes mcp

MCP 客户端配置（通过环境变量设置笔记库）：

{
  "mcpServers": {
    "vaultnotes": {
      "command": "npx",
      "args": ["-y", "@reneturcios/vaultnotes", "mcp"],
      "env": { "VAULTNOTES_DIR": "/path/to/your/notes" }
    }
  }
}

即使尚未配置笔记库，服务也会启动并列出其工具；笔记库会在每次调用时解析，若缺少笔记库，则会返回工具错误，而不会崩溃。

工具

工具	输入	返回内容
list_files_in_vault	（无参数）	笔记库中的所有文件，以相对于笔记库的路径表示。
list_files_in_dir	dirpath（字符串，必填）	该笔记库目录下的所有文件，以相对于笔记库的路径表示。
get_file_contents	filepath（字符串，必填）	文件内容，以文本形式返回。
search	query（字符串，必填）	在笔记库的 .md 文件中查找不区分大小写的子串匹配项；每项匹配都会返回文件路径、行号和作为片段的匹配行。
append_content	filepath（字符串，必填）、content（字符串，必填）	将内容追加到文件中；若文件尚不存在，则创建该文件（及其父文件夹）。
patch_content	filepath（字符串，必填）、target（字符串，必填）、content（字符串，必填）	将目标文本首次出现的位置替换为新内容；若文件中没有目标文本，则返回错误。
delete_file	target_filepath（字符串，必填）	删除文件。拒绝删除目录。

关于 patch_content 的说明：此处按精确文本定位——目标是要替换的原文片段，而不是标题名称或块引用。这样可以确保修补操作明确无误：要么找到完全匹配的文本并替换，要么操作失败且不做任何更改。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, real fs in temp dirs, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。