# filesystem-mcp-rust

**Repository Path**: awol2010ex/filesystem-mcp-rust

## Basic Information

- **Project Name**: filesystem-mcp-rust
- **Description**: A Model Context Protocol (MCP) server for advanced filesystem operations with  file handling capabilities
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-18
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Filesystem MCP Server

A Model Context Protocol (MCP) server for advanced filesystem operations with large file handling capabilities.

模型上下文协议 (MCP) 文件系统服务器，支持高级文件操作和大文件处理功能。

**Current Version: 0.0.2** | **当前版本：0.0.2**

## ⚠️ Important Notice for v0.0.2 | v0.0.2重要通知

**Breaking Change**: This version enforces **absolute paths only** for all file operations. Relative paths are no longer supported to enhance security.
**破坏性变更**：本版本强制要求所有文件操作必须使用**绝对路径**。不再支持相对路径以增强安全性。

## Features | 功能特点

- **Advanced File Operations**: Read, write, delete, copy, move files with encoding support
- **Directory Management**: List, create, search directories recursively
- **Large File Support**: Sequential reading with offset and limit parameters
- **Security**: Path validation and allowed directories whitelist
- **Metadata**: File information including size, permissions, mime type, SHA-256 hash
- **Multiple Encodings**: Text and base64 encoding support
- **MCP Protocol**: Full JSON-RPC compliance for Claude Desktop integration

- **高级文件操作**: 支持读取、写入、删除、复制、移动文件，支持多种编码
- **目录管理**: 递归列出、创建、搜索目录
- **大文件支持**: 支持偏移量和限制参数的序列化读取
- **安全性**: 路径验证和允许目录白名单
- **元数据**: 文件信息包括大小、权限、MIME类型、SHA-256哈希
- **多种编码**: 支持文本和base64编码
- **MCP协议**: 完全符合JSON-RPC协议，支持Claude Desktop集成

## Installation | 安装

### Prerequisites | 前置要求

- Rust 1.70+ (install from [rustup.rs](https://rustup.rs/))
- Claude Desktop (for MCP integration)

### Build from Source | 从源码构建

```bash
# Clone the repository
# 克隆仓库
git clone https://gitee.com/awol2010ex/filesystem-mcp-rust.git
cd filesystem-mcp-rust

# Build the project
# 构建项目
cargo build --release

# Install locally
# 本地安装
cargo install --path .
```

## Usage | 使用方法

### Basic Usage | 基本用法

```bash
# Run the server
# 运行服务器
./target/release/filesystem-mcp-rust

# Or if installed via cargo install
# 或者通过cargo install安装后
filesystem-mcp-rust
```

### Configuration | 配置

**⚠️ Important**: All paths must be absolute paths. Relative paths are not supported in v0.0.2+
**⚠️ 重要**：所有路径必须是绝对路径。v0.0.2+版本不支持相对路径

The server accepts configuration through command line arguments:

服务器接受通过命令行参数进行配置：

```bash
# Set allowed directories (semicolon-separated)
# 设置允许的目录（分号分隔）
filesystem-mcp-rust /home/user/documents;/home/user/projects

# Use current directory (default)
# 使用当前目录（默认）
filesystem-mcp-rust

# Single directory
# 单个目录
filesystem-mcp-rust /home/user/workspaces
```

**Note**: The `CREATE_BACKUP_FILES` feature is automatically enabled for write operations to prevent accidental data loss.
**注意**：`CREATE_BACKUP_FILES` 功能在写入操作时会自动启用，以防止意外数据丢失。

### MCP Integration | MCP集成

#### Install in Trae | 在Trae中安装

1. **Build and install the MCP server**
   **构建并安装MCP服务器**
   ```bash
   # Build the project
   # 构建项目
   cargo build --release
   
   # Install the binary
   # 安装二进制文件
   cargo install --path .
   ```

2. **Configure in Trae settings.json**
   **在Trae的settings.json中配置**
   
   Add the filesystem MCP server to your Trae `settings.json` configuration:
   将文件系统MCP服务器添加到您的Trae `settings.json` 配置中：
   
   ```json
   {
     "mcpServers": {
         "filesystem-mcp-rust": {
           "command": "filesystem-mcp-rust",
           "args": ["E:/workspaces"]
         }
       
     }
   }
   ```
   
   **Note**: Use absolute paths in the arguments. Example for Windows: `E:/workspaces`, for Linux/macOS: `/home/user/workspaces`
   **注意**：在参数中使用绝对路径。Windows示例：`E:/workspaces`，Linux/macOS示例：`/home/user/workspaces`
   
   For multiple directories, use semicolon-separated paths:
    对于多个目录，使用分号分隔的路径：
    ```json
    {
      "mcp": {
        "servers": {
          "filesystem": {
            "command": "filesystem-mcp-rust",
            "args": ["/home/user/workspaces;/home/user/projects"]
          }
        }
      }
    }
    ```
    
    **Note**: The `settings.json` file is typically located in your Trae configuration directory. You can access it through Trae's command palette (Ctrl+Shift+P) and searching for "Preferences: Open Settings (JSON)".
    **注意**：`settings.json` 文件通常位于您的Trae配置目录中。您可以通过Trae的命令面板（Ctrl+Shift+P）搜索"首选项：打开设置(JSON)"来访问它。

3. **Verify installation**
   **验证安装**
   
   The filesystem operations should now be available in Trae's MCP tools.
   文件系统操作现在应该在Trae的MCP工具中可用。

## Testing | 测试

### Run Tests | 运行测试

```bash
# Run all tests
# 运行所有测试
cargo test

# Run tests with output
# 运行测试并显示输出
cargo test -- --nocapture

# Run specific test
# 运行特定测试
cargo test test_read_file
```

### Integration Testing | 集成测试

```bash
# Test basic file operations
# 测试基本文件操作
echo "test content" > test_file.txt
./target/release/filesystem-mcp-rust  # Start server in one terminal
# Then test MCP requests in another terminal
```

## Development | 开发

### Development Build | 开发构建

```bash
# Build for development
# 开发构建
cargo build

# Build with fast profile
# 使用快速配置文件构建
cargo build --profile fast
```

### Code Quality | 代码质量

```bash
# Format code
# 格式化代码
cargo fmt

# Run linter
# 运行 linter
cargo clippy

# Check for security vulnerabilities
# 检查安全漏洞
cargo audit
```

## API Reference | API参考

### Supported Operations | 支持的操作

- `read_file` - Read file content with optional offset and limit
- `write_file` - Write content to file with encoding support
- `delete_file` - Delete file or directory
- `list_directory` - List directory contents
- `search_files` - Search files by name or content
- `create_directory` - Create new directory
- `copy_file` - Copy file to new location
- `move_file` - Move file to new location
- `get_file_info` - Get detailed file information
- `get_disk_usage` - Get disk usage statistics

- `read_file` - 读取文件内容，支持偏移量和限制
- `write_file` - 写入文件内容，支持编码
- `delete_file` - 删除文件或目录
- `list_directory` - 列出目录内容
- `search_files` - 按名称或内容搜索文件
- `create_directory` - 创建新目录
- `copy_file` - 复制文件到新位置
- `move_file` - 移动文件到新位置
- `get_file_info` - 获取详细的文件信息
- `get_disk_usage` - 获取磁盘使用统计

## Security | 安全

- Path traversal protection
- Allowed directories whitelist
- File permission validation
- Safe encoding handling

- 路径遍历保护
- 允许目录白名单
- 文件权限验证
- 安全编码处理

## Performance | 性能

- Optimized for large files with sequential reading
- Efficient directory traversal
- Minimal memory footprint for streaming operations
- Async I/O with Tokio

- 针对大文件的序列化读取优化
- 高效的目录遍历
- 流操作的最小内存占用
- 使用Tokio的异步I/O

## Contributing | 贡献

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交拉取请求

## License | 许可证

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

本项目采用 Apache License 2.0 许可证 - 详见 [LICENSE](LICENSE) 文件。

## Changelog | 更新日志

### Version 0.0.2 (2025-12-19)
**版本 0.0.2 (2025年12月19日)**

#### Security Enhancement | 安全增强
- **Breaking Change**: Enforced absolute path requirement for all file operations
- **破坏性变更**: 强制所有文件操作必须使用绝对路径
- **Security**: Disabled relative path support to prevent path traversal attacks
- **安全性**: 禁用相对路径支持以防止路径遍历攻击

#### Changes | 变更
- All file operations now require absolute paths only
- 所有文件操作现在仅支持绝对路径
- Relative paths will be rejected with clear error message
- 相对路径将被拒绝并显示明确的错误信息

#### Impact | 影响
- Existing configurations using relative paths need to be updated
- 使用相对路径的现有配置需要更新
- Migration required for all MCP client configurations
- 需要迁移所有MCP客户端配置

### Version 0.0.1 (Initial Release)
**版本 0.0.1 (初始版本)**

#### Features | 功能
- Basic filesystem operations (read, write, delete, copy, move)
- 基本文件系统操作（读取、写入、删除、复制、移动）
- Directory management (list, create, search)
- 目录管理（列出、创建、搜索）
- Large file support with streaming
- 支持大文件流式处理
- Multiple encoding support (UTF-8, base64)
- 多种编码支持（UTF-8、base64）
- Full MCP protocol compliance
- 完全符合MCP协议
- Path validation and security features
- 路径验证和安全功能

## Support | 支持

For issues and questions:
- Create an issue on Gitee: https://gitee.com/awol2010ex/filesystem-mcp-rust/issues
- Contact: awol2005ex@163.com

对于问题和疑问：
- 在Gitee上创建问题：https://gitee.com/awol2010ex/filesystem-mcp-rust/issues
- 联系：awol2005ex@163.com