MCP Virtual Fs

mcp虚拟fs

](https://www.npmjs.com/package/mcp-virtual-fs)  ](https://www.npmjs.com/package/mcp-virtual-fs)  ](https://nodejs.org)

一 MCP服务器 它为AI代理提供了 持久的、PostgreSQL支持的虚拟文件系统。支持会话隔离文件操作、跨会话共享存储、glob/grep搜索和行级安全性——所有这些都是标准公开的 模型上下文协议 工具。

适用于任何MCP客户端： 克劳德桌面, 克劳德代码, 光标, 帆板运动, 克莱恩以及其他。

特性

• 持久文件存储 --文件存储在PostgreSQL中，并在进程重启、容器回收和重新部署中幸存下来
• 会话隔离 --每个代理会话都会自动获得自己的命名空间，无需配置
• 跨会话商店 --命名持久存储，用于在代理之间共享数据或用于长期代理内存
• 11个POSIX风格的工具 — read, write, append, stat, ls, mkdir, rm, mv, glob, grep, stores
• Glob和grep搜索 --按模式查找文件(**/*.ts)或者通过正则表达式搜索内容，由PostgreSQL三元组索引提供支持
• 行级安全性 --用于多租户部署的会话之间的可选数据库强制隔离
• 零配置 --首次运行时自动创建表 VFS_AUTO_INIT=true

用例

• 代理草稿 --为LLM代理提供一个持久的工作区，以便跨工具调用读/写文件
• 长期代理记忆 --使用命名存储跨会话存储笔记、上下文和知识
• 多Agent协作 --多个代理通过跨会话存储共享文件
• 沙盒文件操作 --代理与虚拟文件系统交互，而不是与主机操作系统交互
• CI/CD工件存储 --在可查询的文件系统中持久化构建输出、日志和报告

为什么

代理与用于上下文管理的文件系统配合良好，但将存储与代理运行时耦合意味着当Pod重启或容器被回收时，数据会丢失。此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 或克劳德代码 .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响应。

工具

所有工具（除 stores)接受可选 store 用于跨会话持久存储的参数。

会话管理

会话是自动处理的——工具参数中没有会话ID。

它是如何工作的：

优先级：运输 sessionId > VFS_SESSION_ID env-var>自动生成的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()

商店在首次使用时自动创建。

环境变量

手动数据库设置

如果您更喜欢自己管理模式而不是使用 VFS_AUTO_INIT:

psql $DATABASE_URL -f sql/schema.sql

行级安全（可选）

RLS提供数据库强制会话隔离。即使应用程序代码有一个bug，忽略了 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'"

然后配置MCP服务器以连接为 vfs_app:

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

发展

需求

• Node.js 20+
• 码头工人 （用于集成测试——通过以下方式运行PostgreSQL 试验容器)

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

命令

测试

测试使用 试验容器 在Docker中启动真正的PostgreSQL实例。无模拟——集成测试执行实际的SQL查询、三元组索引和RLS策略。

# Requires Docker running
npm test

会话清理

临时会议可以定期清理：

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

这 ON DELETE CASCADE 上 vfs_nodes 自动处理文件清理。持久存储（通过 store 参数）永远不会受到影响。

许可证

麻省理工学院