Skip to main content
Glama
MCP Simple Shell

MCP Simple Shell

by TheWandrr
README.md
# MCP Simple Shell

A workspace-confined file operations server for the Model Context Protocol (MCP). Provides safe, sandboxed file and directory operations with built-in safety features.

## Features

- **File Operations**: Read, write, copy, move, delete, append, rename, touch, stat
- **Directory Operations**: Create, delete, copy, move, rename, list
- **Text Processing**: Replace sections, apply unified diff patches
- **Binary Operations**: Read/write binary, hexdump, find byte patterns, diff binaries
- **Advanced Processing**: UPX unpacking, XOR/AES decryption, YARA scanning, file type detection, firmware carving, entropy analysis, ELF/PE segment splitting
- **SQLite Database**: Create, open, query, schema inspection
- **System Tools**: Cryptographic hashing, PE rebasing, disk usage, server info
- **Trash System**: Protected trash with SHA256 verification for recovery
- **Advisory Locking**: Shared/exclusive file locking for coordination
- **Chunked Upload**: Handle files larger than 64KB tool call limit

## Safety Features

- **No permanent deletion**: All deletions go to protected trash with SHA256 verification
- **Atomic writes**: Temp file + os.replace() for crash-safe writes
- **Symlink protection**: O_NOFOLLOW + lstat() on all path components
- **Path containment**: Workspace-root confinement, no traversal
- **Rate limiting**: 100 ops/sec per session
- **Size limits**: 10MB max file size, 8KB chunk limit for tool calls

## Installation

```bash
# Install Python dependencies
pip install -r requirements.txt

# Install system dependencies (Ubuntu/Debian)
sudo scripts/install_deps.sh
```

## Usage

```bash
# Run the MCP server
python -m mcp_simple_shell.server

# Or use the entry point
mcp-simple-shell
```

The server runs on streamable-http transport by default.

## Tools

### File Operations
- `file_read` - Read text files (with encoding support)
- `file_read_range` - Read specific byte ranges
- `file_write` - Create or overwrite files
- `file_overwrite` - Replace existing files (trash old version)
- `file_append` - Append to files
- `file_rename` - Rename files
- `file_delete` - Move to trash
- `file_copy` - Copy files
- `file_move` - Move/rename files
- `file_diff` - Unified diff between files
- `file_touch` - Create empty file or update mtime
- `file_stat` - Get file metadata

### Directory Operations
- `make_dir` - Create directories
- `delete_dir` - Delete directories (with recursive trash)
- `copy_dir` - Copy directory trees
- `move_dir` - Move directory trees
- `rename_dir` - Rename directories
- `list_dir` - List directory contents
- `file_list` - Recursive listing with filters

### Text Processing
- `file_replace_section` - Exact string replacement
- `file_patch` - Apply unified diff patches

### Binary Operations
- `file_read_binary` - Read raw bytes (hex + ASCII)
- `file_write_binary` - Write raw bytes at offset
- `file_hexdump` - Formatted hex dump
- `file_find_bytes` - Pattern search with wildcards
- `file_diff_binary` - Byte-by-byte comparison

### Advanced Processing
- `file_unpack` - UPX unpacking
- `file_decrypt` - XOR/AES-CBC decryption
- `file_extract_range` - Extract byte ranges
- `file_yara_scan` - YARA rule scanning
- `file_magic` - File type detection (libmagic)
- `file_carve_firmware` - Firmware extraction (binwalk)
- `file_find_embedded` - Entropy-based embedded file detection
- `file_split_segments` - ELF/PE segment splitting

### SQLite
- `sqlite_create_file` - Create database
- `sqlite_open_file` - Open database (read-only option)
- `sqlite_get_catalog` - Full schema catalog
- `sqlite_execute` - Execute SQL
- `sqlite_close` - Close connection
- `sqlite_table_info` - Table column info

### System
- `file_hash` - SHA256/MD5/SHA1/SSDEEP/TLSH
- `file_rebase` - PE image base change
- `disk_usage` - Workspace statistics
- `server_info` - Server configuration

### Trash
- `list_trash` - List trashed files
- `trash_info` - View trash metadata
- `restore_from_trash` - Restore with SHA256 verification

### Locking
- `file_lock` - Acquire advisory lock
- `file_unlock` - Release advisory lock

### Chunked Upload
- `begin_upload` - Start upload session
- `append_chunk` - Append chunk
- `finish_upload` - Finalize upload
- `cancel_upload` - Cancel upload

## Configuration

Workspace root: `./workspace` (created automatically)
Trash directory: `./workspace/.trash` (managed only by trash tools)

## Requirements

- Python 3.10+
- Linux (primary), macOS (limited binary tool support)
- System packages: upx, binwalk, yara, libyara-dev, file, python3-dev, build-essential, libfuzzy-dev

## License

MIT