文件管理器 MCP 服务器

一个基于 Model Context Protocol (MCP) 的文件管理服务器，为 AI 助手提供安全的文件系统操作能力。

功能特性

核心工具

1. list_directory - 列出目录内容

   • 显示文件和子目录
   • 可选显示隐藏文件
   • 显示文件大小信息

2. read_file - 读取文件内容

   • 支持多种编码格式
   • 文件大小限制（10MB）
   • 自动检测二进制文件

3. create_file - 创建新文件

   • 自动创建父目录
   • 防止覆盖现有文件
   • 支持自定义编码

4. delete_file - 删除文件或目录

   • 安全删除确认
   • 支持递归删除目录
   • 权限检查

5. search_files - 搜索文件

   • 支持通配符模式
   • 递归搜索选项
   • 显示匹配结果统计

6. copy_files - 复制文件

   • 支持单个或多个文件复制
   • 自动创建目标文件夹
   • 可选择是否覆盖已存在文件
   • 详细的操作结果报告

安全特性

• 参数验证: 严格的输入参数验证
• 路径安全: 防止路径遍历攻击
• 权限控制: 尊重文件系统权限
• 错误处理: 详细的错误信息和日志记录
• 文件大小限制: 防止处理过大文件

安装和设置

环境要求

• Python 3.8+
• pip 或 pipenv

安装步骤

1. 克隆项目

   git clone <repository-url>
   cd mcpDevelop
   

2. 创建虚拟环境

   python3 -m venv venv
   source venv/bin/activate  # Linux/Mac
   # 或
   venv\Scripts\activate     # Windows
   

3. 安装依赖

   pip install -r requirements.txt
   

使用方法

启动服务器

# 方法1: 直接运行主文件
python main.py

# 方法2: 作为模块运行
python -m file_manager_mcp.server

在 AI 客户端中配置

将以下配置添加到你的 MCP 客户端配置文件中：

{
  "mcpServers": {
    "file-manager": {
      "command": "python",
      "args": ["/path/to/mcpDevelop/main.py"]
    }
  }
}

工具使用示例

1. 列出目录内容

{
  "name": "list_directory",
  "arguments": {
    "path": "/home/user/documents",
    "show_hidden": false
  }
}

2. 读取文件

{
  "name": "read_file",
  "arguments": {
    "path": "/home/user/example.txt",
    "encoding": "utf-8"
  }
}

3. 创建文件

{
  "name": "create_file",
  "arguments": {
    "path": "/home/user/new_file.txt",
    "content": "Hello, World!",
    "encoding": "utf-8"
  }
}

4. 删除文件

{
  "name": "delete_file",
  "arguments": {
    "path": "/home/user/old_file.txt",
    "recursive": false
  }
}

5. 搜索文件

{
  "name": "search_files",
  "arguments": {
    "directory": "/home/user/projects",
    "pattern": "*.py",
    "recursive": true
  }
}

6. 复制文件

{
  "name": "copy_files",
  "arguments": {
    "source_paths": ["/home/user/file1.txt", "/home/user/file2.txt"],
    "destination_folder": "/home/user/backup",
    "overwrite": false
  }
}

项目结构

mcpDevelop/
├── file_manager_mcp/
│   ├── __init__.py          # 包初始化
│   ├── server.py            # MCP 服务器主程序
│   ├── tools.py             # 工具实现
│   └── validators.py        # 参数验证和错误处理
├── main.py                  # 入口文件
├── requirements.txt         # Python 依赖
├── pyproject.toml          # 项目配置
└── README.md               # 项目文档

开发和测试

运行测试

# 激活虚拟环境
source venv/bin/activate

# 运行基本功能测试
python -c "import file_manager_mcp.tools; print('导入成功')"

调试模式

设置环境变量启用详细日志：

export PYTHONPATH=.
export MCP_LOG_LEVEL=DEBUG
python main.py

安全注意事项

1. 文件系统访问: 此服务器可以访问运行用户权限范围内的所有文件
2. 路径验证: 已实现路径遍历攻击防护
3. 文件大小限制: 读取和创建文件有大小限制
4. 权限检查: 尊重操作系统的文件权限设置

故障排除

常见问题

1. 权限错误

   • 确保运行用户有足够的文件系统权限
   • 检查目标文件/目录的权限设置

2. 编码错误

   • 确认文件编码格式
   • 尝试使用不同的编码参数

3. 路径错误

   • 使用绝对路径
   • 确认路径存在且格式正确

日志查看

服务器会输出详细的日志信息，包括：

• 工具调用记录
• 错误信息
• 参数验证结果

贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

更新日志

v0.1.1

• 新增 copy_files 工具
• 支持单个或多个文件复制到目标文件夹
• 增强文件操作功能覆盖范围

v0.1.0

• 初始版本
• 实现 5 个核心文件操作工具
• 添加参数验证和错误处理
• 完整的 MCP 协议支持