Python (MCP) Filesystem Server

Python（MCP）文件系统服务

此仓库包含一个健壮的 Python 版 Model Context Protocol（MCP）文件系统服务。它使 AI 模型和应用程序能够通过一组定义好的工具，安全地与主机系统的文件目录交互，执行读取、写入、移动和列出文件及目录等操作。

此服务基于 fastmcp 库构建，并遵循 Model Context Protocol，为 AI 工具在指定边界内管理和访问文件提供标准化方式。

它的灵感来自这个 TypeScript 示例实现。

---

功能

• 安全的目录访问： 所有文件操作都严格限制在预先指定的允许目录列表中，防止未经授权地访问文件系统的其他部分。
• 全面的文件操作：
  • read_file：读取单个 UTF-8 文本文件的完整内容。对于二进制文件等无效 UTF-8 文件，会报告错误，而不会返回乱码。
  • read_multiple_files：高效读取多个文件的内容，并返回带有清晰路径引用的结果。
  • write_file：创建新文件，或使用指定内容覆盖现有文件。
  • edit_file：对文本文件应用基于行的编辑，并可通过 Git 风格的差异预览更改。
  • create_directory：创建新目录（包括嵌套目录），或确保目录存在。
  • list_directory：获取指定路径下文件和子目录的详细列表。
  • directory_tree：递归生成文件和目录的 JSON 树状结构，清晰展示层级关系。
  • move_file：移动或重命名文件和目录。若目标位置已存在，则拒绝覆盖。
  • search_files：递归搜索与模式匹配的文件和目录，并可指定排除模式。
  • get_file_info：获取文件或目录的详细元数据（大小、时间戳、权限）。在 Linux 上，报告的创建时间是 inode 更改时间，这是该平台唯一提供的时间信息。
• 动态配置允许的目录： 可通过命令行参数配置服务能够访问的具体目录。
• 健壮的日志记录： 集成全面的日志记录功能，支持不同日志级别，并可输出到 stderr（符合 MCP 要求）以及可选的轮换日志文件。
• 错误处理： 针对访问被拒绝、文件不存在或权限错误等常见问题，提供详细的错误消息。
• 换行符规范化： 在 edit_file 操作中一致处理 \r\n 和 \n 换行符。
• 路径规范化： 在检查路径是否位于允许范围内之前，会解析请求路径和允许的目录。因此，符号链接、.. 路径段和 Windows 8.3 短文件名既无法逃出允许的目录树，也不会导致其中合法的路径被错误拒绝。

---

开始使用

前置条件

• Python 3.10+：与 pyproject.toml 中的 requires-python 一致。CI 会在 Linux 和 Windows 上测试 3.10、3.12 和 3.13。
• fastmcp 库：此服务使用 fastmcp 库处理 MCP 协议。你需要安装该库。

安装

1. 克隆仓库：

   git clone https://github.com/hypercat/PyMCP-FS.git
   cd PyMCP-FS
   

2. 使用 uv 安装依赖：

   uv sync
   

   此命令会根据 uv.lock 安装，因此你获得的版本与 CI 测试所用版本相同。添加 --no-dev 可跳过测试工具的安装。

---

用法

运行 MCP 服务（main.py）

MCP 服务需要通过命令行参数接收允许访问的目录列表。它只会在指定路径范围内运行。

python3 main.py -d /path/to/allowed/dir1 /path/to/another/allowed/dir2 --log-level INFO --log-file mcp_server.log

参数：

• -d、--directories：（必填） 服务允许访问的一个或多个目录路径。可以指定多个目录。
• --log-file：（可选） 用于写入服务日志的文件路径。日志会轮转，以防文件过大。
• --log-level：（可选） 要输出的最低日志级别。可选值为 DEBUG、INFO、WARNING、ERROR。默认为 INFO。

示例：

若要允许服务访问主目录下的 projects 文件夹和一个临时 data 文件夹：

uv run main.py -d ~/projects /tmp/data --log-level DEBUG --log-file mcp_debug.log

服务启动后，会通过标准输入（stdin）接收 MCP 消息，并通过标准输出（stdout）进行响应。

运行测试

测试套件涵盖路径验证与限制、文件操作辅助函数、 MCP 工具函数和服务启动。

uv sync
uv run pytest

tests/test_path_confinement.py 专门测试允许目录边界， 包括同级目录前缀和别名目录的情况。

test_mcp_server.py 既是集成检查，也是调试辅助工具。它会将 main.py 作为子进程启动，通过标准输入/输出执行 MCP initialize 握手， 并验证响应。单独运行该测试，即可查看完整的交互过程：

uv run test_mcp_server.py

CI 会在 Linux 和 Windows 上，使用 Python 3.10、3.12 和 3.13 运行完整测试套件。 只有所有任务均通过，拉取请求才能合并。

---

故障排除

如果遇到问题，请按以下清单检查：

1. 检查命令行参数：确保为 main.py 提供至少一个允许访问的目录。否则服务无法启动。
2. 依赖项：确认环境与锁文件保持同步（uv sync）。
3. 权限：确保运行服务的用户对指定的允许访问目录和日志文件路径拥有读写权限。
4. 检查日志（mcp_debug.log）：日志文件（尤其是使用 --log-level DEBUG 时）会详细记录服务的运行情况以及可能发生故障的位置。
5. 遵循 MCP 协议：确保客户端按照 MCP 规范发送格式正确的 JSON-RPC 2.0 消息。服务通过 stdin 接收消息，并通过 stdout 进行响应。
6. 路径验证错误：如果看到“Access denied”错误，请确认请求的路径严格位于配置的允许访问目录内。路径会在完全解析后进行比较，因此符号链接会按其目标判断，而不是按链接所在位置判断。
7. edit_file 匹配问题：如果 edit_file 报告“Could not find exact match”，请确认编辑操作中的 oldText 与文件内容完全一致，包括空白字符和换行符。

---

安全

所有文件操作都被限制在通过 --directories 传入的目录内。 进行包含性检查前，请求路径和允许访问的目录都会被完全解析，因此无法利用符号链接、.. 路径段或 Windows 8.3 短文件名越出允许的目录树。

本项目关注的安全属性就是这种路径限制。如果你发现绕过此限制的方法，请私下报告，而不要提交 issue。报告渠道和范围请参阅 SECURITY.md。

安全边界的严格程度取决于你允许访问的范围。将服务指向敏感目录或 /，就意味着连接的模型获得对该目录的全部访问权限。

---

扩展服务

此服务为文件系统交互提供了坚实的基础。你可以通过以下方式扩展其功能：

• 添加更多工具：为其他文件系统操作实现新的 @mcp.tool() 函数（例如 copy_file、delete_file、checksum_file）。
• 与其他系统集成：修改工具以与云存储、数据库或版本控制系统交互，同时仍提供类似文件系统的接口。
• 自定义验证：如有需要，可为 validate_path 函数添加更复杂的访问控制规则。

---

许可证

根据 BSD Zero Clause License（0BSD）发布，这是 Open Source Initiative 批准的最宽松许可证。你可以出于任何目的使用、修改和再分发此软件，无需保留版权声明或附带许可证文本。