AI导哈

只读文件系统MCP服务

一个基于Node.js的只读文件系统操作服务，实现Model Context Protocol（MCP）协议，提供文件读取、目录列表、搜索等功能，并支持动态目录访问控制。

  • by abhinav-mangla
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 abhinav-mangla/filesystem-readonly-mcp

使用说明

只读文件系统MCP服务器

Node.js服务器实现了用于只读文件系统操作的模型上下文协议（MCP）。

特性

  • 读取文件（文本、媒体、多个文件）
  • 列出目录和目录树
  • 列出目录及其大小和摘要
  • 搜索文件
  • 获取文件元数据
  • 通过动态目录访问控制 根

目录访问控制

服务器使用灵活的目录访问控制系统。目录可以通过命令行参数指定，也可以通过以下方式动态指定 根.

方法1：命令行参数

启动服务器时指定允许的目录：

filesystem-readonly-mcp /path/to/dir1 /path/to/dir2

方法2:MCP根（推荐）

支持的MCP客户端 根 可以动态更新Allowed目录。

客户端通知服务器的根目录，在提供时完全替换任何服务器端允许的目录。

重要：如果服务器在没有命令行参数的情况下启动，并且客户端不支持根协议（或提供空根），则服务器将在初始化过程中抛出错误。

这是推荐的方法，因为这可以通过以下方式实现运行时目录更新 roots/list_changed 无需重新启动服务器即可发出通知，提供更灵活、更现代的集成体验。

运作原理

服务器的目录访问控制遵循以下流程：

  1. 服务器启动

    • 服务器从命令行参数（如果提供）中的目录开始
    • 如果没有提供参数，服务器将从允许的空目录开始

  2. 客户端连接和初始化

    • 客户端连接并发送 initialize 具有能力的请求
    • 服务器检查客户端是否支持根协议(capabilities.roots)

  3. 根协议处理 （如果客户端支持root）

    • 初始化时：服务器通过从客户端请求根 roots/list
    • 客户端使用其配置的根进行响应
    • 服务器将所有允许的目录替换为客户端的根目录
    • 运行时更新：客户端可以发送 notifications/roots/list_changed
    • 服务器请求更新根目录并再次替换允许的目录

  4. 回退行为 （如果客户端不支持根）

    • 服务器仅继续使用命令行目录
    • 无法进行动态更新

  5. 访问控制

    • 所有文件系统操作都限制在允许的目录中
    • 使用 list_allowed_directories 查看当前目录的工具
    • 服务器需要至少一个允许的目录才能运行

备注：服务器只允许在通过以下方式指定的目录内进行操作 args 或者通过Roots。

API（只读）

工具

  • read_text_file

    • 以文本形式读取文件的完整内容
    • 输入：
      • path （字符串）
      • head （数字，可选）：前N行
      • tail （数字，可选）：最后N行
    • 始终将文件视为UTF-8文本，而不管扩展名如何
    • 注： head 和 tail 不能一起使用

  • read_media_file

    • 读取图像或音频文件
    • 输入：
      • path （字符串）
    • 流式传输文件并返回具有相应MIME类型的base64数据

  • 读取多个文件

    • 同时读取多个文件
    • 输入： paths （字符串[]）
    • 读取失败不会停止整个操作

  • list_directory

    • 列出带有[FILE]或[DIR]前缀的目录内容
    • 输入： path （字符串）

  • list_directory_with_sizes

    • 列出目录内容，包括大小和摘要
    • 输入：
      • path （字符串）
      • sortBy （“name”|“size”，可选，默认值：“name”）
    • 输出包括用[FILE]/[DIR]格式化的条目和文件大小

  • 目录树

    • 以JSON格式获取文件和目录的递归树视图
    • 输入： path （字符串）
    • 输出：条目数组 name, type （文件|目录），以及 children 对于目录

  • 搜索文件

    • 递归搜索文件/目录
    • 输入：
      • path （string）：起始目录
      • pattern （string）：搜索模式
      • excludePatterns （string[]）：排除任何模式。支持Glob格式。
    • 不区分大小写的匹配
    • 返回匹配项的完整路径

  • 获取_文件_信息

    • 获取详细的文件/目录元数据
    • 输入： path （字符串）
    • 退货：
      • 尺寸
      • 创建时间
      • 修改时间
      • 访问时间
      • 类型（文件/目录）
      • 权限

  • list_allowed_directories

    • 列出服务器允许访问的所有目录
    • 无需输入
    • 退货：
      • 此服务器可以读取的目录

使用Claude Desktop

将此添加到您的 claude_desktop_config.json:

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "filesystem-readonly-mcp",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

使用VS代码

方法1：用户配置（推荐） 将配置添加到用户级MCP配置文件中。打开命令选项板(Ctrl + Shift + P)然后跑 MCP: Open User Configuration。这将打开您的用户 mcp.json 您可以在其中添加服务器配置的文件。

方法2：工作空间配置 或者，您可以将配置添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。

有关VS Code中MCP配置的更多详细信息，请参阅 官方VS Code MCP文档.

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "filesystem-readonly-mcp",
        "${workspaceFolder}"
      ]
    }
  }
}

许可证

此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。

相关 MCP