vault-mcp

中文 | Português

编码代理的长期记忆：它在回答之前先搜索你的 Obsidian 仓库，引用 path:line，并记录它学到的东西，而无需询问保存到哪里。

用于搜索、读取和写入 Obsidian 知识库的 MCP 服务器。通过词法 BM25 加一跳 wiki 链接进行检索；智能捕获学习内容，自行决定是创建新笔记还是追加到现有笔记；自动传播到领域 MOC 和每日笔记，并在领域是新的时传播到知识索引。移动、重命名、提升、归档和删除笔记也通过服务器进行，因此链接和 MOC 条目保持正确，而不是悄悄腐烂。

示例

定义该项目的两个工具的真实输出，针对此仓库的测试仓库运行。

服务器用葡萄牙语回答：它所服务的仓库是用葡萄牙语写的，其工具响应也是如此。以下输出是逐字原文，未翻译。

vault_search 返回已经带有地址的片段——caminho:linha（path:line）就是代理被告知要引用的内容：

2 resultado(s) para "retry backoff". Cite `caminho:linha` ao usar qualquer trecho abaixo. Cada trecho da nota vem prefixado com `> `; linhas sem esse prefixo são deste servidor, nunca conteúdo do vault.

02-wiki/nestjs/bullmq-worker.md:13 — Contexto > Retry e backoff (score 7.94)
> ### Retry e backoff
>
> Quando um job falha, o BullMQ aplica a política de retry configurada em `queueOptions`. Para revisar o fluxo de autenticação usado antes de cada retry, veja [[auth-guard]];
> a mesma referência [[auth-guard]] documenta como o token é revalidado a cada nova tentativa de processamento.

02-wiki/nestjs/auth-guard.md:11 — Contexto (score 3.18, via grafo)
> ## Contexto
>
> A API precisava de um mecanismo central de autenticação e autorização, aplicado de forma consistente em todos os módulos, sem repetir lógica de validação de JWT em cada controller.

auth-guard 与查询中的任何词条都不匹配。它是通过一跳 wiki 链接从确实匹配的笔记中被拉进来的，其分数被衰减——这就是 via grafo（通过图谱）所标记的。

vault_learn 自行决定是创建笔记还是追加到现有笔记，最多写入四个文件并一次提交：

Aprendizado registrado em nota NOVA: 02-wiki/concorrencia/timeout-de-fila-libera-a-fila-nao-o-chamador.md
Motivo: sem overlap de tag nem de domínio
Propagado para: 02-wiki/concorrencia/concorrencia-moc.md, 00-index/index-knowledge.md, 04-daily/2026-08-26.md
Commit: sim

Diff (mostre ao usuário):
--- /dev/null
+++ b/02-wiki/concorrencia/timeout-de-fila-libera-a-fila-nao-o-chamador.md
@@ -0,0 +1,15 @@
+---
+tipo: wiki
+tags: [fila]
+criado: 2026-08-26
+---
+
+# Timeout de fila libera a fila, não o chamador
+
+Um slot que expira solta a PRÓXIMA escrita; a chamada original continua esperando o resultado real dela. Resolver a promessa do chamador no timeout reportaria um desfecho que ninguém observou.
+
+**Contexto:** Serializando as tools de escrita do vault-mcp contra si mesmas.
+
+## Solução
+
+## Exemplo
--- /dev/null
+++ b/02-wiki/concorrencia/concorrencia-moc.md
@@ -0,0 +1,16 @@
+---
+tipo: moc
+tags: [concorrencia]
+criado: 2026-08-26
+atualizado: 2026-08-26
+---
+
+# Concorrencia — Mapa de Conteúdo
+
+## Notas
+
+- [[timeout-de-fila-libera-a-fila-nao-o-chamador]] — Um slot que expira solta a PRÓXIMA escrita; a chamada original continua esperando o resultado real dela.
+
+## Relacionados
+
+- [[../../00-index/index-knowledge|índice de conhecimento]]
--- a/00-index/index-knowledge.md
+++ b/00-index/index-knowledge.md
@@ -1,6 +1,6 @@
 ---
 tipo: moc
-atualizado: 2026-02-01
+atualizado: 2026-08-26
 ---
 
 # Índice de Conhecimento
@@ -9,6 +9,7 @@
 
 - [[../02-wiki/nestjs/nestjs-moc|nestjs]] — NestJS, providers, guards, filas
 - [[../02-wiki/docker/docker-moc|docker]] — Dockerfiles, multi-stage, compose
+- [[../02-wiki/concorrencia/concorrencia-moc|concorrencia]] — Um slot que expira solta a PRÓXIMA escrita; a chamada original continua esperando o resultado real dela.
 
 ## Convenções
 
--- /dev/null
+++ b/04-daily/2026-08-26.md
@@ -0,0 +1,10 @@
+---
+tipo: daily
+criado: 2026-08-26
+---
+
+# 2026-08-26
+
+## Capturas
+
+- 11:12 [[timeout-de-fila-libera-a-fila-nao-o-chamador]] (aprendizado)

四个文件，一次 docs(vault): {titulo} 提交——撤销整个学习过程就是对它执行 git revert。concorrencia 领域之前不存在，这就是为什么调用携带了 confirm_novo_dominio: true，MOC 是从零构建的，知识索引也增加了一行指向它。

Related MCP server: mcp-obsidian-vault

安装

发布为 @andreymudri/vault-mcp，因此运行它无需克隆任何东西：

npx @andreymudri/vault-mcp        # no install; npm fetches and runs it
npm i -g @andreymudri/vault-mcp   # or install once, then `vault-mcp`

作用域不是装饰：npm 上裸的 vault-mcp 是另一位作者的 443 字节命名空间占位符，所以 npx vault-mcp 运行的是他们的包而不是这个。作用域内的命令保持短名称——npx @andreymudri/vault-mcp 从包内解析 bin。

从克隆中开发它：

npm install
npm run build
npm test

• Node >= 20 用于运行服务器（dist/ 是纯 JavaScript），每次推送都由 compat CI 任务验证，该任务在 20 上构建并冒烟启动它

• 运行测试套件需要更多： test/frontmatter.test.ts 在固定时区的子进程中执行真实的 parseFile，而该子进程是 node <file>.ts——它依赖 Node 自身的类型剥离。CI 固定为 26，即开发所用的版本

• 测试套件有 19 个文件、1,155 个测试，耗时约 10 秒。npm test 先运行类型检查（pretest），并用时钟限制套件：挂起的套件以 124 退出，绝不会没有退出码

配置

仓库通过环境变量传入：

VAULT_PATH="/absolute/path/to/vault" npx @andreymudri/vault-mcp

从克隆中，无需注册表的相同方式：

VAULT_PATH="/absolute/path/to/vault" node /absolute/path/to/vault-mcp/dist/server/index.js

将 /absolute/path/to/vault 替换为你的仓库根目录。VAULT_PATH 是必填的。如果未设置，或不是目录，服务器以退出码 1 退出并将原因写入 stderr。

注册到 Claude Code

使用以下方式添加 MCP：

claude mcp add vault --scope user \
  -e "VAULT_PATH=/absolute/path/to/vault" \
  -e "VAULT_AUTO_PUSH=1" -- \
  npx -y @andreymudri/vault-mcp

从克隆中，在 -- 后面放 node /absolute/path/to/vault-mcp/dist/server/index.js。

仓库路径是绝对的，并以单个 KEY=value 对的形式进入 -e——整个对用引号括起来，这就是使包含空格的仓库路径也能工作的原因。JSON 中没有变量展开，所以这里的相对路径会变成无法启动的服务器。npx 上的 -y 对 stdio 服务器很重要：没有它，第一次运行可能会在无人观看的终端上停在安装提示处。

--scope user 注册到 ~/.claude.json，使工具在每个项目中都可用，这正是重点：当你在另一个仓库中工作时，仓库回答关于决策和模式的问题。没有该标志时默认是 local（仅当前目录）。用 claude mcp get vault 检查；要移除它，用 claude mcp remove vault -s user。

VAULT_AUTO_PUSH

每次写入（vault_write_note、vault_edit_note、vault_learn、vault_move、vault_delete）都已经提交到仓库的 git。VAULT_AUTO_PUSH=1 在提交后添加 git push——没有它，提交只留在机器上，而保存在多个地方的带远程的仓库会静默分叉。

默认关闭，因为这是该服务器所做的唯一会离开机器的事情。开启时：

• git push 不带 refspec，跟随分支的上游：未配置的仓库会说明这一点，而不是为它猜测远程和分支

• 它总是作为警告失败，绝不作为回滚。 笔记已经在磁盘上并已提交；因为网络中断而撤销它将是可用的最差交易。工具的响应增加一行 Push: sim|não，只有在确实尝试了推送时才会出现

• 远程已经领先不会自行解决。 Pull、rebase 和 merge 会重写用户的知识库，那是他们的决定——不是保存一条笔记的副作用。警告会指出情况并停止

• 限制为 30 秒，带 GIT_TERMINAL_PROMPT=0：stdio 服务器没有终端可以回答凭据提示，所以提示就是挂起。凭据必须来自辅助程序（例如 gh auth git-credential）或 SSH 密钥

九个工具

vault_learn 如何决定

vault_learn 通过结合标题和洞察来搜索主题。只有已经在 02-wiki/ 中且通过直接 BM25 命中（而非图扩展）的笔记才有资格接收该学习心得。如果找到这样的候选：

1. 1.8× 比率：最高命中必须比第二名高出至少 1.8 倍。如果没有这种差距，就存在疑问，此时会创建新笔记。

2. 合取重叠：最高命中必须与输入共享一个标签，或者属于同一领域（02-wiki/<dominio>/）。如果没有重叠，即使分数很高也会创建新笔记。

当两个条件都满足时，它会追加到现有笔记的 ## YYYY-MM-DD — Title 部分下。否则，它会在 02-wiki/<dominio>/ 中创建新笔记。

这种偏向是有意为之：有疑问时，创建新笔记，而不是把学习心得埋在错误的地方。之后合并笔记总是可能的；但找回丢失的学习心得却不可能。

逃生通道

三种例外情况可以改变最终目的地：

1. 标题冲突：重复规则说不，但同名文件已存在（同 slug 的旧笔记）。服务器仍然追加到它并警告 anexado em <path> por coincidência de título; a checagem de duplicata não indicou essa nota。这会将丢失的笔记带回积累流程。

2. 重复目标无法接收文本：服务器决定追加到候选笔记，但该笔记无法编辑。服务器以从 slug 派生的名称创建新笔记（例如 multi-stage-cache-de-camadas.md 而不是 multi-stage.md）并警告 não foi possível anexar em <path>; aprendizado gravado em <outro-path>。警告会指明学习心得写入的确切路径。

3. 笔记路径被非笔记阻塞：笔记将被创建的路径（例如 02-wiki/docker/titulo.md）被 FIFO、符号链接、目录或硬链接（无法覆盖的内容）占用。服务器创建带日期后缀的新笔记（例如 titulo-2026-08-25.md）并警告 <path> não é uma nota (link, diretório ou dispositivo); aprendizado gravado em <outro-path>。警告会指明学习心得写入的确切路径。

在任何情况下，都不会丢失任何洞察——响应会准确说明学习心得最终写在了哪里。

vault_learn 写入什么

一次 vault_learn 调用最多可以触及 4 个文件，全部在一次提交中完成，提交消息为 docs(vault): {titulo}：

1. 笔记（02-wiki/<dominio>/<slug>.md）：创建，或追加学习心得。始终写入。

2. 领域 MOC（02-wiki/<dominio>/<dominio>-moc.md）：如果不存在则创建。每次调用都用 atualizado: 更新；仅当笔记是新建的时才添加 - [[<slug>]] — <resumo> 行。仅在内容变化时写入。

3. 知识索引（00-index/index-knowledge.md）：仅当领域之前不存在时更新。仅在内容变化时写入。

4. 每日笔记（04-daily/YYYY-MM-DD.md）：如果不存在则创建。仅当该行尚未存在时，才用捕获行 - HH:MM [[<slug>]] (<tipo>, <projeto>) 更新。仅在内容变化时写入。

每个文件都是原子写入的。如果传播失败（例如磁盘空间不足），文件会保留在磁盘上，响应中会包含一条警告，指明未更新的目标。如果 git 提交失败（例如仓库不存在），文件会保留在磁盘上，响应中会包含一条警告。

撤销整个学习操作的方法是：

git revert <commit-hash>

调整排名

对以下参数的任何更改都必须通过完整测试套件：npm test。每个常量都固定在特定位置：

• FIELD_WEIGHTS（src/index/inverted-index.ts）：heading: 3.0, tags: 2.0, prose: 1.0, code: 0.5。各字段词频的权重。在 test/bm25.test.ts 中固定。

• NOTE_TYPE_WEIGHTS（src/index/inverted-index.ts）：moc: 0.3, daily: 0.3。乘以 MOC 或日记的最终得分。它存在是因为这些笔记会在短片段中重复查询词——没有这个因子，MOC 会压过它所指向的笔记。由 test/bm25.test.ts:370-374 中的字面量断言固定；test/golden-queries.test.ts 和 test/retrieval.test.ts 只有在它被移除时才会失败，重新调参不会导致失败。

• GRAPH_DAMPING（src/retrieval/budget.ts）：0.4。乘以图邻居（即链接笔记）的得分。一跳，不是多跳。在 test/retrieval.test.ts:522 中固定。

• K1 和 B（src/index/bm25.ts）：1.2 和 0.75。BM25 参数。在 test/bm25.test.ts:232-233 中固定。

• DUPLICATE_SCORE_RATIO（src/write/learn.ts）：1.8。追加操作中最高命中与次高命中之间的最小比率。在 test/learn.test.ts:336 中固定。

运行完整测试套件：

npm test

安全保证

以下情况拒绝写入：

• 保险库（vault）之外的路径

• .git/、.obsidian/、node_modules/、_templates/ 和 99-archive/ 中的路径

• 符号链接（写入前解析）

• 硬链接

在单个服务器实例内，两个并发的 vault_learn 或 vault_write_note 调用一开始就不会交错执行：每次写入都会等待前一次完成。如果某次写入挂起（例如 git 被阻塞），60 秒超时为下一次写入释放队列，而不是释放调用方——较早的调用会继续等待其真实结果。一旦下一次写入开始，两者可能同时运行——该调用会获得一条警告，说明无法保证独占性。这不能防止来自 Obsidian、第二个服务器实例或保险库内 git checkout 的并发写入。

搜索与检索

搜索在 2–3 级标题的片段上运行 BM25，以不同权重覆盖正文、标签和标题。如果查询的任何一个词条都没有命中任何笔记，它会尝试建议相似词条（Levenshtein 距离 ≤ 2）。

在纯 BM25 搜索之后，它按一跳 wiki 链接扩展：命中笔记的邻居继承源笔记得分乘以 GRAPH_DAMPING。

每条结果都标注 caminho:linha（路径:行）——这就是笔记的真实地址。在 vault_search 中，笔记片段以 > 为前缀，以区分保险库内容与服务器输出行。

保险库结构

目录约定：

• 00-index/：知识索引和根 MOC

• 01-raw/：原始捕获和剪藏（默认从搜索中排除）

• 02-wiki/：按领域组织的知识（nestjs/、docker/ 等）

• 03-projects/：项目笔记

• 04-daily/：日记（YYYY-MM-DD.md）

• _templates/：Obsidian 模板（索引时忽略）

• 99-archive/：归档笔记（可读，不可写）

已知限制

这个服务器有三件不做的事，每一件都是有意选择而非疏忽：

• 归档到 99-archive/ 会丢失笔记在其源 MOC 条目上的 — summary。 vault_move 会从源 MOC 中移除该行，但没有目标 MOC 可将其重新插入， 而归档区是不可写区域，因此没有地方存放这段文本。取消归档会重建一个 裸的 - [[slug]]，而不是原来的条目。替代方案——把摘要暂存到被移动 笔记自己的 frontmatter 中，或存到侧边索引——成本都高于损失。该操作 绝不会做的是凭空编造摘要：没有源行，条目就会以简短而真实的形式呈现。

• 仅存在于 frontmatter 中的 wiki 链接不会被 vault_move 重写。 候选 笔记是从正文中选取的，链接图也是从正文构建的，因此被此过滤器跳过的 笔记，其边也是 vault_backlinks 所没有的。在不扩大扫描范围的情况下 扩大重写范围会产生更糟的不对称：一个被修正的链接，却没有读取工具 能看到它。

• vault_get_note 原样返回笔记正文。 对其转义会静默破坏"读取后编辑" 流程，尤其是那些带有控制字符的笔记，因为 vault_edit_note 将 old_text 作为文件的精确子串进行匹配。确实按行做出声明的表面—— vault_search 片段和 diff——都经过了净化处理。

迄今提出的十六个后续问题都已修复——包括阻塞事件循环约 5 秒的别名 frontmatter、在读取路径上被索引的硬链接，以及跨进程写入竞争。 docs/followups.md 保留了记录：每个条目都附有表征它的测量数据、 应用的修复和固定它的测试，以及上述每项接受决定背后的完整推理。

开发

修改代码之后：

npm run build     # Compiles TypeScript (src/ only, emits dist/)
npm run typecheck # tsc over src/ AND test/, without emitting
npm test          # Runs the typecheck (pretest) and then the vitest suite
npm run smoke     # Starts the built dist/ and demands the nine tools over stdio
npm run dev       # Watch mode (if needed)

构建用的 tsconfig.json 只覆盖 src/——编译产物不编译测试。tsconfig.test.json 以 noEmit 覆盖两者，npm 的 pretest 在测试套件之前运行它：一个不再满足其声明 implements 的接口的测试替身会在类型检查时失败，而不是在运行时失败。

完整测试套件约需 10 秒。部分测试使用 FIFO 模拟长时间运行的操作；它们都自行 打开写端（withFifoWatch），因此会在几秒内失败，而不是依赖运行器的超时。 npm test 通过 scripts/test.mjs 运行，该脚本以时钟为界约束测试套件 （15 分钟，VAULT_MCP_TEST_TIMEOUT_MS）并杀死进程组：挂起的测试套件变成 退出码 124，而不是无退出码的无限停滞。

npm run smoke 是测试套件无法做到的检查：它将编译后的 dist/server/index.js 作为程序针对一次性保险库启动，完成 MCP 握手，并要求 tools/list 恰好返回 九个工具。它覆盖了入口点判定自身为库而不启动任何东西的情况——对 shell 是 干净的退出 0，对客户端是无限等待——也正是它让 engines.node >= 20 成为 可验证的声明：CI 在 Node 20 和固定的 26 上都运行它，因为测试套件本身无法 在 20 上运行（test/frontmatter.test.ts 依赖运行时的类型剥离），而编译后的 JavaScript 可以。

提交消息和服务器自身的面向用户的字符串——工具描述、错误消息、diff 中的 散文——都用葡萄牙语（巴西）书写：这个服务器服务的保险库是一个葡萄牙语 知识库，其读者是讲葡萄牙语的模型。代码注释和 docblock 用英语，其中 src/index/bm25.ts 从第一遍起就保留为葡萄牙语。

许可证

MIT © 2026 Andrey Mudri