MCP HubMCP Hub
bsmi021

mcp-file-operations-server

by: bsmi021

mcp file operations server

9created 31/12/2024
Visit
file
operations

📌Overview

Purpose: To provide an advanced server framework that enhances file operations with capabilities such as streaming, patching, and change tracking.

Overview: The File Operations MCP Server facilitates efficient management of file system operations, allowing users to perform multiple file and directory tasks while ensuring robust error handling, security, and real-time progress reporting. Its design caters to both basic and complex operations that are essential for modern file management needs.

Key Features:

  • Basic File Operations: Support for essential file manipulations like copy, read, write, move, and delete, which streamline daily tasks.

  • File Watching: Real-time monitoring of files and directories to track changes, enhancing responsiveness to system modifications.

  • Change Tracking: Ability to track and query the history of file operations, providing users with a comprehensive overview of changes and actions performed.

  • Streaming Support: Efficient handling of large files without the need for extensive resources, allowing for smoother operations.

  • Enhanced Security: Built-in path validation and input sanitization techniques safeguard against potential vulnerabilities and attacks.

File Operations MCP Server

A Model Context Protocol (MCP) server that provides enhanced file operation capabilities with streaming, patching, and change tracking support.

Features

  • Basic File Operations: Copy, read, write, move, and delete files
  • Directory Operations: Create, remove, and copy directories
  • File Watching: Monitor files and directories for changes
  • Change Tracking: Track and query file operation history
  • Streaming Support: Handle large files efficiently with streaming
  • Resource Support: Access files and directories through MCP resources
  • Progress Reporting: Real-time progress updates for long operations
  • Rate Limiting: Protection against excessive requests
  • Enhanced Security: Path validation and input sanitization
  • Robust Error Handling: Comprehensive error handling and reporting
  • Type Safety: Full TypeScript support with strict type checking

Installation

Install via Smithery

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

Manual Installation

npm install

Usage

Starting the Server

npm start

For development with auto-reloading:

npm run dev

Available Tools

Basic File Operations

  • copy_file: Copy a file to a new location
  • read_file: Read content from 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: Remove a directory
  • copy_directory: Copy a directory recursively

Watch Operations

  • watch_directory: Start watching a directory for changes
  • unwatch_directory: Stop watching a directory

Change Tracking

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

Example Usage

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

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

Rate Limits

  • Tools: 100 requests per minute
  • Resources: 200 requests per minute
  • Watch Operations: 20 operations per minute

Security Features

Path Validation

  • No parent directory references (../)
  • Proper path normalization
  • Input sanitization

Resource Protection

  • Rate limiting on all operations
  • Proper error handling and logging
  • Input validation on all parameters

Development

Building

npm run build

Linting

npm run lint

Formatting

npm run format

Testing

npm test

Configuration

  • Rate Limiting: Configure request limits and windows
  • Progress Reporting: Control update frequency and detail level
  • Resource Access: Configure resource permissions and limits
  • Security Settings: Configure path validation rules
  • Change Tracking: Set retention periods and storage options
  • Watch Settings: Configure debounce times and recursive watching

Error Handling

Standard MCP Error Codes

  • InvalidRequest: Invalid parameters or request format
  • MethodNotFound: Unknown tool or resource requested
  • InvalidParams: Invalid parameters (e.g., path validation failure)
  • InternalError: Server-side errors

Custom Error Types

  • File operation failures
  • Rate limit exceeded
  • Path validation errors

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License.