# LocalFS MCP Server
A comprehensive filesystem management MCP (Model Context Protocol) server that provides sandboxed access to local filesystem operations. Built with [Smithery CLI](https://smithery.ai/docs/getting_started/quickstart_build_python).
## Features
### 16 Filesystem Tools
#### Directory Operations (5 tools)
- `list_directories` - List subdirectories in a path
- `create_directory` - Create new directories (with parent creation)
- `delete_directory` - Delete directories (recursive option)
- `move_directory` - Move or rename directories
- `get_directory_metadata` - Get directory statistics and info
#### File Operations (6 tools)
- `list_files` - List files in a directory
- `read_file` - Read file content with chunking support
- `write_file` - Write or overwrite files (text and binary)
- `append_file` - Append content to existing files
- `delete_file` - Delete files
- `move_file` - Move or rename files
- `get_file_metadata` - Get file stats (size, mime type, timestamps)
#### Search Operations (5 tools)
- `search_by_name` - Exact filename match
- `search_by_glob` - Glob pattern matching (*.txt, **/*.py)
- `search_by_filename_regex` - Regex pattern on filenames
- `search_by_content_text` - Plain text search in file content
- `search_by_content_regex` - Regex search in file content
### Binary File Support
- Automatic detection of binary vs text files
- Base64 encoding for binary content
- UTF-8 text handling with error recovery
### Performance & Safety
- Chunked file reads for large files (offset/limit support)
- Configurable file size limits
- Configurable search depth limits
- Lazy directory traversal with generators
## Prerequisites
- **Python >= 3.10**
- **Smithery API key**: Get yours at [smithery.ai/account/api-keys](https://smithery.ai/account/api-keys)
## Getting Started
1. Install dependencies:
```bash
uv sync
```
2. Run the development server:
```bash
uv run dev
```
3. Test interactively with the playground:
```bash
uv run playground
```
## Configuration
Each session requires a `root_directory` parameter and supports optional configuration:
```python
root_directory: str # Required - sandbox root path
max_file_size_mb: int = 100 # Optional - max file size for operations
max_search_depth: int = 10 # Optional - max recursion depth for searches
```
### Example Connection URL
```
http://localhost:8081/mcp?root_directory=/path/to/sandbox&max_file_size_mb=100
```
## Usage Examples
### Read a file
```python
# Small file - read all at once
read_file(path="documents/readme.txt")
# Large file - read in chunks
read_file(path="large_file.bin", offset=0, limit=1048576) # First 1MB
```
### Search for files
```python
# Find all Python files
search_by_glob(pattern="**/*.py", recursive=true)
# Find files containing "TODO"
search_by_content_text(query="TODO", path="src", recursive=true)
```
### Directory operations
```python
# Create nested directories
create_directory(path="projects/new_project", create_parents=true)
# List directory contents
list_files(path="projects")
```
## Development
### Project Structure
Your server code is organized in `src/local_filesystem/`:
- `server.py` - Main server setup
- `core/` - Core utilities and exceptions
- `safety.py` - Path validation and sandboxing
- `exceptions.py` - Custom exception classes
- `constants.py` - Configuration constants
- `api/` - API route handlers
- `directory_routes.py` - Directory operation endpoints
- `file_routes.py` - File operation endpoints
- `search_routes.py` - Search operation endpoints
- `services/` - Business logic services
- `directory_service.py` - Directory management
- `file_service.py` - File management
- `search_service.py` - Search capabilities
- `schemas/` - Pydantic models and validation
### Code Quality Tools
The project uses pre-commit hooks to maintain code quality:
- **Black** - Code formatting (line length: 100)
- **Flake8** - Linting and style checking
- **Mypy** - Static type checking
#### Setup Pre-commit Hooks
```bash
# Install dependencies (includes pre-commit tools)
uv sync
# Install pre-commit hooks
uv run pre-commit install
# Run manually on all files
uv run pre-commit run --all-files
```
The hooks will automatically run on `git commit` to ensure code quality.
## Security Features
1. **Sandboxed Operations**: All paths validated against root directory
2. **Size Limits**: Configurable limits prevent resource exhaustion
3. **Depth Limits**: Recursive operations bounded by max_search_depth
4. **Path Traversal Protection**: Prevents access outside sandbox root
## Testing
Run the test suite:
```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/local_filesystem
# Run specific test file
uv run pytest tests/integration/test_file_routes.py
```
## Deploy
Ready to deploy? Push your code to GitHub and deploy to Smithery:
1. Create a new repository at [github.com/new](https://github.com/new)
2. Initialize git and push to GitHub:
```bash
git add .
git commit -m "LocalFS MCP server"
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
git push -u origin main
```
3. Deploy your server to Smithery at [smithery.ai/new](https://smithery.ai/new)
## Resources
- **Documentation**: [smithery.ai/docs](https://smithery.ai/docs)
- **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Community**: [Discord](https://discord.gg/Afd38S5p9A)
