AI导哈

文件系统MCP服务器

一个基于MCP协议的文件系统操作服务器，提供创建、读取、写入、编辑、移动、复制和删除文件的功能，并通过工作区沙盒确保操作安全。

  • by Jalalkhan912
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jalalkhan912/file_mcp_server

使用说明

最小文件系统MCP服务器

fs_server.py 是一个简单但功能强大的服务器，它将文件系统操作（创建、读取、写入、编辑、移动、复制、删除）作为 MCP（基于消息的通信协议） 服务。它的设计非常强调通过工作区沙盒的安全性，确保所有操作都限制在指定的根目录中。

此服务器还包括一个直接HTTP端点，用于从工作区提供静态文件，这为需要直接文件访问的场景（例如，用于提供web资产或查看生成的文件）提供了便利。

特性

  • 工作区沙盒：所有文件系统操作都严格限制在可配置的根目录中，防止未经授权访问系统的其他部分。
  • 交互式工作区选择：启动时，服务器智能地确定工作区根：
    1. 优先考虑 FS_WORKSPACE 环境变量。
    2. 尝试使用图形文件夹选择器（Tkinter）进行用户友好的选择。
    3. 回到控制台提示，进行基于文本的交互式选择。
    4. 如果没有交互式选择其他选项，则使用当前工作目录作为默认目录。
  • 全面的文件系统工具：通过MCP接口显示一组丰富的操作：
    • workspace_root()：返回当前工作区根的绝对路径。
    • make_dir(path, parents, exist_ok)：创建新目录。
    • list_dir(path, recursive, pattern)：列出目录的内容，包括递归和glob模式的选项。
    • read_text(path, encoding, max_bytes)：读取文本文件的内容，有截断限制。
    • write_text(path, content, overwrite, create_dirs, encoding)：将内容写入文本文件，并提供覆盖和创建父目录的选项。
    • append_text(path, content, create_dirs, encoding)：将内容附加到现有文件（如果缺少，则创建它）。
    • replace_text(path, pattern, replacement, regex, count, encoding)：在文本文件中执行搜索和替换，支持文字和正则表达式模式。
    • move_path(src, dest, overwrite)：移动或重命名文件或目录。
    • copy_path(src, dest, overwrite)：复制文件或目录。
    • delete_path(path, recursive)：删除文件或整个目录（如果 recursive 是真的）。
    • read_json(path)：读取并解析JSON文件。
    • write_json(path, data, overwrite, create_dirs, indent)：将Python字典作为JSON写入文件。
  • 直接文件访问HTTP端点：工作区中的文件可以直接通过以下方式提供 http://0.0.0.0:8765/files/{path:path}，允许轻松访问静态资产或生成的内容。
  • 基于现代Python Web堆栈构建：利用 Starlette 对于web应用程序和 Uvicorn 作为ASGI服务器，确保高性能和健壮性。

设置和安装

  1. 先决条件:

    • Python 3.7+
    • （GUI选择可选） tkinter （通常包含在Python中或可通过以下方式安装 sudo apt-get install python3-tk 在Debian/Ubuntu上）。

  2. 克隆存储库（如果适用）:

    git clone <Jalalkhan912/File_MCP_Server>
cd <File_MCP_Server>

  3. 再进行:

    pip install fastmcp starlette uvicorn

用法

  1. 运行服务器: 直接执行Python脚本。

    python fs_server.py

  2. 工作空间选择: 运行后，如果出现以下情况，服务器将提示您选择工作区目录 FS_WORKSPACE 未设置环境变量。

    • 环境变量：设置 FS_WORKSPACE 在运行脚本之前，请将其添加到所需的根路径：
      export FS_WORKSPACE="/path/to/your/workspace"
python fs_server.py
    • GUI选择：如果 tkinter 如果可用，将出现一个文件对话框，让您选择一个目录。
    • 控制台提示：如果无法或取消GUI选择，您可以在控制台中键入路径。

  3. 访问服务器: 启动后，服务器将监听 http://0.0.0.0:8765.

    • 健康检查: 您可以在以下网址检查服务器的运行状况 http://0.0.0.0:8765/healthz。它应该返回“ok”。

    • MCP工具: MCP工具可通过SSE（服务器发送事件）端点访问，通常由MCP客户端使用。基本SSE端点为 http://0.0.0.0:8765/sse. （注意：与MCP工具的交互需要MCP客户端库或兼容系统。）

    • 直接文件访问: 要直接从所选工作区访问文件，请使用 /files/ 终点。例如，如果您的工作区是 /home/user/my_project 你有一个文件 /home/user/my_project/data/report.txt，您可以在以下网址访问它： http://0.0.0.0:8765/files/data/report.txt

开发/高级使用

您还可以使用以下命令运行服务器 uvicorn 直接用于更多控制，包括用于开发的热重新加载：

uvicorn --app-dir . fs_server:app --host 0.0.0.0 --port 8765 --reload --log-level debug

（注意：如果您从重命名文件 fs_server_n8n.py 向 fs_server.py，相应地调整命令。)

安全考虑

主要的安全机制是工作区沙盒。至关重要的是 FS_WORKSPACE 仔细选择目录，因为通过MCP工具执行的任何操作都将仅限于此目录。与此服务器交互的用户应该明白，它的功能仅限于指定的工作区。

相关 MCP