# 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