# MCP File Operations Server

A Python MCP (Model Context Protocol) server that provides read and write access to files in the `documents` subfolder for use with Claude Desktop.

## Features

- **Read files**: Read the contents of any file in the documents folder
- **Write files**: Create or overwrite files in the documents folder
- **List files**: Browse files and directories in the documents folder with search capabilities
- **Delete files/directories**: Remove files or directories from the documents folder
- **Create directories**: Create new directories within the documents folder
- **Security**: Path validation to prevent access outside the documents folder
- **All file types**: Supports all file types without restrictions
- **Search functionality**: Find files using patterns and recursive search

## Installation

### Using Poetry (Recommended)

1. Install Poetry if you haven't already:
   ```bash
   curl -sSL https://install.python-poetry.org | python3 -
   ```

2. Install dependencies:
   ```bash
   poetry install
   ```

3. Activate the virtual environment:
   ```bash
   poetry shell
   ```

### Using pip

1. Install the required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

2. Ensure the `documents` folder exists in your project directory.

## Usage with Claude Desktop

### 1. Add the server to Claude Desktop

1. Open Claude Desktop
2. Go to Settings → MCP Servers
3. Click "Add Server"
4. Configure the server:
   - **Name**: File Operations
   - **Command**: `poetry` (if using Poetry) or `python`
   - **Arguments**: `run run_server.py` (if using Poetry) or `run_server.py` (if using pip)
   - **Working Directory**: Path to your project folder

### 2. Available Tools

Once connected, Claude will have access to these tools:

#### `read_file`
Read the contents of a file from the documents folder.

**Parameters:**
- `file_path` (required): Path to the file relative to the documents folder

**Example:**
```
Read the file "notes.txt" from the documents folder
```

#### `write_file`
Write content to a file in the documents folder.

**Parameters:**
- `file_path` (required): Path to the file relative to the documents folder
- `content` (required): Content to write to the file
- `mode` (optional): Write mode - "w" for overwrite (default), "a" for append

**Example:**
```
Write "Hello World" to a file called "greeting.txt"
```

#### `list_files`
List all files and directories in the documents folder with search capabilities.

**Parameters:**
- `subdirectory` (optional): Specific subdirectory to list files from
- `search_pattern` (optional): Search pattern to filter files (supports wildcards like *.txt, *.py, etc.)
- `recursive` (optional): Whether to search recursively in subdirectories (default: false)

**Examples:**
```
List all files in the documents folder
List all Python files recursively
List all files in the "projects" subdirectory
Search for files matching "*.md" pattern
```

#### `delete_file`
Delete a file or directory from the documents folder.

**Parameters:**
- `file_path` (required): Path to the file or directory relative to the documents folder
- `recursive` (optional): Whether to delete directories recursively (default: false)

**Examples:**
```
Delete the file "old_notes.txt"
Delete the directory "temp_folder" recursively
```

#### `create_directory`
Create a new directory in the documents folder.

**Parameters:**
- `dir_path` (required): Path to the directory relative to the documents folder

**Example:**
```
Create a directory called "projects"
```

## Security Features

- **Path validation**: All file operations are restricted to the `documents` folder
- **Directory traversal protection**: Prevents access to parent directories
- **All file types supported**: No restrictions on file extensions
- **Error handling**: Comprehensive error messages for debugging

## Supported File Types

The server supports **all file types** without any restrictions. You can read, write, and manage any file format including:
- Text files (.txt, .md, .py, .js, .html, .css, etc.)
- Data files (.json, .csv, .xml, .yaml, etc.)
- Binary files (.pdf, .doc, .xls, .zip, etc.)
- Images (.jpg, .png, .gif, etc.)
- And any other file type

## Testing the Server

### Using Poetry

You can test the server using Poetry:

```bash
# Run the server directly
poetry run python run_server.py

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=mcp_file_server
```

### Using pip

You can test the server manually by running:

```bash
python run_server.py
```

The server will start and wait for MCP protocol messages on stdin/stdout.

## Troubleshooting

### Common Issues

1. **Import errors**: Make sure you've installed the requirements:
   ```bash
   # Using Poetry
   poetry install
   
   # Using pip
   pip install -r requirements.txt
   ```

2. **Permission errors**: Ensure the `documents` folder has write permissions

3. **Path issues**: The server automatically creates the `documents` folder if it doesn't exist

4. **Claude Desktop connection**: Make sure the working directory in Claude Desktop settings points to your project folder

5. **Poetry not found**: Install Poetry using the official installer:
   ```bash
   curl -sSL https://install.python-poetry.org | python3 -
   ```

### Logging

The server includes logging to help debug issues. Check the console output for error messages.

## Development

### Using Poetry

To modify the server:

1. Edit `mcp_file_server/server.py` to add new tools or modify existing ones
2. Modify the `DOCUMENTS_DIR` constant to change the base directory
3. All file types are supported by default - no need to modify file type restrictions
4. Run tests: `poetry run pytest`
5. Format code: `poetry run black .`
6. Sort imports: `poetry run isort .`

### Using pip

To modify the server:

1. Edit `mcp_file_server/server.py` to add new tools or modify existing ones
2. Modify the `DOCUMENTS_DIR` constant to change the base directory
3. All file types are supported by default - no need to modify file type restrictions

## License

This project is open source and available under the MIT License.