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

# 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:

   file-system-mcp-server --create-example-config config.json
   

2. Validate configuration:

   file-system-mcp-server --validate-config --config config.json
   

3. Start the server:

   file-system-mcp-server --config config.json
   

Configuration

Configuration File

The server uses a JSON configuration file with the following options:

{
  "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:

{
  "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

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

# 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

# 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

# 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:

{
  "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:

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