关键词

文件系统本地文件LLM工具代码编辑文件管理

项目简介

'filesystem-mcp-rs' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 客户端提供对本地文件系统的安全访问和操作能力。它是官方 JavaScript 文件系统 MCP 服务器的 Rust 移植版本，在保持协议兼容性的同时，提升了性能和安全性，并加强了路径保护机制。

主要功能点

  • 文件内容管理:
    • 'read_text_file': 读取文本文件的完整内容，也可指定读取头部或尾部的N行。
    • 'read_media_file': 读取图片或音频等多媒体文件，并以 Base64 编码和 MIME 类型返回。
    • 'read_multiple_files': 同时读取多个文件，即使部分文件读取失败也不会中断其他文件的读取。
    • 'write_file': 创建新文件或覆盖现有文件，写入指定内容。
  • 高级文件编辑:
    • 'edit_file': 对文件内容进行文本查找替换式编辑，支持“干运行”预览差异。
    • 'edit_lines': 基于行号进行精确的、外科手术式编辑（替换行、在行前/后插入、删除行或行范围），支持“干运行”预览差异。适用于已知精确修改位置的场景。
    • 'bulk_edits': 对多个符合特定模式的文件批量进行相同的文本查找替换操作，高效地在整个代码库中重构、修复或更新内容，支持“干运行”预览差异。
  • 文件系统操作:
    • 'create_directory': 创建目录（包括任何缺失的父目录）。
    • 'move_file': 移动或重命名文件/目录，若目标已存在则失败。
    • 'copy_file': 复制文件或目录到新位置，可选择是否覆盖现有目标。
    • 'delete_path': 删除文件，或在指定 'recursive=true' 时递归删除目录。
  • 文件系统信息与搜索:
    • 'list_directory': 列出目录中的文件和子目录。
    • 'list_directory_with_sizes': 列出目录内容并显示文件大小，支持按名称或大小排序。
    • 'directory_tree': 递归生成目录结构树（JSON 格式），支持排除特定文件/目录模式。
    • 'search_files': 根据 Glob 模式递归搜索文件路径，可指定排除模式。
    • 'grep_files': 像 'grep' 或 'ripgrep' 一样，在文件内容中用正则表达式搜索文本，支持大小写不敏感、上下文行和文件过滤。
    • 'get_file_info': 获取文件或目录的元数据，如大小、创建/修改时间、权限等。
    • 'list_allowed_directories': 列出当前服务器被授权访问的所有目录。
  • 安全性: 通过“允许目录列表”（allowlist）机制严格控制服务器可操作的文件系统范围，提供路径安全检查，并可选支持符号链接逃逸。

安装步骤

  1. 确保 Rust 环境已安装: 如果未安装，请访问 rustup.rs 官网进行安装。
  2. 克隆仓库: 打开终端或命令行工具，执行以下命令： 
    git clone https://github.com/ssoj13/filesystem-mcp-rs.git
cd filesystem-mcp-rs
  3. 编译项目: 在仓库根目录执行编译命令。 
    cargo build --release
    编译成功后，可执行文件通常位于 'target/release/filesystem-mcp-rs' (Linux/macOS) 或 'target\release\filesystem-mcp-rs.exe' (Windows)。
  4. 可选：全局安装: 如果您希望在系统的任何位置都能直接运行此服务器，可以执行： 
    cargo install --path .
    这会将可执行文件安装到 Rust 的 bin 目录，使其可以在全局范围内调用。

服务器配置

MCP 客户端（如 Claude Code、Codex）需要配置 'filesystem-mcp-rs' 服务器的启动命令及其参数才能建立连接。以下是配置 MCP 服务器的关键信息和参数说明：

  • Server Name (服务器名称): 通常命名为 'filesystem' 或其他您易于识别的名称。客户端会通过这个名称引用您的服务器。

  • Command (命令): 您的 'filesystem-mcp-rs' 可执行文件的完整路径。

    • 如果您已全局安装，可以直接使用 'filesystem-mcp-rs'。
    • 否则，需要指定完整路径，例如：'"/path/to/filesystem-mcp-rs/target/release/filesystem-mcp-rs"' (Linux/macOS) 或 '"C:/Users/YourUser/path/to/filesystem-mcp-rs/target/release/filesystem-mcp-rs.exe"' (Windows)。

  • Args (参数):

    • 允许访问的目录: 必须提供一个或多个您希望 LLM 客户端能访问的目录路径。例如：'"/home/user/my_project"'、'"/tmp"'、'"C:/work"'。这些目录定义了服务器的操作边界，超出这些目录的请求将被拒绝。
    • '--allow-symlink-escape': 这是一个可选参数，用于允许符号链接指向允许目录之外的目标。默认为了安全性是禁用的。
    • '--stream' 或 '-s': 这是一个可选参数，用于启用 HTTP 流模式，主要用于远程访问、Web 集成和云部署。如果未指定，服务器将使用 Stdio 模式（适用于本地 MCP 客户端）。
    • '--port <PORT>' 或 '-p <PORT>': (仅限 HTTP 模式) 可选参数，用于指定 HTTP 服务器监听的端口。默认值为 '8000'。
    • '--bind <ADDR>' 或 '-b <ADDR>': (仅限 HTTP 模式) 可选参数，用于指定 HTTP 服务器绑定的 IP 地址。默认值为 '127.0.0.1'。
    • '--log [<FILE>]' 或 '-l [<FILE>]': 这是一个可选参数，用于启用日志文件输出。您可以选择性地指定日志文件的名称（例如 'my_server.log'），默认文件名为 'filesystem-mcp-rs.log'。在 Stdio 模式下，除非明确启用此日志选项，否则服务器不会向标准错误输出任何信息，以避免干扰客户端通信。

    请注意:

    • 您需要在实际使用的 MCP 客户端中找到对应的配置界面或配置文件（例如 '~/.config/claude-code/config.json' 或 '~/.codex/config.toml'），按照其要求填入上述信息。
    • Windows 用户在指定目录路径时，建议使用正斜杠 ('/') 或双反斜杠 ('\')，具体取决于客户端的配置格式。

基本使用方法

  1. 启动服务器:
    • Stdio 模式 (适用于本地 MCP 客户端，默认): 
      # 允许访问 /my_project 和 /tmp 目录
filesystem-mcp-rs /my_project /tmp
# 允许访问 C:\Users\user\Documents\MyProject (Windows 示例)
filesystem-mcp-rs "C:/Users/user/Documents/MyProject"
    • HTTP 模式 (适用于远程访问或 Web 集成): 
      # 启动 HTTP 服务器在 0.0.0.0:8000，并允许访问 /projects 目录
filesystem-mcp-rs -s -b 0.0.0.0 -p 8000 /projects
  2. 连接 MCP 客户端: 根据您使用的 MCP 客户端（如 Claude Code、Codex 等），在其配置中添加上述服务器信息（Server Name, Command, Args）。客户端会自动与您启动的 'filesystem-mcp-rs' 服务器建立连接。
  3. LLM 交互: 一旦连接成功，您的 LLM 客户端即可通过此服务器提供的文件系统工具，安全地在您允许访问的本地文件系统中进行读取、写入、编辑、搜索和管理操作。例如，LLM 可能会调用 'read_text_file' 来查看代码文件，或调用 'write_file' 来修改配置文件，甚至调用 'grep_files' 在整个项目中搜索特定代码模式。

信息

分类

数据库与文件

访问项目