AI导哈

文件系统服务

基于Bun的文件系统服务，实现模型上下文协议（MCP），提供全面的权限控制和增强的文件操作功能。

  • by rawr-ai
  • TypeScript
  • 混合部署
  • 3 星标
  • 更新于
在 GitHub 查看 rawr-ai/mcp-filesystem

使用说明

文件系统MCP服务器

基于Bun的服务器实现了用于文件系统操作的模型上下文协议（MCP），具有全面的权限控制和增强的功能。

开发用途 包子 服务器可以直接从TypeScript运行 bun，但大多数MCP客户端执行与Node兼容的JavaScript。使用 node dist/index.js 除非您有意使用Bun运行TypeScript条目。

特性

  • 精细的权限控制（只读、完全访问或特定操作权限）
  • 在允许的目录内进行安全的文件操作
  • 文件操作：
    • 读取/写入/修改文件
    • 创建/列出/删除目录
    • 移动文件/目录
    • 按名称或扩展名搜索文件
    • 获取文件元数据
  • 目录操作：
    • 目录结构的树形视图
    • 具有排除模式的递归操作
  • 实用功能：
    • XML到JSON转换
    • 一次调用中的多个文件操作
    • 使用模式匹配进行高级文件编辑
  • 安全功能：
    • Symlink控制
    • 路径验证
    • 沙盒操作

备注：服务器只允许在通过指定的目录内进行操作 args 并根据配置的权限。

安装

  1. 安装Bun （需要Bun v1.0或更高版本）
    curl -fsSL https://bun.sh/install | bash
  2. 安装依赖项
    bun install
  3. 构建项目 （节点运行时需要）
    bun run build
  4. 运行测试
    bun test

配置选项

路径可能包括环境变量，如 $HOME, ${CUSTOM}，或 %USERPROFILE%。选择适合您设置的模态：

本地（节点或Bun）

使用Node构建JavaScript或Bun直接运行TypeScript。

{ "command": "node", "args": ["/path/to/mcp-filesystem/dist/index.js", "$HOME/allowed-directory"] }

{ "command": "bun",  "args": ["/path/to/mcp-filesystem/index.ts", "$HOME/allowed-directory"] }

Git托管

直接从公共仓库运行，无需克隆。

{ "command": "bunx", "args": ["github:rawr-ai/mcp-filesystem", "$HOME/allowed-directory"] }

{ "command": "npx",  "args": ["github:rawr-ai/mcp-filesystem", "$HOME/allowed-directory"] }

NPM包（即将推出）

计划出版至 rawr-ai/mcp-filesystem.

{ "command": "bunx", "args": ["rawr-ai/mcp-filesystem", "$HOME/allowed-directory"] }

{ "command": "npx",  "args": ["rawr-ai/mcp-filesystem", "$HOME/allowed-directory"] }

码头工人

隔离的容器环境。

{ "command": "docker", "args": ["run", "--rm", "-v", "$HOME/allowed-directory:/data", "mcp/filesystem", "/data"] }

托管式服务

适用于glama.ai等托管MCP主机。

{ "mcpServers": { "filesystem": { "url": "https://glama.ai/rawr-ai/mcp-filesystem" } } }

请参阅 examples/ 用于平台特定配置（Cursor、Roo等）和其他路径变体的目录。

API

资源

  • file://system：文件系统操作界面

工具

所有工具参数模式都定义为 打字机 并通过注册 toolSchemas 在中映射 src/schemas这确保了每个工具共享一个一致的模式，处理程序可以引用该模式。

  • read_file

    • 读取文件内容（响应上限）
    • 输入：
      • path （字符串）
      • maxBytes （number）：返回的最大字节数
    • 最多返回 maxBytes 保护下游消费者的字节数

  • 读取多个文件

    • 同时读取多个文件
    • 输入：
      • paths （字符串[]）
      • maxBytesPerFile （number）：每个文件返回的最大字节数
    • 读取失败不会停止整个操作

  • 创建文件

    • 创建一个包含内容的新文件
    • 输入：
      • path （string）：文件位置
      • content （string）：文件内容
    • 如果文件已存在，则失败
    • 需要 create 许可

  • 修改文件

    • 用新内容修改现有文件
    • 输入：
      • path （string）：文件位置
      • content （string）：新文件内容
    • 如果文件不存在，则失败
    • 需要 edit 许可

  • edit_file

    • 使用模式匹配和格式进行选择性编辑
    • 特征：
      • 基于行和多行内容匹配
      • 保留缩进的空白归一化
      • 具有正确定位的多个同时编辑
      • 压痕样式检测和保存
      • 带上下文的Git风格差异输出
      • 使用模拟运行模式预览更改
    • 输入：
      • path （string）：要编辑的文件
      • edits （array）：编辑操作列表
        • oldText （string）：要搜索的文本（完全匹配）
        • newText （string）：要替换的文本
      • dryRun （boolean）：预览更改而不应用（默认值：false）
      • maxBytes （number）：编辑前可读取的最大字节数
    • 返回干运行的详细差异，否则应用更改
    • 需要 edit 许可
    • 最佳实践：始终先使用dryRun预览更改

  • create_directory

    • 创建新目录或确保其存在
    • 输入： path （字符串）
    • 如果需要，创建父目录
    • 如果目录存在，则自动成功
    • 需要 create 许可

  • list_directory

    • 列出带有[FILE]或[DIR]前缀的目录内容
    • 输入： path （字符串）
    • 返回文件和目录的详细列表

  • 目录树

    • 获取目录结构的递归树视图
    • 输入： path （字符串）
    • 返回包含文件和目录的JSON结构
    • 每个条目都包括名称、类型和子项（用于目录）

  • move_file

    • 移动或重命名文件和目录
    • 输入：
      • source （string）：源路径
      • destination （string）：目标路径
    • 如果目标存在，则失败
    • 适用于文件和目录
    • 需要 move 许可

  • 删除文件

    • 删除文件
    • 输入： path （字符串）
    • 如果文件不存在，则失败
    • 需要 delete 许可

  • delete_directory

    • 删除目录
    • 输入：
      • path （string）：要删除的目录
      • recursive （boolean）：是否删除内容（默认值：false）
    • 如果目录不为空且递归为false，则失败
    • 需要 delete 许可

  • 搜索文件

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

  • find_files_by_扩展名

    • 查找具有特定扩展名的所有文件
    • 输入：
      • path （string）：起始目录
      • extension （string）：要查找的文件扩展名
      • excludePatterns （string[]）：可选排除模式
    • 不区分大小写的扩展匹配
    • 返回匹配文件的完整路径

  • 获取_文件_信息

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

  • 获取权限

    • 获取当前服务器权限
    • 无需输入
    • 退货：
      • 权限标志（只读、完全访问、创建、编辑、移动、删除）
      • Symlink跟踪状态
      • 允许的目录数量

  • list_allowed_directories

    • 列出服务器允许访问的所有目录
    • 无需输入
    • 返回允许的目录路径数组

  • xml_to_json

    • 将XML文件转换为JSON格式
    • 输入：
      • xmlPath （string）：源XML文件
      • jsonPath （string）：目标JSON文件
      • maxResponseBytes （number，可选）：写入JSON的最大大小；总结了大量产出
      • options （对象，可选）：
        • ignoreAttributes （布尔值）：跳过XML属性（默认值：false）
        • preserveOrder （boolean）：维护属性顺序（默认值：true）
        • format （boolean）：漂亮的打印JSON（默认值：true）
        • indentSize （number）：JSON缩进（默认值：2）
    • 需要 read XML文件的权限
    • 需要 create 或 edit JSON文件的权限

  • xml_to_json_string

    • 将XML文件转换为JSON字符串
    • 输入：
      • xmlPath （string）：源XML文件
      • maxResponseBytes （number，可选）：返回JSON字符串的最大大小；总结了大量产出
      • options （对象，可选）：
        • ignoreAttributes （布尔值）：跳过XML属性（默认值：false）
        • preserveOrder （boolean）：维护属性顺序（默认值：true）
    • 需要 read XML文件的权限
    • 返回JSON字符串表示形式（响应上限）

  • xml_query

    • 使用XPath表达式查询XML文件
    • 输入：
      • path （string）：XML文件的路径
      • query （字符串，可选）：要执行的XPath查询
      • structureOnly （boolean，可选）：仅返回标记结构
      • includeAttributes （布尔值，可选）：包含属性信息（默认值：true）
      • maxResponseBytes （number，可选）：返回JSON的最大大小；默认为200KB
        • 遗产 maxBytes 仍被接受并视为响应上限
    • XPath示例：
      • 获取所有元素： //tagname
      • 获取具有特定属性的元素： //tagname[@attr="value"]
      • 获取文本内容： //tagname/text()
    • 解析完整文件；根据需要截断响应以适应限制

  • xml_结构

    • 分析XML结构
    • 输入：
      • path （string）：XML文件的路径
      • maxDepth （数字，可选）：分析深度（默认值：2）
      • includeAttributes （布尔值，可选）：包括属性分析（默认值：true）
      • maxResponseBytes （number，可选）：返回JSON的最大大小；默认为200KB
        • 遗产 maxBytes 仍被接受并视为响应上限
    • 返回有关元素、属性、命名空间和层次结构的统计信息
    • 解析完整文件；如果响应超过限制，则返回摘要结构

  • regex_search_content

    • 使用正则表达式搜索文件内容
    • 输入：
      • path （string）：要搜索的根目录
      • regex （string）：正则表达式模式
      • filePattern （字符串，可选）：Glob用于限制文件（默认值： *)
      • maxDepth （数字，可选）：目录深度（默认值：2）
      • maxFileSize （数字，可选）：最大文件大小（以字节为单位）（默认值：10MB）
      • maxResults （number，可选）：最大匹配文件数（默认值：50）
    • 返回文件和匹配行的可读摘要

参数验证

服务器使用验证所有工具输入 parseArgs 帮手。 parseArgs 根据适当的TypeBox架构解析传入数据，并在参数与预期结构不匹配时抛出错误。

权限和安全

服务器实现了一个具有细粒度权限控制的全面安全模型：

目录访问控制

  • 操作严格限于启动时通过指定的目录 args
  • 所有操作（包括符号链接目标）必须保留在允许的目录内
  • 路径验证可确保在允许的路径之外没有目录遍历或访问

权限标志

  • --只读：强制只读模式，覆盖所有其他权限标志
  • --完全访问：启用所有操作（创建、编辑、移动、删除）
  • 单个权限标志（除非设置了完全访问权限，否则需要显式启用）：
    • --允许创建：允许创建新文件和目录
    • --允许编辑：允许修改现有文件
    • --允许移动：允许移动/重命名文件和目录
    • --允许删除：允许删除文件和目录

默认行为：如果没有指定权限标志，服务器将以只读模式运行。要启用任何写入操作，您必须使用 --full-access 或具体 --allow-* 旗帜。

Symlink处理

  • 默认情况下，当链接和目标都在允许的目录内时，会遵循符号链接
  • --没有关注符号链接：将符号链接视为常规文件，拒绝遍历其目标，防止通过链接路径逃逸

看 examples/mcp_permissions.json 对于使用这些标志的示例配置。

构建

要在本地编译项目，请运行：

bun run build

使用以下命令运行测试套件：

bun test

Docker构建：

docker build -t mcp/filesystem -f Dockerfile .

许可证

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

相关 MCP