# 文件管理器 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. **克隆项目**
   ```bash
   git clone <repository-url>
   cd mcpDevelop
   ```

2. **创建虚拟环境**
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # Linux/Mac
   # 或
   venv\Scripts\activate     # Windows
   ```

3. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

## 使用方法

### 启动服务器

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

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

### 在 AI 客户端中配置

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

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

## 工具使用示例

### 1. 列出目录内容

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

### 2. 读取文件

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

### 3. 创建文件

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

### 4. 删除文件

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

### 5. 搜索文件

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

### 6. 复制文件

```json
{
  "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               # 项目文档
```

## 开发和测试

### 运行测试

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

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

### 调试模式

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

```bash
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 协议支持