vault-mcp

英語 | ポルトガル語

コーディングエージェントのための長期記憶：回答する前にObsidianボールトを検索し、path:lineを引用し、どこに保存するかを尋ねずに学んだことを記録します。

Obsidianナレッジボールトを検索・読み取り・書き込みするためのMCPサーバー。語彙BM25と1ホップのwikiリンクによる検索。新しいノートを作成するか既存のノートに追記するかを決定する学習のインテリジェントなキャプチャ。ドメインMOCとデイリーノートへの自動伝播、およびドメインが新しい場合のナレッジインデックスへの自動伝播。ノートの移動、名前変更、昇格、アーカイブ、削除もサーバーを通じて行われるため、リンクとMOCエントリは静かに腐ることなく正しく保たれます。

Example

このプロジェクトを定義する2つのツールからの実際の出力で、このリポジトリのテストボールトに対して実行されたものです。

サーバーはポルトガル語で応答します。提供するボールトはポルトガル語で書かれており、ツールの応答も同様です。以下の出力はそのままのもので、翻訳されていません。

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 はクエリ内のどの用語にも一致しません。一致したノートから 1ホップのwikiリンク によって引き込まれ、スコアが減衰されます — それが via grafo（グラフ経由）が示すものです。

vault_learn は、ノートを作成するか既存のノートに追記するかを独自に決定し、最大4つのファイルを書き込み、1回 コミットします。

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)

4つのファイル、1つの docs(vault): {titulo} コミット — 学習全体を元に戻すには、そのコミットに対して git revert を実行します。concorrencia ドメインは存在しなかったため、呼び出しに confirm_novo_dominio: true が含まれ、MOCはゼロから構築され、ナレッジインデックスにそれを指す行が追加されました。

Related MCP server: mcp-obsidian-vault

Installation

@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で終了し、終了コードなしになることはありません。

Configuration

ボールトは環境変数を介して渡されます：

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に書き込みます。

Registering with 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 を置きます。

ボールトのパスは絶対パスであり、-e に単一の KEY=value ペアとして入れます — ペア全体を引用符で囲むことで、パスにスペースを含むボールトが機能します。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 行が追加され、これは実際にプッシュが試行された場合にのみ表示されます。

• 先行したリモートは自動では解決されません。 プル、リベース、マージはユーザーのナレッジベースを書き換えるため、それはユーザーの決定です — 1つのノートを保存する副作用ではありません。警告は状況を明示して停止します。

• 30秒に制限され、GIT_TERMINAL_PROMPT=0 が設定されます：stdioサーバーには資格情報プロンプトに応答するターミナルがないため、プロンプトはハングになります。資格情報はヘルパー（例：gh auth git-credential）またはSSHキーから取得する必要があります。

The Nine Tools

vault_learn の決定方法

vault_learn はタイトルとインサイトを組み合わせて主題を検索する。すでに 02-wiki/ にあり、直接の BM25 で到達した（グラフ展開ではない）ノートのみが学びを受け取る候補となる。そのような候補が見つかった場合:

1. 1.8倍の比率: 最上位のヒットは2位に対して少なくとも1.8倍の差をつけなければならない。その差がなければ疑念が残るため、新しいノートを作成する。

2. 論理積の重なり: 最上位のヒットは入力とタグを共有しているか、同じドメイン（02-wiki/<dominio>/）にある必要がある。重なりがなければ、スコアが高くても新しいノートを作成する。

両方の条件が満たされた場合、既存のノートの ## YYYY-MM-DD — Title セクションの下に追記する。それ以外の場合は 02-wiki/<dominio>/ に新しいノートを作成する。

この偏りは意図的である: 疑わしい場合は、学びを間違った場所に埋めるのではなく、新しいノートを作成する。後でノートを統合することは常に可能だが、失われた学びを回復することはできない。

逃げ道

最終的な保存先を変更できる例外が3つある:

1. タイトルの衝突: 重複ルールは「いいえ」と言うが、その名前のファイルがすでに存在する（同じスラッグを持つ古いノート）。サーバーはとにかくそれに追記し、anexado em <path> por coincidência de título; a checagem de duplicata não indicou essa nota と警告する。これにより、失われたノートが蓄積フローに戻る。

2. 重複対象がテキストを受け取れない: サーバーが候補ノートに追記することを決定したが、編集できない。サーバーはスラッグから派生した名前で新しいノートを作成し（例: multi-stage.md の代わりに multi-stage-cache-de-camadas.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 の1回の呼び出しで最大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。グラフ隣接ノート（リンクされたノート）のスコアに乗算される。1ホップであり、複数ホップではない。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

セキュリティ保証

以下のパスへの書き込みは拒否される：

• ボールト外のパス

• .git/、.obsidian/、node_modules/、_templates/、99-archive/ 内のパス

• シンボリックリンク（書き込み前に解決される）

• ハードリンク

単一のサーバーインスタンス内では、2つの同時 vault_learn または vault_write_note 呼び出しはそもそもインターリーブしない。各書き込みは前の書き込みの完了を待つ。書き込みがハングした場合（例：git がブロックされた場合）、60秒のタイムアウトは呼び出し元ではなく次の書き込みのためにキューを解放する — 先の呼び出しは実際の結果を待ち続ける。次の書き込みが開始されると、両方が実行中になる可能性があり、呼び出しは排他性が保証されなかったという警告を受け取る。これは、Obsidian からの同時書き込み、2番目のサーバーインスタンスからの書き込み、またはボールト内の git checkout からの書き込みに対しては保護されない。

検索と取得

検索は、2〜3レベルの見出しのチャンクに対して BM25 を実行し、散文、タグ、見出しを異なる重みでカバーする。クエリのどの用語もどのノートにもヒットしない場合、類似用語の提案を試みる（レーベンシュタイン距離 ≤ 2）。

純粋な BM25 検索の後、1ホップの 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/：アーカイブされたノート（読み取り可能、書き込み不可）

既知の制限

このサーバーが行わない3つのこと。それぞれ見落としではなく選択されたもの：

• 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 — はサニタイズされる。

これまでに提起された16のフォローアップはすべて修正された — イベントループを約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 が 正確に9つのツールで応答することを要求する。これは、エントリポイントがライブラリであると判断して何も起動しないことをカバーする — シェルにはクリーンな終了コード0、クライアントには永遠の待機 — そしてこれが engines.node >= 20 を 検証済みの主張にするものである：CI は固定された26に加えて Node 20 でもこれを実行する。スイート自体は 20では実行できない（test/frontmatter.test.ts はランタイムの型ストリッピングに依存している）一方で、 コンパイル済み JavaScript は実行できるからである。

コミットメッセージとサーバー自身のユーザー向け文字列 — ツールの説明、エラーメッセージ、 diff 内の散文 — はポルトガル語（ブラジル）で書かれている：このサーバーが提供するボールトはポルトガル語の ナレッジベースであり、その読者はポルトガル語を話すモデルである。コードコメントと docblock は 英語で書かれており、src/index/bm25.ts は最初のパスからポルトガル語のまま残されている。

ライセンス

MIT © 2026 Andrey Mudri