vaultnotes

vaultnotes

vaultnotes は、ローカルディスク上のフォルダーにプレーンファイルとして保存されたノートの保管庫を操作するための小さなツールセットです。保管庫内の一覧表示、ノートの読み取り、Markdown ファイル全体の検索、ノートへの追記やパッチ適用、削除ができます。コマンドラインから、またはエージェント向けの 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 サーバー

1 つの実行ファイルで、どちらの使い方にも対応します。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 を参照してください。