关键词

文件系统访问AI助手文件管理上下文协议工具服务器

使用说明

项目简介

Filesystem MCP Server 是一个基于 Model Context Protocol (MCP) 标准构建的服务器，旨在为 AI agent 提供安全且平台无关的文件系统交互能力。它允许 AI agent 通过标准化的 MCP 协议，读取、写入、更新和管理本地文件系统中的文件和目录。

主要功能点

  • 全面的文件操作：提供读取、写入、列出、删除、移动和复制文件及目录的工具。
  • 精准的文件更新：'update_file' 工具支持在文件中进行查找和替换操作，支持纯文本和正则表达式。
  • 会话感知路径管理：'set_filesystem_default' 工具允许为会话设置默认工作目录，简化相对路径的使用。
  • 安全保障：内置路径清理机制，防止目录遍历攻击。可选的基础目录限制进一步增强安全性。
  • 生产级基础：基于 TypeScript 构建，包含完善的日志记录、错误处理和请求追踪机制。

安装步骤

  1. 克隆仓库: 
    git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server
  2. 安装依赖: 
    npm install
  3. 构建项目: 
    npm run build
    构建完成后，可执行文件位于 'dist/index.js'。

服务器配置

MCP 客户端需要配置以下信息以连接到 Filesystem MCP Server。以下是一个 JSON 格式的配置示例，请根据实际情况修改路径：

{
  "serverName": "filesystem",  // 服务器名称，客户端用于标识
  "command": "node",         // 启动服务器的命令
  "args": [                   // 命令参数
    "/path/to/filesystem-mcp-server/dist/index.js"  // 指向构建后的服务器主文件
  ],
  "env": {                     // 环境变量（可选）
    "FS_BASE_DIRECTORY": "/path/to/base/directory",  // (推荐配置) 限制文件操作的基础目录，提升安全性
    "LOG_LEVEL": "info"          // (可选) 日志级别，默认为 info
  },
  "disabled": false,          // 是否禁用该服务器，默认为 false
  "autoApprove": []           // 自动批准的工具列表（可选）
}

参数说明:

  • 'serverName': 自定义服务器名称，在客户端配置中用于标识和引用。
  • 'command': 启动服务器进程的命令，通常为 'node'。
  • 'args': 传递给启动命令的参数，务必将 '/path/to/filesystem-mcp-server/dist/index.js' 替换为服务器可执行文件的实际绝对路径。
  • 'env': 环境变量配置（可选）。
    • 'FS_BASE_DIRECTORY': 强烈推荐配置。设置后，服务器的所有文件操作将被限制在这个目录及其子目录内，增强安全性。请替换 '/path/to/base/directory' 为您希望限制的实际目录的绝对路径。
    • 'LOG_LEVEL': 设置日志输出级别，可选值包括 'error', 'warn', 'info', 'http', 'verbose', 'debug', 'silly'。 默认为 'info'。
  • 'disabled': 设置为 'true' 可以禁用该服务器，默认为 'false'。
  • 'autoApprove': 一个字符串数组，包含需要自动批准的工具名称。留空表示需要手动批准。

基本使用方法

  1. 启动服务器: 在终端中，进入仓库根目录，执行以下命令启动服务器：

    npm start

    或

    node dist/index.js

    服务器成功启动后，将等待 MCP 客户端的连接和请求。

  2. 配置 MCP 客户端: 在您的 MCP 客户端 (如 AI 助手) 中，按照客户端的配置方式，添加上面提供的服务器配置信息。请确保 'args' 数组中的路径指向您服务器 'dist/index.js' 文件的绝对路径。

  3. 使用文件系统工具: 客户端成功连接服务器后，即可使用服务器提供的文件系统工具，例如 'read_file', 'write_file', 'list_files' 等，与本地文件系统进行交互。具体工具及其使用方法请参考 "可用工具" 章节。

可用工具

| 工具 | 描述 | | :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 'set_filesystem_default' | 设置当前会话的默认绝对路径。后续工具调用中使用的相对路径将以此默认路径为基准进行解析。服务器重启后重置。 | | 'read_file' | 读取指定文件的全部内容，以 UTF-8 文本形式返回。接受相对路径（相对于默认路径解析）或绝对路径。 | | 'write_file' | 将内容写入指定文件。如果文件不存在，则创建文件（以及必要的父目录）；如果文件已存在，则覆盖文件。接受相对路径或绝对路径。 | | 'update_file' | 对现有文件执行定向的查找和替换操作，使用 '{search, replace}' 块数组。适用于局部修改。支持纯文本或正则表达式搜索 ('useRegex: true')，以及替换所有匹配项 ('replaceAll: true')。接受相对路径或绝对路径。文件必须已存在。 | | 'list_files' | 列出指定路径中的文件和目录。选项包括递归列出 ('includeNested: true') 和限制条目数量 ('maxEntries')。返回格式化的树状结构。接受相对路径或绝对路径。 | | 'delete_file' | 永久删除指定文件。接受相对路径或绝对路径。 | | 'delete_directory' | 永久删除指定目录。使用 'recursive: true' 删除非空目录及其内容（谨慎使用！）。接受相对路径或绝对路径。 | | 'create_directory' | 在指定路径创建新目录。默认情况下 ('create_parents: true')，还会创建任何必要的父目录。接受相对路径或绝对路径。 | | 'move_path' | 移动或重命名文件或目录，从源路径到目标路径。源路径和目标路径均接受相对路径或绝对路径。 | | 'copy_path' | 复制文件或目录，从源路径到目标路径。对于目录，默认情况下递归复制 ('recursive: true')。源路径和目标路径均接受相对路径或绝对路径。 |

信息

分类

数据库与文件

访问项目