Virtual Filesystem

mcp-virtual-fs

AI エージェントに永続的な PostgreSQL ベースの仮想ファイルシステムを提供する MCP サーバーです。セッションごとに分離されたファイル操作、セッション間で共有できるストア、glob／grep 検索、行レベルセキュリティをサポートし、標準の Model Context Protocol ツールとしてすべての機能を利用できます。

あらゆる MCP クライアントに対応しています。Claude Desktop、Claude Code、Cursor、Windsurf、Cline などで動作します。

機能

• 永続的なファイルストレージ — ファイルは PostgreSQL に保存され、プロセスの再起動、コンテナの再利用、再デプロイ後も保持されます
• セッションの分離 — 各エージェントセッションに専用の名前空間が自動的に割り当てられ、設定は不要です
• セッション間で共有できるストア — エージェント間のデータ共有や、エージェントの長期記憶に使える名前付きの永続ストアです
• POSIX 形式の 11 個のツール — read、write、append、stat、ls、mkdir、rm、mv、glob、grep、stores
• Glob／grep 検索 — パターン（**/*.ts）でファイルを検索したり、正規表現で内容を検索したりできます。PostgreSQL のトライグラムインデックスを利用します
• 行レベルセキュリティ — マルチテナント環境でセッション間の分離をデータベース側で強制できます（任意）
• 設定不要 — VFS_AUTO_INIT=true により初回実行時にテーブルを自動作成します

ユースケース

• エージェントのスクラッチパッド — ツール呼び出しをまたいでファイルを読み書きできる永続的な作業領域を LLM エージェントに提供します
• エージェントの長期記憶 — 名前付きストアを使って、セッションをまたいでメモ、コンテキスト、知識を保存します
• マルチエージェントの連携 — 複数のエージェントがセッション間で共有できるストアを通じてファイルを共有します
• サンドボックス化されたファイル操作 — エージェントはホスト OS ではなく、仮想ファイルシステムを操作します
• CI/CD アーティファクトの保存 — ビルド出力、ログ、レポートを検索可能なファイルシステムに保存します

背景

エージェントはコンテキスト管理にファイルシステムを活用できますが、ストレージをエージェントのランタイムに結び付けると、ポッドの再起動やコンテナの再利用時にデータが失われます。この MCP サーバーは、ファイル操作を PostgreSQL に移すことでストレージをランタイムから切り離し、ホストのファイルシステムに触れることなく、エージェントに永続的で分離された検索可能なファイルストレージを提供します。

前提条件

• Node.js 20 以降
• PostgreSQL 14 以降（pg_trgm 拡張機能が必要です。ほとんどのディストリビューションに含まれています）

クイックスタート

1. PostgreSQL をセットアップする

# Using Docker
docker run -d --name vfs-postgres \
  -e POSTGRES_DB=vfs \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16-alpine

2. MCP クライアントを設定する

MCP クライアントの設定ファイルに追加します（例：Claude Desktop の claude_desktop_config.json または Claude Code の .mcp.json）。

{
  "mcpServers": {
    "virtual-fs": {
      "command": "npx",
      "args": ["-y", "mcp-virtual-fs"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/vfs",
        "VFS_AUTO_INIT": "true"
      }
    }
  }
}

以上です。VFS_AUTO_INIT=true を指定すると、初回実行時にテーブルが作成されます。

3. ツールを使う

ツール名には短い POSIX 形式の名前を使用します。

write({ path: "/notes/todo.md", content: "# My Tasks\n- Ship feature" })
read({ path: "/notes/todo.md" })
ls({ path: "/notes" })
glob({ pattern: "**/*.md" })
grep({ pattern: "TODO" })

すべてのツールは、構造化された JSON レスポンスを返します。

ツール

ツール	パラメーター	戻り値	説明
read	path	{content, size}	ファイルの内容を読み取ります
write	path、content	{path, size, has_parents}	ファイルを書き込みます（親ディレクトリは自動的に作成されます）
append	path、content	{path, appended_bytes}	ファイルに追記します（ファイルがない場合は作成します）
stat	path	{exists, type?, size?, children?}	存在を確認し、メタデータを取得します
ls	path	{entries: [{name, type}]}	ディレクトリを一覧表示します（ディレクトリが先、その後にアルファベット順で表示）
mkdir	path	{path, already_existed}	ディレクトリと親ディレクトリを作成します（mkdir -p）
rm	path	{path, deleted}	ファイルまたはディレクトリを再帰的に削除します
mv	source、destination	{source, destination}	ファイルまたはディレクトリを移動／名前変更します
glob	pattern	{files, count}	glob でファイルを検索します（例：**/*.ts、**/*.{js,ts}）
grep	pattern、path_filter?	{matches, count}	正規表現でファイルの内容を検索します
stores	(なし)	{stores, count}	永続ストア名をすべて一覧表示します

stores を除くすべてのツールは、セッションをまたいで永続ストレージを利用するための省略可能な store パラメーターを受け付けます。

セッション管理

セッションは自動的に処理されます。ツールのパラメーターにセッション ID を指定する必要はありません。

仕組み：

トランスポート	セッションの識別方法	動作
stdio	プロセスごとに自動生成される UUID	MCP 接続ごとに一意のセッションが作成されます
HTTP/SSE	トランスポートが提供する sessionId	MCP プロトコルが処理します
任意	VFS_SESSION_ID 環境変数	決定的／再開可能なセッション

優先順位：トランスポートの sessionId > VFS_SESSION_ID 環境変数 > 自動生成される UUID。

再開可能なセッション

プロセスの再起動後に以前のセッションを再開するには、決定的なセッション ID を設定します。

{
  "env": {
    "DATABASE_URL": "postgresql://...",
    "VFS_SESSION_ID": "my-agent-session-1"
  }
}

セッション間で共有されるストア

名前付きストアはセッションをまたいで保持されます。store パラメーターを渡すことで、任意のセッションからストアの読み書きができます。

// Session A writes to a store
write({ path: "/context.md", content: "project notes", store: "agent-memory" })

// Session B (days later) reads from the same store
read({ path: "/context.md", store: "agent-memory" })

// Without `store`, operations target the session's own namespace
write({ path: "/scratch.txt", content: "session-only data" })

// List all available stores
stores()

ストアは初回使用時に自動作成されます。

環境変数

変数	必須	デフォルト	説明
DATABASE_URL	はい	—	PostgreSQL 接続文字列
VFS_AUTO_INIT	いいえ	false	起動時にテーブルを自動作成します
VFS_SESSION_ID	いいえ	random UUID	決定的なセッション ID
VFS_ENABLE_RLS	いいえ	false	行レベルセキュリティを有効にします
VFS_STORAGE_BACKEND	いいえ	postgres	ストレージバックエンドの種類

データベースの手動セットアップ

VFS_AUTO_INIT を使用せず、自分でスキーマを管理する場合：

psql $DATABASE_URL -f sql/schema.sql

行レベルセキュリティ（任意）

RLS により、データベース側でセッション分離が適用されます。アプリケーションコードに不具合があり、WHERE session_id = 句が省略された場合でも、PostgreSQL 自体がセッションをまたぐアクセスを防ぎます。

# Run after schema.sql
psql $DATABASE_URL -f sql/rls.sql

# Update the vfs_app password
psql $DATABASE_URL -c "ALTER ROLE vfs_app PASSWORD 'your-secure-password'"

次に、vfs_app として接続するよう MCP サーバーを設定します。

{
  "env": {
    "DATABASE_URL": "postgresql://vfs_app:your-secure-password@localhost:5432/vfs",
    "VFS_ENABLE_RLS": "true"
  }
}

開発

要件

• Node.js 20+
• Docker（統合テスト用 — testcontainers を介して PostgreSQL を実行します）

git clone https://github.com/lu-zhengda/mcp-virtual-fs.git
cd mcp-virtual-fs
npm install
npm run build

コマンド

コマンド	説明
npm run build	TypeScript をコンパイルします
npm test	すべてのテストを実行します（Docker が必要です）
npm run test:unit	ユニットテストのみを実行します
npm run test:integration	統合テストのみを実行します
npm run lint	ESLint を実行します
npm run lint:fix	lint の問題を自動修正します
npm run dev	tsx で実行します（ビルド手順なし）

テスト

テストでは testcontainers を使用して、Docker 内に実際の PostgreSQL インスタンスを起動します。モックは使用せず、統合テストでは実際の SQL クエリ、トライグラムインデックス、RLS ポリシーを検証します。

# Requires Docker running
npm test

セッションのクリーンアップ

一時セッションは定期的にクリーンアップできます。

DELETE FROM vfs_sessions
WHERE is_persistent = false
  AND created_at < now() - interval '7 days';

vfs_nodes の ON DELETE CASCADE により、ファイルは自動的にクリーンアップされます。store パラメーターで作成された永続ストアには影響しません。

ライセンス

MIT