# File Operations MCP Server

A Model Context Protocol (MCP) server that provides comprehensive file system operations using FastMCP. This server allows AI assistants to safely interact with the file system through a well-defined set of tools.

## Features

The server provides the following file operations:

### File Operations
- **read_file**: Read the contents of a file
- **write_file**: Write content to a file (creates directories as needed)
- **append_file**: Append content to an existing file
- **delete_file**: Delete a file
- **copy_file**: Copy a file from source to destination
- **move_file**: Move a file from source to destination

### Directory Operations
- **list_directory**: List contents of a directory with file sizes
- **create_directory**: Create a directory (including parent directories)
- **delete_directory**: Delete a directory and all its contents

### Information & Search
- **get_file_info**: Get detailed information about a file or directory
- **find_files**: Find files matching a pattern in a directory

## Installation

### 🚀 Quick Setup (Recommended)

1. Clone this repository:
```bash
git clone <repository-url>
cd your-first-mcp-server
```

2. Run the setup script:

**Linux/macOS:**
```bash
./setup.sh
```

**Windows (PowerShell):**
```powershell
.\setup.ps1
```

The setup script will:
- Create a virtual environment
- Install all dependencies
- Configure Claude Desktop automatically
- Create run scripts for easy server management
- Test the installation

3. **Restart Claude Desktop** to load the new configuration

That's it! The server should now be available in Claude Desktop.

### 📋 Manual Installation

If you prefer to install manually:

#### Option 1: Using pip (with virtual environment - recommended)
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
```

#### Option 2: Using pip (system-wide)
```bash
pip install -r requirements.txt
```

#### Option 3: Using setup.py (development install)
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
```

## Usage

### Running the Server

#### If you used the setup script:
```bash
# Linux/macOS
./run_server.sh           # Regular server
./test_tools.sh           # Run automated tests
./test_tools.sh --interactive  # Interactive testing

# Windows
.\run_server.bat          # Regular server
.\test_tools.bat          # Run automated tests
.\test_tools.bat --interactive  # Interactive testing
```

#### Manual start:
```bash
# If using virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate
python main.py

# If installed system-wide
python main.py
```

#### If you installed using setup.py:
```bash
file-operations-server
```

The server will start and listen for MCP connections.

### Using with Claude Desktop

#### If you used the setup script:
**The Claude Desktop configuration is already set up!** Just restart Claude Desktop and the server will be available.

#### Manual Configuration:
If you installed manually, you need to configure Claude Desktop:

1. **Copy the example config**: Use the provided `claude_desktop_config.json` file as a starting point
2. **Update the path**: Edit the file to replace `/absolute/path/to/your-first-mcp-server/main.py` with the actual absolute path to your server file
3. **Copy to Claude config location**: Copy the updated config to your Claude Desktop configuration directory

#### Quick Manual Setup:
```bash
# Copy the example config
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Edit the path in the config file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

#### Example configuration:
```json
{
  "mcpServers": {
    "file-operations": {
      "command": "python",
      "args": ["/Users/yourusername/your-first-mcp-server/main.py"]
    }
  }
}
```

**Note**: Make sure to use the absolute path to your `main.py` file.

### Configuration File Location

The `claude_desktop_config.json` file is typically located at:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

## Tool Reference

### read_file(path: str) -> str
Reads and returns the contents of a file.

**Parameters:**
- `path`: Path to the file to read

**Returns:** File contents as a string, or error message if file cannot be read.

### write_file(path: str, content: str) -> str
Writes content to a file, creating directories as needed.

**Parameters:**
- `path`: Path to the file to write
- `content`: Content to write to the file

**Returns:** Success message or error message.

### append_file(path: str, content: str) -> str
Appends content to an existing file.

**Parameters:**
- `path`: Path to the file to append to
- `content`: Content to append

**Returns:** Success message or error message.

### list_directory(path: str = ".") -> str
Lists the contents of a directory with file sizes and type indicators.

**Parameters:**
- `path`: Directory path (defaults to current directory)

**Returns:** Formatted list of directory contents with 📁 for directories and 📄 for files.

### create_directory(path: str) -> str
Creates a directory, including any necessary parent directories.

**Parameters:**
- `path`: Directory path to create

**Returns:** Success message or error message.

### delete_file(path: str) -> str
Deletes a file.

**Parameters:**
- `path`: Path to the file to delete

**Returns:** Success message or error message.

### delete_directory(path: str) -> str
Deletes a directory and all its contents.

**Parameters:**
- `path`: Directory path to delete

**Returns:** Success message or error message.

### copy_file(source: str, destination: str) -> str
Copies a file from source to destination.

**Parameters:**
- `source`: Source file path
- `destination`: Destination file path

**Returns:** Success message or error message.

### move_file(source: str, destination: str) -> str
Moves a file from source to destination.

**Parameters:**
- `source`: Source file path
- `destination`: Destination file path

**Returns:** Success message or error message.

### get_file_info(path: str) -> str
Gets detailed information about a file or directory.

**Parameters:**
- `path`: Path to the file or directory

**Returns:** Formatted information including type, size, modification time, and permissions.

### find_files(directory: str = ".", pattern: str = "*") -> str
Finds files matching a pattern in a directory.

**Parameters:**
- `directory`: Directory to search in (defaults to current directory)
- `pattern`: Glob pattern to match (defaults to "*")

**Returns:** List of matching files and directories.

## Error Handling

All tools include comprehensive error handling for common scenarios:
- File not found
- Permission denied
- Invalid paths
- Directory vs file mismatches

Errors are returned as descriptive strings rather than exceptions, making them safe for AI assistant use.

## Security Considerations

This server provides full file system access within the permissions of the running process. When deploying:

1. Run with minimal necessary permissions
2. Consider sandboxing the server process
3. Monitor file system access patterns
4. Implement additional access controls as needed for your use case

## Development

### Testing

To test the server functionality:

```bash
# Test basic functionality
python -c "
from main import *
print(list_directory('.'))
print(write_file('test.txt', 'Hello, World!'))
print(read_file('test.txt'))
print(delete_file('test.txt'))
"
```

### Adding New Tools

To add new file operations:

1. Define a new function with the `@mcp.tool()` decorator
2. Add appropriate error handling
3. Return descriptive success/error messages
4. Update this documentation

## License

This project is provided as-is for educational and development purposes.