@@ -18,12 +18,15 @@ Agents work well with filesystems for context management, but coupling storage t
1818- ** Standard file operations** — 11 tools that mirror familiar POSIX commands
1919- ** Row Level Security** — optional database-enforced isolation between sessions
2020
21+ ## Prerequisites
22+
23+ - ** Node.js** 20 or later
24+ - ** PostgreSQL** 14 or later (with ` pg_trgm ` extension — included in most distributions)
25+
2126## Quick Start
2227
2328### 1. Set up PostgreSQL
2429
25- You need a PostgreSQL instance with the ` pg_trgm ` extension.
26-
2730``` bash
2831# Using Docker
2932docker run -d --name vfs-postgres \
@@ -174,45 +177,12 @@ Then configure the MCP server to connect as `vfs_app`:
174177}
175178```
176179
177- ## Architecture
178-
179- ```
180- MCP Client (Claude, agent, etc.)
181- ↓ stdio / HTTP
182- ┌───────────────────────────────────┐
183- │ tools.ts — 11 MCP tool handlers │
184- │ vfs.ts — filesystem semantics │
185- │ storage/interface.ts — abstract │
186- │ storage/postgres.ts — PG impl │
187- └───────────────────────────────────┘
188- ↓ SQL
189- PostgreSQL (with optional RLS)
190- ```
180+ ## Development
191181
192- The storage backend is pluggable. ` VirtualFS ` depends only on the ` StorageBackend ` interface — never on a concrete implementation.
182+ ### Requirements
193183
194- ```
195- mcp-virtual-fs/
196- ├── src/
197- │ ├── index.ts # Entry point: env config, MCP server + stdio
198- │ ├── tools.ts # 11 MCP tool registrations with Zod schemas
199- │ ├── vfs.ts # VirtualFS class: filesystem semantics
200- │ ├── paths.ts # Path normalization, validation, ancestors
201- │ └── storage/
202- │ ├── interface.ts # StorageBackend interface + types
203- │ ├── postgres.ts # PostgreSQL implementation
204- │ ├── schema.ts # Embedded SQL for auto-init
205- │ └── index.ts # Backend factory
206- ├── sql/
207- │ ├── schema.sql # Database schema
208- │ └── rls.sql # Row Level Security setup
209- └── tests/
210- ├── unit/ # Pure function tests
211- ├── integration/ # PostgreSQL Docker tests
212- └── helpers/ # Testcontainers setup
213- ```
214-
215- ## Development
184+ - ** Node.js** 20+
185+ - ** Docker** (for integration tests — runs PostgreSQL via [ testcontainers] ( https://node.testcontainers.org/ ) )
216186
217187``` bash
218188git clone https://github.com/lu-zhengda/mcp-virtual-fs.git
0 commit comments