mcp file operations server

Local 2025-08-31 23:30:52 0

File Systems @bsmi021/mcp-file-operations-server

A Model Context Protocol server that enables enhanced file system operations including reading, writing, copying, moving files with streaming capabilities, directory management, file watching, and change tracking.

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

Installing via Smithery

To install File Operations Server for Claude Desktop automatically 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 (with progress reporting)

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

Available Resources

Static Resources

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

Resource Templates

file://{path}: Access file contents
metadata://{path}: Access file metadata
directory://{path}: List directory contents

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
});

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

// Copy directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Progress token in result can be used to track progress
console.log(result.progressToken);

Rate Limits

The server implements rate limiting to prevent abuse:

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

Rate limit errors include a retry-after period in the error message.

Security Features

Path Validation

All file paths are validated to prevent directory traversal attacks:

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
Safe resource cleanup

Progress Reporting

Long-running operations like directory copying provide progress updates:

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

Progress can be tracked through the progress token returned in the operation result.

Development

Building

npm run build

Linting

npm run lint

Formatting

npm run format

Testing

npm test

Configuration

The server can be configured through various settings:

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

The server provides detailed error information through the FileOperationError class and MCP error codes:

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
Resource access errors

Each error includes:

Specific error code
Detailed error message
Relevant metadata (file paths, limits, etc.)
Stack traces in development mode

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

[
  {
    "description": "Copy a file to a new location",
    "inputSchema": {
      "properties": {
        "destination": {
          "description": "Destination file path",
          "type": "string"
        },
        "overwrite": {
          "default": false,
          "description": "Whether to overwrite existing file",
          "type": "boolean"
        },
        "source": {
          "description": "Source file path",
          "type": "string"
        }
      },
      "required": [
        "source",
        "destination"
      ],
      "type": "object"
    },
    "name": "copy_file"
  },
  {
    "description": "Read the contents of a file",
    "inputSchema": {
      "properties": {
        "encoding": {
          "default": "utf8",
          "description": "File encoding (default: utf8)",
          "type": "string"
        },
        "path": {
          "description": "Path to the file to read",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "read_file"
  },
  {
    "description": "Write content to a file",
    "inputSchema": {
      "properties": {
        "content": {
          "description": "Content to write to the file",
          "type": "string"
        },
        "encoding": {
          "default": "utf8",
          "description": "File encoding (default: utf8)",
          "type": "string"
        },
        "path": {
          "description": "Path to write the file to",
          "type": "string"
        }
      },
      "required": [
        "path",
        "content"
      ],
      "type": "object"
    },
    "name": "write_file"
  },
  {
    "description": "Create a new directory",
    "inputSchema": {
      "properties": {
        "path": {
          "description": "Path to create the directory at",
          "type": "string"
        },
        "recursive": {
          "default": true,
          "description": "Create parent directories if they Do not exist",
          "type": "boolean"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "make_directory"
  },
  {
    "description": "Remove a directory",
    "inputSchema": {
      "properties": {
        "path": {
          "description": "Path to the directory to remove",
          "type": "string"
        },
        "recursive": {
          "default": false,
          "description": "Remove directory contents recursively",
          "type": "boolean"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "remove_directory"
  },
  {
    "description": "List contents of a directory with detailed metadata",
    "inputSchema": {
      "properties": {
        "path": {
          "description": "Path of directory to list",
          "type": "string"
        },
        "recursive": {
          "default": false,
          "description": "Whether to list contents recursively",
          "type": "boolean"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "list_directory"
  },
  {
    "description": "Copy a directory and its contents to a new location",
    "inputSchema": {
      "properties": {
        "destination": {
          "description": "Destination directory path",
          "type": "string"
        },
        "overwrite": {
          "default": false,
          "description": "Whether to overwrite existing files/directories",
          "type": "boolean"
        },
        "source": {
          "description": "Source directory path",
          "type": "string"
        }
      },
      "required": [
        "source",
        "destination"
      ],
      "type": "object"
    },
    "name": "copy_directory"
  },
  {
    "description": "Watch a directory for changes",
    "inputSchema": {
      "properties": {
        "path": {
          "description": "Path to the directory to watch",
          "type": "string"
        },
        "recursive": {
          "default": false,
          "description": "Watch subdirectories recursively",
          "type": "boolean"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "watch_directory"
  },
  {
    "description": "Stop watching a directory",
    "inputSchema": {
      "properties": {
        "path": {
          "description": "Path to the directory to stop watching",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "unwatch_directory"
  },
  {
    "description": "Check if a path is currently being watched",
    "inputSchema": {
      "properties": {
        "path": {
          "description": "Path to check",
          "type": "string"
        }
      },
      "required": [
        "path"
      ],
      "type": "object"
    },
    "name": "is_watching"
  },
  {
    "description": "Get list of tracked changes",
    "inputSchema": {
      "properties": {
        "limit": {
          "description": "Maximum number of changes to return",
          "type": "number"
        },
        "type": {
          "description": "Filter changes by type",
          "type": "string"
        }
      },
      "type": "object"
    },
    "name": "get_changes"
  },
  {
    "description": "Clear all tracked changes",
    "inputSchema": {
      "properties": {},
      "type": "object"
    },
    "name": "clear_changes"
  }
]