file-system-mcp-server

# 文件系统 MCP Server 一个强大的文件系统管理服务器，使用 FastMCP 构建，提供了一套全面的文件和目录操作工具。此服务器允许您通过结构化的 API 执行各种文件系统操作，使其成为自动化和与其他系统集成的理想选择。 ## 平台支持 该服务器旨在跨不同的操作系统工作，但功能级别有所不同： ### Windows - 完整功能支持 - 驱动器列表 - 特殊文件夹访问 - Windows 专用路径处理 - 详细的系统信息 ### macOS/Linux - 基本文件操作 - 目录操作 - 文件搜索和元数据 - 基本系统信息 - 注意：某些 Windows 专用功能不可用 ## 未来实施 ### 计划的 macOS 支持 - macOS 的本机路径处理 - macOS 专用系统信息检索 - 与 macOS 文件系统功能集成 - 支持 macOS 专用文件属性 - 实施 macOS 专用实用程序（类似于 windows_utils.py） ### 计划的 Linux 支持 - Linux 的本机路径处理 - Linux 专用系统信息检索 - 与 Linux 文件系统功能集成 - 支持 Linux 文件权限和属性 - 实施 Linux 专用实用程序 ### 跨平台改进 - 统一的路径处理系统 - 平台无关的驱动器检测 - 一致的系统信息 API - 跨平台的标准化文件属性 - 跨平台文件系统事件监视 - 通用文件收集系统 ### 时间线 - 阶段 1：基本跨平台兼容性改进 - 阶段 2：平台特定功能实施 - 阶段 3：高级跨平台功能 - 阶段 4：性能优化和改进 ## 功能 ### 文件操作 - 复制文件，支持备份 - 移动文件，支持备份 - 删除文件，具有安全检查 - 读取文件内容 - 写入文件内容 - 获取文件信息（大小、创建时间、修改时间） - 按名称模式搜索文件 - 创建文件集合以组织相关文件 ### 目录操作 - 列出目录内容 - 创建目录 - 删除目录 - 递归列出目录（树状结构） - 按名称模式搜索目录 ### 系统信息 - 获取系统信息（操作系统、CPU、内存、磁盘使用情况） - 获取磁盘信息（总空间、已用空间、可用空间） - 获取目录信息（文件数、总大小） ## 项目结构 ``` file-system-mcp-server/ ├── fs_server.py # Main server implementation ├── windows_utils.py # Windows-specific utilities (Windows only) ├── requirements.txt # Project dependencies └── test_prompts_example.md # Example test prompts ``` ### 集合存储 集合可以存储在用户指定的任何目录中。如果未指定存储位置，集合将存储在项目 `data/collections` 目录中的默认位置。 用法示例： ```python # Store in default location create_collection("my_collection", ["file1.txt", "file2.txt"]) # Store in custom location create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store") ``` ## 依赖项 ### 必需的依赖项 - FastMCP - Pydantic - pywin32 (Windows only) - WMI (Windows only) 要安装依赖项： ```bash pip install -r requirements.txt ``` ## 设置 1. 克隆存储库： ```bash git clone https://github.com/calebmwelsh/file-system-mcp-server.git cd file-system-mcp-server ``` 2. 创建并激活虚拟环境： ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. 安装依赖项： ```bash pip install -r requirements.txt ``` ## 用法 有关跨不同开发环境（Claude、Cursor、Windsurf）的详细 MCP 配置说明，请访问： [MCP Configuration Guide](https://calebmwelsh.github.io/Configure-MCP/) ### 与 Claude 集成 要将文件系统 MCP server 与 Claude 集成，请将以下内容添加到您的 `claude_desktop_config.json` 文件中： ```json { "mcpServers": { "file-system": { "command": "/absolute/path/to/python", "args": [ "/absolute/path/to/file-system-mcp-server/fs_server.py" ] } } } ``` #### 查找您的 Python 路径 要查找您的 Python 可执行文件路径，请使用以下命令： **Windows (PowerShell):** ```powershell (Get-Command python).Source ``` **Windows (Command Prompt/Terminal):** ```cmd where python ``` **Linux/macOS (Terminal):** ```bash which python ``` 将 `/absolute/path/to/python` 替换为上面相应命令的输出。 #### 配置示例 对于 Windows，您的配置可能如下所示： ```json { "mcpServers": { "file-system": { "command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe", "args": [ "C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py" ] } } } ``` 对于 macOS/Linux： ```json { "mcpServers": { "file-system": { "command": "/usr/local/bin/python3", "args": [ "/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py" ] } } } ``` 添加配置后： 1. 保存 `claude_desktop_config.json` 文件 2. 重新启动 Claude 3. 现在，您可以通过要求 Claude 执行文件操作来使用文件系统工具 ## 可用工具 ### 文件操作 - `copy_file`: 复制文件，带有可选备份 - `move_file`: 移动文件，带有可选备份 - `delete_file`: 删除文件，具有安全检查 - `read_file`: 读取文件内容 - `write_file`: 将内容写入文件 - `get_file_info`: 获取详细的文件信息 - `search_files`: 按名称模式搜索文件 - `create_collection`: 创建文件集合 ### 目录操作 - `list_directory`: 列出目录内容 - `create_directory`: 创建新目录 - `delete_directory`: 删除目录 - `list_directory_recursively`: 以树状格式显示目录结构 - `search_directories`: 按名称模式搜索目录 ### 系统信息 - `get_system_info`: 获取系统信息 - `get_disk_info`: 获取磁盘使用信息 - `get_directory_info`: 获取目录统计信息 ## 已知问题 以下功能目前遇到问题，可能无法按预期工作： 1. **删除文件功能** - `delete_file` 函数在某些情况下可能无法正确删除文件 - 建议用户手动验证文件删除情况，或在关键情况下使用其他方法 - 问题正在调查中，将在未来的更新中修复 2. **列出驱动器功能** - `list_drives` 函数可能无法正确检测或显示所有可用驱动器 - 某些驱动器可能从列表中缺失或显示不正确的信息 - 这是一个已知的限制，将在未来的更新中解决 3. **平台特定限制** - Windows 专用功能在 macOS/Linux 上不可用 - 某些路径处理可能因平台而异 - 系统信息检索因平台而异 ## 错误处理 该服务器包括全面的错误处理，适用于： - 无效的文件路径 - 未找到文件/目录 - 权限问题 - 磁盘空间限制 - 无效操作 - 平台特定错误 ## 安全 - 所有文件操作都包括路径验证 - 在破坏性操作之前创建备份文件 - 系统信息访问仅限于安全操作 - 文件操作在执行时具有适当的错误处理 ## 贡献 1. Fork 存储库 2. 创建一个功能分支 3. 提交您的更改 4. 推送到分支 5. 创建一个 Pull Request ## 许可证 此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。 ## 致谢 - 使用 FastMCP 构建 - 使用 Pydantic 进行数据验证 - 灵感来自现代文件系统管理工具