Python（MCP）文件系统服务器
此存储库包含一个强大的基于Python的 模型上下文协议（MCP）文件系统服务器它使AI模型和应用程序能够通过一组定义的工具与主机系统的文件目录安全地交互，允许读取、写入、移动和列出文件和目录等操作。
服务器建立在 fastmcp 图书馆坚持 模型上下文协议，为人工智能工具在指定边界内管理和访问文件提供了一种标准化的方法。
它的灵感来自于此 示例排版实现.
______________________________________________________________________
特性
- 安全目录访问： 所有文件操作都严格限制在预定义的允许目录列表中，防止未经授权访问文件系统的其他部分。
- 全面的文件操作：
- read_file：读取单个文本文件的完整内容。 - read_multiple_files：高效地从多个文件中读取内容，返回具有清晰路径引用的结果。 - write_file：创建新文件或用指定内容覆盖现有文件。 - edit_file：对文本文件应用基于行的编辑，并提供模拟运行选项，以Git风格的差异预览更改。 - create_directory：创建新目录，包括嵌套结构，或确保其存在。 - list_directory：获取给定路径中文件和子目录的详细列表。 - directory_tree：生成文件和目录的递归JSON树结构，以获得清晰的层次视图。 - move_file：移动或重命名文件和目录。 - search_files：递归搜索与模式匹配的文件和目录，可选排除模式。 - get_file_info：检索有关文件或目录的详细元数据（大小、时间戳、权限）。
- 动态允许目录： 可通过命令行参数进行配置，以精确指定服务器可以访问的目录。
- 稳健的日志记录： 将全面的日志记录与对不同日志级别和输出的支持相结合
stderr（用于MCP合规性）和可选的旋转日志文件。 - 错误处理： 为常见问题（如拒绝访问、找不到文件或权限错误）提供详细的错误消息。
- 线端标准化： 手柄
\r\n和\n行尾一致edit_file操作。 - Symlink保护： 验证符号链接的真实路径，以防止转义允许的目录。
______________________________________________________________________
入门指南
先决条件
- Python 3.8+：服务器是用现代Python版本开发和测试的。
fastmcp图书馆：此服务器使用fastmcpMCP协议处理库。你需要安装它。
安装
- 克隆存储库：
git clone https://github.com/hypercat/PyMCP-FS.git
cd PyMCP-FS- 使用初始化项目
uv:
uv pip install -r pyproject.toml______________________________________________________________________
用法
运行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运行后，服务器将在其标准输入上监听MCP消息(stdin)并对其标准输出做出响应(stdout).
使用以下工具测试服务器 test_mcp_server.py
这 test_mcp_server.py 脚本是一个用于验证服务器初始化和基本功能的实用程序。它启动了 main.py 服务器作为子进程，发送 initialize MCP消息，并捕获服务器的输出和日志。
uv run test_mcp_server.py此脚本将：
- 创建临时目录(
~/mcp_test)以及其中的测试文件。 - 发射
main.py作为子流程，授予它访问临时目录的权限。 - 发送标准MCP
initialize向服务器发出请求。 - 监控服务器的输出(
stdout,stderr)对于响应和错误。 - 打印服务器的调试日志(
mcp_debug.log)以获取详细的见解。 - 清理临时测试文件和目录。
解释测试输出：
Response: {"jsonrpc": "2.0", "result": {}, "id": 1}：这表示MCP成功initialize来自服务器的响应，确认它正确处理了初始握手。STDOUT/STDERR：任何直接打印的声明或未捕获的例外情况main.py将出现在这里。这是运行时错误的第一站。=== DEBUG LOG CONTENTS ===：提供服务器进程本身的详细日志。查找指示工具注册成功、路径验证以及文件操作过程中任何错误的消息。
______________________________________________________________________
故障排除
如果你遇到问题，这里有一个清单：
- 检查命令行参数：确保您至少提供了一个允许的目录
main.py。没有它们，服务器将无法启动。 fastmcp安装：验证fastmcp库已正确安装(pip install fastmcp).- 权限：确保运行服务器的用户对指定的允许目录和日志文件路径具有读/写权限。
- 检查日志(
mcp_debug.log)：日志文件（尤其是--log-level DEBUG)提供了有关服务器正在做什么以及可能发生故障的最详细信息。 - MCP协议遵守情况：确保您的客户端根据MCP规范发送格式良好的JSON-RPC 2.0消息。服务器希望收到以下消息
stdin并回应stdout. - 路径验证错误：如果您看到“拒绝访问”错误，请仔细检查请求的路径是否严格位于配置的允许目录内。请记住，符号链接目标也会被验证。
edit_file比赛问题：如果edit_file报告“找不到完全匹配”，请验证oldText在您的编辑操作中，与文件中的内容完全匹配，包括空格和行尾。
______________________________________________________________________
扩展服务器
此服务器为文件系统交互提供了坚实的基础。您可以通过以下方式扩展其功能：
- 添加更多工具：实施新
@mcp.tool()用于其他文件系统操作的功能（例如。，copy_file,delete_file,checksum_file). - 与其他系统集成：修改工具以与云存储、数据库或版本控制系统交互，同时仍呈现类似文件系统的界面。
- 自定义验证：增强
validate_path如果需要，可以使用更复杂的访问控制规则。