MCP File Operations Server

🚀 MCP File Operations Server

This is an MCP (Meta Computing Protocol) server for file and directory operations. It offers functions such as basic file operations, directory management, and change tracking.

🚀 Quick Start

📦 Installation

• Automatic Installation: Install automatically via Smithery:

  npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude
  

• Manual Installation: Run the following command directly:

  npm install
  

Start the Server

To start the server:

npm start

For development mode (with auto - reload):

npm run dev

✨ Features

Available Tools

Basic File Operations

• copy_file: Copy a file to a new location.
• read_file: Read the content of a file.
• write_file: Write content to a file.
• move_file: Move/rename a file.
• delete_file: Delete a file.
• append_file: Append content to a file.

Directory Operations

• make_directory: Create a directory.
• remove_directory: Delete a directory.
• copy_directory: Recursively copy a directory (with progress reporting).

Monitoring Operations

• watch_directory: Start monitoring directory changes.
• unwatch_directory: Stop monitoring a directory.

Change Tracking

• get_changes: Get the list of recorded changes.
• clear_changes: Clear all change records.

Available Resources

Static Resources

• file:///recent-changes: List of recent file system changes.

Resource Templates

• file://{path}: Access file content.
• metadata://{path}: Access file metadata.
• directory://{path}: List directory content.

💻 Usage Examples

Basic Usage

// Copy a file
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// Monitor a directory
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// Access file content via resource
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// Copy a directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Track progress via the progress token in the result
console.log(result.progressToken);

🔧 Technical Details

Rate Limiting

The server implements rate limiting to prevent abuse:

• Tools: 100 requests per minute.
• Resources: 200 requests per minute.
• Monitoring Operations: 20 operations per minute. Rate - limiting errors contain information about the retry - after period.

Security Features

Path Validation

All file paths are validated to prevent directory traversal attacks:

• Parent directory references (../) are prohibited.
• Paths are properly normalized.
• Input parameters are sanitized.

Resource Protection

• All operations have rate limits.
• There is proper error handling and logging.
• All parameter inputs are validated.
• There is a secure resource cleanup mechanism.

Progress Reporting

Long - running operations (such as directory copying) provide progress updates:

interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}

Track progress via the progress token in the operation result.

Configuration

Basic Configuration

The following options can be set via environment variables or a configuration file:

• PORT: The port the server listens on, default is 3000.
• LOG_LEVEL: Log level, available values are debug, info, warning, error, default is info.
• MAX_FILE_SIZE: The maximum allowed file size, default is 1MB.

Advanced Configuration

• Enable/disable change tracking:

  {
    enableChangeTracking: true // Default is true
  }
  

• Configure the concurrency for directory copying:

  {
    copyConcurrency: 5 // Default concurrency for copy operations is 5
  }
  

Error Handling

Common Errors

1. File Not Found: Thrown when trying to access or operate on a non - existent file.

   Error: File not found
   

2. Permission Denied: Thrown when there is insufficient permission to perform an operation.

   Error: Permission denied
   

3. Directory Traversal Attempt Detected: Blocked when a directory traversal attack is attempted.

   Error: Directory traversal attempt detected
   

Custom Error Handling

You can capture and handle errors by registering a global error handler:

mcp errorHandler(error) {
    console.error('An error occurred:', error);
    // Custom handling logic
}

Logging

Log Format

The default log format is:

[timestamp] - [level] - message

For example:

2023-10-05 12:34:56 - info - File operation completed successfully.

Log Levels

The following log levels are supported:

• debug: Debug information.
• info: General information.
• warning: Warning messages.
• error: Error information.

Performance Optimization

Caching Mechanism

The server has a built - in cache for file operations to improve the efficiency of repeated operations. It is enabled by default.

Parallel Processing

It supports multi - threading and concurrent operations to enhance performance, depending on system load and configuration.

📚 Documentation

FAQ

1. How to view current logs?
   • Use the mcp logs command to view real - time logs.
2. Can I disable change tracking?
   • Yes, you can disable the change tracking function by setting enableChangeTracking: false.
3. Which protocols does the server support?
   • The current version only supports the MCP protocol. More protocol support is planned for future versions.

📄 License

Contributors

• Developer: [Your Name]
• Maintainer: [Project Maintenance Team]

This is the complete documentation for the project, including installation, configuration, usage instructions, and frequently asked questions. If you have any questions or need further assistance, please feel free to contact the project maintenance team.