{
  "markdown": "# mcp-virtual-fs\n\n[![npm version](https://img.shields.io/npm/v/mcp-virtual-fs)](https://www.npmjs.com/package/mcp-virtual-fs)\n[![CI](https://github.com/lu-zhengda/mcp-virtual-fs/actions/workflows/ci.yml/badge.svg)](https://github.com/lu-zhengda/mcp-virtual-fs/actions/workflows/ci.yml)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-virtual-fs)](https://www.npmjs.com/package/mcp-virtual-fs)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/node/v/mcp-virtual-fs)](https://nodejs.org)\n\nAn [MCP server](https://modelcontextprotocol.io/) that provides AI agents with a **persistent, PostgreSQL-backed virtual filesystem**. Supports session-isolated file operations, cross-session shared stores, glob/grep search, and Row Level Security — all exposed as standard [Model Context Protocol](https://modelcontextprotocol.io/) tools.\n\nWorks with any MCP client: **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, **Cline**, and others.\n\n## Features\n\n- **Persistent file storage** — files are stored in PostgreSQL and survive process restarts, container recycling, and redeployments\n- **Session isolation** — each agent session gets its own namespace automatically, no configuration needed\n- **Cross-session stores** — named persistent stores for sharing data between agents or for long-term agent memory\n- **11 POSIX-style tools** — `read`, `write`, `append`, `stat`, `ls`, `mkdir`, `rm`, `mv`, `glob`, `grep`, `stores`\n- **Glob and grep search** — find files by pattern (`**/*.ts`) or search content by regex, powered by PostgreSQL trigram indexes\n- **Row Level Security** — optional database-enforced isolation between sessions for multi-tenant deployments\n- **Zero config** — auto-creates tables on first run with `VFS_AUTO_INIT=true`\n\n## Use Cases\n\n- **Agent scratchpad** — give LLM agents a persistent workspace to read/write files across tool calls\n- **Long-term agent memory** — store notes, context, and knowledge across sessions using named stores\n- **Multi-agent collaboration** — multiple agents share files through cross-session stores\n- **Sandboxed file operations** — agents interact with a virtual filesystem instead of the host OS\n- **CI/CD artifact storage** — persist build outputs, logs, and reports in a queryable filesystem\n\n## Why\n\nAgents work well with filesystems for context management, but coupling storage to the agent runtime means data is lost when pods restart or containers are recycled. This MCP server decouples storage from runtime by moving file operations to PostgreSQL — giving agents persistent, isolated, and searchable file storage without touching the host filesystem.\n\n## Prerequisites\n\n- **Node.js** 20 or later\n- **PostgreSQL** 14 or later (with `pg_trgm` extension — included in most distributions)\n\n## Quick Start\n\n### 1. Set up PostgreSQL\n\n```bash\n# Using Docker\ndocker run -d --name vfs-postgres \\\n  -e POSTGRES_DB=vfs \\\n  -e POSTGRES_PASSWORD=postgres \\\n  -p 5432:5432 \\\n  postgres:16-alpine\n```\n\n### 2. Configure your MCP client\n\nAdd to your MCP client config (e.g., Claude Desktop `claude_desktop_config.json` or Claude Code `.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"virtual-fs\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-virtual-fs\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgresql://postgres:postgres@localhost:5432/vfs\",\n        \"VFS_AUTO_INIT\": \"true\"\n      }\n    }\n  }\n}\n```\n\nThat's it. `VFS_AUTO_INIT=true` creates the tables on first run.\n\n### 3. Use the tools\n\nTool names are short POSIX-style names:\n\n```\nwrite({ path: \"/notes/todo.md\", content: \"# My Tasks\\n- Ship feature\" })\nread({ path: \"/notes/todo.md\" })\nls({ path: \"/notes\" })\nglob({ pattern: \"**/*.md\" })\ngrep({ pattern: \"TODO\" })\n```\n\nAll tools return structured JSON responses.\n\n## Tools\n\n| Tool | Parameters | Returns | Description |\n|------|-----------|---------|-------------|\n| `read` | `path` | `{content, size}` | Read file contents |\n| `write` | `path`, `content` | `{path, size, has_parents}` | Write file (creates parents automatically) |\n| `append` | `path`, `content` | `{path, appended_bytes}` | Append to file (creates if missing) |\n| `stat` | `path` | `{exists, type?, size?, children?}` | Check existence and get metadata |\n| `ls` | `path` | `{entries: [{name, type}]}` | List directory (dirs first, then alphabetical) |\n| `mkdir` | `path` | `{path, already_existed}` | Create directory and parents (mkdir -p) |\n| `rm` | `path` | `{path, deleted}` | Remove file or directory recursively |\n| `mv` | `source`, `destination` | `{source, destination}` | Move/rename file or directory |\n| `glob` | `pattern` | `{files, count}` | Find files by glob (e.g., `**/*.ts`, `**/*.{js,ts}`) |\n| `grep` | `pattern`, `path_filter?` | `{matches, count}` | Search file contents by regex |\n| `stores` | *(none)* | `{stores, count}` | List all persistent store names |\n\nAll tools (except `stores`) accept an optional `store` parameter for cross-session persistent storage.\n\n## Session Management\n\nSessions are handled automatically — no session ID in tool parameters.\n\n**How it works:**\n\n| Transport | Session identity | Behavior |\n|-----------|-----------------|----------|\n| stdio | Auto-generated UUID per process | Each MCP connection = unique session |\n| HTTP/SSE | Transport-provided `sessionId` | MCP protocol handles it |\n| Any | `VFS_SESSION_ID` env var | Deterministic/resumable sessions |\n\nPriority: transport `sessionId` > `VFS_SESSION_ID` env var > auto-generated UUID.\n\n### Resumable sessions\n\nTo resume a previous session across process restarts, set a deterministic session ID:\n\n```json\n{\n  \"env\": {\n    \"DATABASE_URL\": \"postgresql://...\",\n    \"VFS_SESSION_ID\": \"my-agent-session-1\"\n  }\n}\n```\n\n## Cross-Session Stores\n\nNamed stores persist across sessions. Any session can read/write to a store by passing the `store` parameter:\n\n```\n// Session A writes to a store\nwrite({ path: \"/context.md\", content: \"project notes\", store: \"agent-memory\" })\n\n// Session B (days later) reads from the same store\nread({ path: \"/context.md\", store: \"agent-memory\" })\n\n// Without `store`, operations target the session's own namespace\nwrite({ path: \"/scratch.txt\", content: \"session-only data\" })\n\n// List all available stores\nstores()\n```\n\nStores are auto-created on first use.\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `DATABASE_URL` | Yes | — | PostgreSQL connection string |\n| `VFS_AUTO_INIT` | No | `false` | Auto-create tables on startup |\n| `VFS_SESSION_ID` | No | random UUID | Deterministic session ID |\n| `VFS_ENABLE_RLS` | No | `false` | Enable Row Level Security |\n| `VFS_STORAGE_BACKEND` | No | `postgres` | Storage backend type |\n\n## Manual Database Setup\n\nIf you prefer to manage the schema yourself instead of using `VFS_AUTO_INIT`:\n\n```bash\npsql $DATABASE_URL -f sql/schema.sql\n```\n\n### Row Level Security (optional)\n\nRLS provides database-enforced session isolation. Even if application code has a bug that omits a `WHERE session_id =` clause, PostgreSQL itself prevents cross-session access.\n\n```bash\n# Run after schema.sql\npsql $DATABASE_URL -f sql/rls.sql\n\n# Update the vfs_app password\npsql $DATABASE_URL -c \"ALTER ROLE vfs_app PASSWORD 'your-secure-password'\"\n```\n\nThen configure the MCP server to connect as `vfs_app`:\n\n```json\n{\n  \"env\": {\n    \"DATABASE_URL\": \"postgresql://vfs_app:your-secure-password@localhost:5432/vfs\",\n    \"VFS_ENABLE_RLS\": \"true\"\n  }\n}\n```\n\n## Development\n\n### Requirements\n\n- **Node.js** 20+\n- **Docker** (for integration tests — runs PostgreSQL via [testcontainers](https://node.testcontainers.org/))\n\n```bash\ngit clone https://github.com/lu-zhengda/mcp-virtual-fs.git\ncd mcp-virtual-fs\nnpm install\nnpm run build\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compile TypeScript |\n| `npm test` | Run all tests (requires Docker) |\n| `npm run test:unit` | Run unit tests only |\n| `npm run test:integration` | Run integration tests only |\n| `npm run lint` | Run ESLint |\n| `npm run lint:fix` | Auto-fix lint issues |\n| `npm run dev` | Run with tsx (no build step) |\n\n### Testing\n\nTests use [testcontainers](https://node.testcontainers.org/) to spin up real PostgreSQL instances in Docker. No mocks — the integration tests exercise actual SQL queries, trigram indexes, and RLS policies.\n\n```bash\n# Requires Docker running\nnpm test\n```\n\n## Session Cleanup\n\nEphemeral sessions can be cleaned up periodically:\n\n```sql\nDELETE FROM vfs_sessions\nWHERE is_persistent = false\n  AND created_at < now() - interval '7 days';\n```\n\nThe `ON DELETE CASCADE` on `vfs_nodes` handles file cleanup automatically. Persistent stores (created via the `store` parameter) are never affected.\n\n## License\n\nMIT\n",
  "bytes": 8793,
  "sha": "a35d112ad263d92e40be77508f1e84d8c3bfc2deee195a5c932bb4d3666cffba",
  "repo_slug": "lu-zhengda/mcp-virtual-fs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lu_zhengda_virtual_fs_0452a8b3/readme"
}