README.md•5.15 kB
# 文件管理器 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 协议支持