Virtual Filesystem
@lu-zhengda
关于 Virtual Filesystem
PostgreSQL-backed virtual filesystem exposed via MCP tools. Persistent, session-isolated file operations for AI agents.
基本信息
配置
使用下面的配置,将此服务器添加到你的 MCP 客户端。
{
"mcpServers": {
"virtual-fs": {
"command": "npx",
"args": [
"-y",
"mcp-virtual-fs"
],
"env": {
"DATABASE_URL": "<YOUR_POSTGRESQL_CONNECTION_STRING>",
"VFS_AUTO_INIT": "true"
}
}
}
}工具
11Read the contents of a file. Returns the file content and size in bytes. Errors: ENOENT if the file does not exist, EISDIR if the path is a directory.
Write content to a file, creating it if it doesn't exist. Parent directories are created automatically (mkdir -p). Overwrites existing file content entirely. Errors: EISDIR if the path is an existing directory, EINVAL if writing to root.
Append content to the end of a file. Creates the file if it doesn't exist. Parent directories are created automatically. Useful for logs or incrementally building files. The 10 MB limit is per call — total file size is not capped. Errors: EISDIR if the path is an existing directory, EINVAL if appending to root.
Check whether a path exists and get metadata about it. Returns exists (boolean), and if it exists: type (file or directory), size (bytes, for files), or children count (for directories). Never errors — returns {exists: false} for missing paths.
List the contents of a directory. Returns an array of entries, each with a name and type (file or directory). Entries are sorted with directories first, then alphabetically. Errors: ENOENT if the directory does not exist, ENOTDIR if the path is a file.
Create a directory and any missing parent directories (mkdir -p behavior). Idempotent — succeeds even if the directory already exists. Returns whether the directory already existed. Errors: EEXIST if a file (not directory) already exists at the path.
Remove a file or directory. Directories are removed recursively including all descendants. This operation is non-recoverable — there is no undo or trash. Returns the total number of nodes deleted. Errors: ENOENT if the path does not exist, EINVAL if attempting to remove root.
Move or rename a file or directory. Moves all descendants when moving a directory. Parent directories at the destination are created automatically. Errors: ENOENT if source doesn't exist, EEXIST if destination already exists, EINVAL if moving root or moving a directory into itself.
Find files matching a glob pattern. Supports wildcards (*.ts), recursive matching (**/*.md), and brace expansion ({py,json}). Returns an array of matching file paths. Only matches files, not directories.
Search file contents using a regular expression. Returns matching lines with file path and line number. Optimized for fast content search across all files. Optionally filter which files to search with a path glob.
List all named persistent stores. Stores are cross-session namespaces for long-term data that persists indefinitely. Returns an array of store names.
概览
What is Virtual Filesystem?
Virtual Filesystem is an MCP server that provides AI agents with a persistent, PostgreSQL-backed virtual filesystem. It supports session-isolated file operations, cross-session shared stores, glob/grep search, and optional Row Level Security, all exposed as standard Model Context Protocol tools. It is designed for use with any MCP client such as Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and others.
How to use Virtual Filesystem?
Set up a PostgreSQL database (version 14 or later) and configure your MCP client to run npx -y mcp-virtual-fs with the DATABASE_URL environment variable and VFS_AUTO_INIT=true for automatic table creation. Then interact with the 11 POSIX-style tools (e.g., write, read, ls, glob, grep) which return structured JSON responses.
Key features of Virtual Filesystem
- Persistent file storage in PostgreSQL, surviving process restarts and container recycling
- Automatic session isolation with per-connection namespaces
- Cross-session named stores for sharing data between agents
- 11 POSIX-style tools: read, write, append, stat, ls, mkdir, rm, mv, glob, grep, stores
- Glob and grep search using PostgreSQL trigram indexes
- Optional Row Level Security for multi-tenant database-enforced isolation
- Zero configuration with auto-created tables on first run
Use cases of Virtual Filesystem
- Agent scratchpad: persistent workspace for LLM agents to read/write files across tool calls
- Long-term agent memory: store notes and context across sessions using named stores
- Multi-agent collaboration: multiple agents share files through cross-session stores
- Sandboxed file operations: agents interact with a virtual filesystem instead of the host OS
- CI/CD artifact storage: persist build outputs, logs, and reports in a queryable filesystem
FAQ from Virtual Filesystem
What are the prerequisites to run Virtual Filesystem?
Node.js 20 or later and PostgreSQL 14 or later (with the pg_trgm extension, included in most distributions). Docker is required for integration tests.
How does session management work?
Sessions are handled automatically. For stdio transport each process gets an auto-generated UUID; for HTTP/SSE the transport provides a sessionId. You can also set a deterministic VFS_SESSION_ID environment variable for resumable sessions. Priority is transport sessionId > VFS_SESSION_ID > auto-generated UUID.
How do cross-session stores work?
Named stores persist across sessions. Any session can read/write to a store by passing the store parameter to tools (e.g., write({ path: "/context.md", content: "notes", store: "agent-memory" })). Without store, operations target the session’s own namespace. Stores are auto-created on first use and are never affected by ephemeral session cleanup.
What transports and authentication are supported?
The server supports stdio, HTTP/SSE, and any transport that provides a sessionId. Authentication is handled via the DATABASE_URL connection string (e.g., PostgreSQL user/password). Row Level Security can be enabled for additional database-enforced isolation, requiring the server to connect as the vfs_app role.
How can I clean up old sessions?
Ephemeral sessions can be deleted with SQL: DELETE FROM vfs_sessions WHERE is_persistent = false AND created_at < now() - interval '7 days';. The ON DELETE CASCADE on vfs_nodes automatically handles file cleanup. Persistent stores are never affected.
文件与存储 分类下的更多 MCP 服务器
Filesystem MCP Server for WSL
webconsultingfilesystem MCP server for accessing WSL distributions from Windows
mcp-v8: V8 JavaScript MCP Server
r33drichardsMCP server that exposes a V8 JavaScript runtime as a tool for AI agents like Claude and Cursor. Supports persistent heap snapshots via S3 or local filesystem, and is ready for integration with modern AI development environments.
Filesystem MCP Server
cyanheadsA Model Context Protocol (MCP) server for platform-agnostic file capabilities, including advanced search/replace and directory tree traversal
PDF Reader MCP Server (@sylphlab/pdf-reader-mcp)
sylphlab📄 The PDF intelligence layer for AI agents — Agent Document Twin, evidence-first extraction, visual crops, OCR provenance, trust reports, and benchmark-gated releases. MCP server for Claude, Cursor, VS Code, and any MCP client.
WORK IN PROGRESS - USE WITH CAUTION - Windows:
hanwegMCP server for working with PDF files
评论