# Secure File System MCP Server

A production-grade Model Context Protocol (MCP) server that exposes safe file system operations with comprehensive security guardrails.

## Features

- **File Operations**: `read_file`, `write_file`, `list_dir`, `search_files`
- **Path Traversal Protection**: Blocks `../` attacks and symlink escapes
- **Allowlisted Root Directories**: Only configured directories are accessible
- **File Size Limits**: Configurable maximum file sizes for reads and writes
- **Proper MCP Error Codes**: Returns `-32602` (invalid params) and `-32603` (internal error) instead of raw exceptions
- **Structured Logging**: JSON-formatted logs with correlation IDs
- **Encoding Handling**: Safe handling of text encodings with fallback
- **Comprehensive Tests**: Unit tests with mocked FS + integration tests with MCP client

## Quick Start

### Installation

```bash
pip install -e ".[dev]"
```

### Configuration

Create a `.env` file or set environment variables:

```env
SECURE_FS_ALLOWED_ROOTS=/path/to/dir1,/path/to/dir2
SECURE_FS_MAX_FILE_SIZE=10485760
SECURE_FS_DEFAULT_ENCODING=utf-8
SECURE_FS_LOG_LEVEL=INFO
```

### Running the Server

```bash
python -m secure_fs_mcp.server
```

### Running Tests

```bash
pytest
pytest --cov=secure_fs_mcp
```

## Architecture

```
secure_fs_mcp/
├── __init__.py
├── server.py          # MCP server setup and tool registration
├── config.py          # Configuration management via env vars
├── fs_operations.py   # Core file system operations with safety rails
├── errors.py          # MCP error codes and custom exceptions
├── logging_config.py  # Structured logging setup
└── validators.py      # Input validation and path safety checks
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `read_file` | Read file contents with encoding detection |
| `write_file` | Write content to a file (within allowed roots) |
| `list_dir` | List directory contents with metadata |
| `search_files` | Search for files by name pattern |

## Security

- All paths are resolved to absolute paths and validated against allowlisted roots
- Symlinks are resolved before validation to prevent symlink-based escapes
- Path components are checked for traversal patterns (`..`, `~`)
- File size is checked before reading to prevent memory exhaustion
- Write operations enforce size limits

## License

MIT