Vaultnotes

io.github.CloudCorpRecords由 GitHub 账号 CloudCorpRecords 发布v0.1.0更新于 Nov 3, 2026

List, read, search, and edit markdown notes in a local vault directory.

已验证STDIO仅桌面文件与存储知识与记忆

概览

AI 生成的概览

本地 stdio MCP 服务器，让助手列出、读取、搜索、追加、替换和删除磁盘上笔记库中的 markdown 笔记。

可以做什么
  • 列出笔记库或其中某个目录下的全部文件（以库内相对路径表示）
  • 读取笔记的文本内容
  • 在库内 markdown 文件中做不区分大小写的搜索，返回文件路径、行号和匹配行
  • 向文件追加内容，文件或父目录不存在时自动创建
  • 把文件中第一处完全匹配的目标文本替换为新内容
  • 删除文件（目录会被拒绝）
适用场景
适合笔记本身就是本地文件夹里的纯 markdown 文件、且希望助手在不依赖笔记应用或插件 API 的情况下查找、追加或小幅修改内容的场景。适用于收件箱式记录、跨笔记库检索和定点文本替换。
运行要求
以本地进程通过 stdio 运行，可用 npx（需 Node.js）或 Docker 镜像启动。笔记库目录按 --vault 参数、VAULTNOTES_DIR 环境变量、当前工作目录的顺序解析；建议在客户端配置中设置 VAULTNOTES_DIR。未声明需要账号或 API 密钥。
安装前请注意
这些工具会写入文件：append_content 会创建文件和目录，patch_content 会改写文本，delete_file 会删除文件，说明中未提及确认步骤。路径均为库内相对路径，越出库外的路径会被拒绝，但仍建议指向专门的笔记目录。未配置笔记库时服务器仍会启动，缺失的库只会表现为工具报错。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Vaultnotes，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

vaultnotes

vaultnotes is a small set of tools for working with a vault of notes stored as plain files in a folder on your own disk: list what is in the vault, read a note, search across the markdown files, and append to, patch, or delete a note. It runs from the command line or as an MCP server for agents.

Local mode. vaultnotes works directly on a local directory. It does not need a running note-taking application or a plugin API: point it at the folder that holds your notes and every tool operates on the files there. Paths are always vault-relative, and anything that would resolve outside the vault — .. escapes, absolute paths elsewhere, symlinks pointing out — is refused before a file is touched.

Install

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

Or run the container image:

bash
docker run -i ghcr.io/cloudcorprecords/vaultnotes

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

Choosing the vault

The vault directory is resolved in this order:

  1. the --vault <dir> flag on the command line,
  2. the VAULTNOTES_DIR environment variable,
  3. the current working directory.

CLI

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

Exit codes: 0 on success, 1 when an operation fails (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

bash
npx -y @reneturcios/vaultnotes mcp

MCP client configuration (set the vault with the environment):

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

The server starts and lists its tools even when no vault has been configured yet; the vault is resolved per call and a missing vault produces a tool error rather than a crash.

Tools

ToolInputWhat it returns
list_files_in_vault(no arguments)Every file in the vault, as vault-relative paths.
list_files_in_dirdirpath (string, required)Every file under that vault directory, as vault-relative paths.
get_file_contentsfilepath (string, required)The file's contents as text.
searchquery (string, required)Case-insensitive substring matches across the vault's .md files: for each match, the filepath, the line number, and the matching line as a snippet.
append_contentfilepath (string, required), content (string, required)Appends the content to the file, creating the file (and parent folders) when it does not exist yet.
patch_contentfilepath (string, required), target (string, required), content (string, required)Replaces the first occurrence of the exact target text with the new content; an error when the target text is not in the file.
delete_filetarget_filepath (string, required)Deletes the file. Directories are refused.

A note on patch_content: targeting here is exact-text — the target is the literal passage to replace, not a heading name or a block reference. That keeps a patch unambiguous: it either finds the exact text once and replaces it, or it fails and changes nothing.

Development

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

License

MIT — see LICENSE.

来源：README.md，提交 570a7bc

工具

7

list_files_in_vault

List all files in the vault.

无需输入参数。

list_files_in_dir

List all files in a specific directory of the vault.

输入参数dirpath必填

get_file_contents

Get the contents of a file in the vault.

输入参数filepath必填

append_content

Append content to a file in the vault, creating the file if it does not exist.

输入参数content必填filepath必填

patch_content

Replace the first occurrence of a target text in a vault file with new content.

输入参数target必填content必填filepath必填

delete_file

Delete a file from the vault.

输入参数target_filepath必填

版本历史

1
  1. v0.1.0最新Oct 30, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分