MCP Server Filesystem

🚀 MCP 文件系统服务器

MCP 文件系统服务器提供了一系列强大的文件操作工具，可与 VSCode 等工具集成，帮助开发者高效地进行文件管理和编辑，同时具备安全特性保障文件和目录结构的安全。

🚀 快速开始

在 Windows 上设置开发环境

REM 克隆仓库
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-filesystem

REM 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\activate

REM 安装依赖项
pip install -e .

REM 安装开发依赖项
pip install -e ".[dev]"

配置说明

要将此服务器与 VSCode 或其他支持 Cline 的工具集成，请按照以下步骤配置：

1. VSCode 集成：
   • 打开 VSCode 并安装 Cline 扩展。
   • 在项目根目录中创建一个 mcp-config.json 文件，并添加以下内容：

{
  "mcp": {
    "servers": [
      {
        "id": "filesystem",
        "class": "mcp_server_filesystem.FileSystemServer",
        "args": {
          "project_dir": "."
        }
      }
    ]
  }
}

2. 启动服务器：
   • 在 VSCode 中，打开终端并运行以下命令：

python src/server.py

✨ 主要特性

• 丰富的文件操作工具：提供了列出目录、读取文件、保存文件、追加文件、删除文件和编辑文件等多种操作。
• 安全可靠：具备文件访问控制和目录结构保护功能，确保文件和目录的安全。
• 易于集成：可与 VSCode 等支持 Cline 的工具集成，方便开发者使用。
• 详细日志：服务器提供详细的日志输出，便于调试和监控运行状态。

📦 安装指南

在 Windows 上设置开发环境的步骤如下：

REM 克隆仓库
git clone https://github.com/MarcusJellinghaus/mcp_server_filesystem.git
cd mcp-server-filesystem

REM 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\activate

REM 安装依赖项
pip install -e .

REM 安装开发依赖项
pip install -e ".[dev]"

💻 使用示例

基础用法

启动服务器：

python src/server.py

使用 VSCode 的 Cline 工具进行交互式测试：

• 打开 Cline 工具。
• 选择 filesystem 服务器并开始会话。

高级用法

单元测试

在项目根目录中运行：

python -m pytest tests/

📚 详细文档

可用工具

该服务器提供了以下 MCP 工具：

工具详情

列出目录

• 返回文件和目录名称的列表。
• 默认情况下，结果会根据 .gitignore 模式过滤，并排除 .git 文件夹。

读取文件

• 参数：file_path（字符串）：要读取的文件路径（相对于项目目录）
• 返回文件内容作为字符串。

保存文件

• 参数：
  • file_path（字符串）：要写入的文件路径
  • content（字符串）：要写入的内容
• 返回布尔值，表示操作是否成功。

追加文件

• 参数：
  • file_path（字符串）：要追加的文件路径
  • content（字符串）：要追加的内容
• 返回布尔值，表示操作是否成功。
• 注意：文件必须已经存在；使用 save_file 创建新文件。

删除文件

• 参数：file_path（字符串）：要删除的文件路径
• 返回布尔值，表示操作是否成功。
• 注意：此操作不可逆，将永久删除文件。

编辑文件

• 参数：
  • file_path（字符串）：要编辑的文件
  • edits（数组）：编辑操作列表，每个操作包含：
    • old_text（字符串）：要替换的文本
    • new_text（字符串）：新的替换文本
  • dry_run（布尔值，可选）：预览更改而不应用
  • options（对象，可选）：格式化设置
• 功能：
  • 支持行范围和文件路径的模式匹配。
  • 支持同时进行多处替换。

🔧 技术细节

安全特性

• 文件访问控制：

  • 仅允许读取、写入和追加操作，严格禁止删除操作。
  • 所有更改都需要显式确认，避免意外修改。

• 目录结构保护：

  • 根目录及其子目录的结构受到保护，防止意外删除或重命名。

开发说明

• 代码结构：

  • 项目基于标准 Python 包结构组织。
  • 主要模块包括 server.py 和 filesystem_server.py。

• 日志与调试：

  • 服务器提供详细日志输出，便于调试和监控运行状态。
  • 可通过配置文件调整日志级别和输出格式。

📄 许可证

本项目遵循 MIT 许可证，允许自由使用、修改和分发。详细许可内容请参考 LICENSE 文件。

通过以上配置与说明，您可以顺利地将 MCP 文件系统服务器集成到开发环境中，并利用其强大的文件操作功能进行高效开发。