AI导哈

虚拟文件系统服务

一个为AI代理提供的持久化、基于PostgreSQL的虚拟文件系统，支持会话隔离、跨会话共享存储、全局搜索和行级安全。

  • by lu-zhengda
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 lu-zhengda/mcp-virtual-fs

使用说明

mcp虚拟fs

一 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响应。

工具

工具 参数 返回 描述
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 env-var 确定性/可恢复会话

优先级：运输 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()

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

环境变量

变量 必填 默认 描述
DATABASE_URL 是 -- PostgreSQL连接字符串
VFS_AUTO_INIT 没有 false 启动时自动创建表
VFS_SESSION_ID 否 随机UUID 确定性会话ID
VFS_ENABLE_RLS 没有 false 启用行级安全
VFS_STORAGE_BACKEND 没有 postgres 存储后端类型

手动数据库设置

如果您更喜欢自己管理模式而不是使用 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

命令

命令 描述
npm run build 编译TypeScript
npm test 运行所有测试（需要Docker）
npm run test:unit 仅运行单元测试
npm run test:integration 仅运行集成测试
npm run lint 运行ESLint
npm run lint:fix 自动修复棉绒问题
npm run dev 使用tsx运行（无构建步骤）

测试

测试使用 试验容器 在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 参数）永远不会受到影响。

许可证

麻省理工学院

相关 MCP