File System MCP Server

# File System MCP Server A Model Context Protocol server that provides safe file system operations with built-in safeguards, backup mechanisms, and comprehensive error handling. ## Features - **Safe file reading** with metadata extraction and binary file detection - **File creation** with overwrite protection and automatic directory creation - **File updates** with automatic backup creation and rollback on failure - **Directory listing** with filtering, pattern matching, and recursive traversal - **Safe file deletion** with backup recovery (moves to backup instead of permanent deletion) - **Comprehensive error handling** with structured error responses and recovery suggestions - **Security safeguards** with protected path checking and file size limits - **Configurable logging** with structured logging and file rotation ## Installation ### From Source ```bash # Clone the repository git clone <repository-url> cd file-system-mcp-server # Install in development mode pip install -e . # Or install with development dependencies pip install -e ".[dev]" ``` ### Dependencies The server requires Python 3.8+ and the following packages: - `mcp` - Model Context Protocol implementation - `python-magic` - MIME type detection - `aiofiles` - Async file operations ## Quick Start 1. **Create example configuration:** ```bash file-system-mcp-server --create-example-config config.json ``` 2. **Validate configuration:** ```bash file-system-mcp-server --validate-config --config config.json ``` 3. **Start the server:** ```bash file-system-mcp-server --config config.json ``` ## Configuration ### Configuration File The server uses a JSON configuration file with the following options: ```json { "backup_directory": "./.mcp_backups", "max_file_size": 10485760, "max_recursion_depth": 10, "allowed_extensions": null, "protected_paths": ["/etc", "/usr", "/bin", "/System"], "enable_backups": true, "log_level": "INFO" } ``` ### Configuration Options - **`backup_directory`**: Directory where backup files are stored (default: `./.mcp_backups`) - **`max_file_size`**: Maximum file size for read operations in bytes (default: 10MB) - **`max_recursion_depth`**: Maximum depth for recursive directory listing (default: 10) - **`allowed_extensions`**: List of allowed file extensions, or `null` for all (default: `null`) - **`protected_paths`**: List of paths that cannot be modified (default: system directories) - **`enable_backups`**: Whether to create backups before destructive operations (default: `true`) - **`log_level`**: Logging level - DEBUG, INFO, WARNING, ERROR, CRITICAL (default: `INFO`) ### Kiro Integration To use with Kiro, add the server to your MCP configuration: ```json { "mcpServers": { "file-system-operations": { "command": "file-system-mcp-server", "args": ["--config", "config.json"], "disabled": false, "autoApprove": ["read_file", "get_file_info", "list_directory"] } } } ``` ## Available Tools ### `read_file` Read file contents with metadata extraction. **Parameters:** - `path` (string): Path to the file to read **Features:** - Binary file detection - Encoding detection and handling - File metadata (size, permissions, timestamps) - MIME type detection ### `write_file` Create a new file with content. **Parameters:** - `path` (string): Path where the file should be created - `content` (string): Content to write to the file - `overwrite` (boolean, optional): Whether to overwrite existing file **Features:** - Automatic directory creation - Overwrite protection - Backup creation for existing files - File extension validation ### `update_file` Update an existing file with automatic backup. **Parameters:** - `path` (string): Path to the file to update - `content` (string): New content for the file **Features:** - Automatic backup creation - Rollback on failure - File existence validation ### `list_directory` List directory contents with filtering options. **Parameters:** - `path` (string): Path to the directory to list - `pattern` (string, optional): Glob pattern to filter files (e.g., `*.py`, `test_*`) - `recursive` (boolean, optional): Whether to list recursively **Features:** - Pattern matching with glob syntax - Recursive traversal with depth limits - File metadata for each entry - Entry counting and filtering statistics ### `delete_file` Safely delete a file or directory with backup. **Parameters:** - `path` (string): Path to the file or directory to delete **Features:** - Moves to backup instead of permanent deletion - Directory deletion support - Protected path checking - File count reporting ### `get_file_info` Get detailed metadata about a file or directory. **Parameters:** - `path` (string): Path to the file or directory **Features:** - Comprehensive metadata (size, timestamps, permissions) - MIME type detection - Existence checking - Owner/group information (Unix systems) ## Security Features ### Protected Paths The server prevents operations on system-critical directories: - `/etc`, `/usr`, `/bin`, `/sbin` (Unix/Linux) - `/System` (macOS) - `C:\Windows`, `C:\Program Files` (Windows) ### File Size Limits Read operations are limited by the `max_file_size` configuration to prevent resource exhaustion. ### Path Validation All paths are resolved and validated to prevent directory traversal attacks. ### Backup System Destructive operations create timestamped backups before making changes, allowing for recovery. ## Command Line Interface ```bash file-system-mcp-server [OPTIONS] Options: -c, --config PATH Path to configuration file --log-level LEVEL Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) --log-file PATH Path to log file --validate-config Validate configuration and exit --create-example-config PATH Create example configuration file and exit --version Show version and exit --help Show help message ``` ### Examples ```bash # Run with default configuration file-system-mcp-server # Run with custom config and debug logging file-system-mcp-server --config my-config.json --log-level DEBUG # Log to file file-system-mcp-server --log-file server.log # Create example configuration file-system-mcp-server --create-example-config my-config.json # Validate configuration file-system-mcp-server --validate-config --config my-config.json ``` ## Development ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=src --cov-report=html # Run specific test file pytest tests/unit/test_config.py ``` ### Code Formatting ```bash # Format code black src tests # Sort imports isort src tests # Type checking mypy src ``` ### Project Structure ``` file-system-mcp-server/ ├── src/file_system_mcp_server/ │ ├── __init__.py │ ├── main.py # CLI entry point │ ├── server.py # MCP server implementation │ ├── config.py # Configuration management │ ├── safety.py # Security and backup management │ ├── file_operations.py # Core file operations │ ├── models.py # Data models and result types │ └── logging_config.py # Logging configuration ├── tests/ │ ├── unit/ # Unit tests │ ├── integration/ # Integration tests │ └── fixtures/ # Test fixtures ├── config/ │ ├── example.json # Example configuration │ └── kiro-mcp.json # Kiro MCP configuration ├── pyproject.toml # Project configuration └── README.md ``` ## Error Handling The server provides structured error responses with: - **Error type classification** (SecurityError, FileNotFound, etc.) - **Detailed error messages** with context - **Recovery suggestions** for common issues - **Structured logging** for debugging Example error response: ```json { "success": false, "error": { "error_type": "FileNotFound", "message": "File does not exist: /path/to/file.txt", "recovery_suggestions": [ "Check the file path", "Ensure the file exists" ] } } ``` ## Troubleshooting ### Common Issues 1. **Permission Denied** - Check file/directory permissions - Ensure the server has appropriate access rights - Verify the path is not in protected directories 2. **File Too Large** - Increase `max_file_size` in configuration - Use streaming for large files (future enhancement) 3. **Backup Directory Issues** - Ensure backup directory is writable - Check disk space availability - Verify backup directory path in configuration 4. **MIME Type Detection Fails** - Install `python-magic` system dependencies - Falls back to file extension-based detection ### Logging Enable debug logging for detailed operation information: ```bash file-system-mcp-server --log-level DEBUG --log-file debug.log ``` ## License MIT License - see LICENSE file for details. ## 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 ## Changelog ### v0.1.0 - Initial release - Core file operations (read, write, update, delete, list) - Safety and backup system - MCP server implementation - Configuration management - Comprehensive error handling