npm package: @iflow-mcp/bsmi021-file-operations-server
Description: MCP server for file operations with enhanced capabilities
Author: Brian W. Smith
Latest version: 1.0.0

# File Operations MCP Server

[![smithery badge](https://smithery.ai/badge/@bsmi021/mcp-file-operations-server)](https://smithery.ai/server/@bsmi021/mcp-file-operations-server)

A Model Context Protocol (MCP) server that provides enhanced file operation capabilities with streaming, patching, and change tracking support.

<a href="https://glama.ai/mcp/servers/7b750si00d">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/7b750si00d/badge" alt="File Operations Server MCP server" />
</a>

## Features

- **Basic File Operations**: Copy, read, write, move, and delete files
- **Directory Operations**: Create, remove, and copy directories
- **File Watching**: Monitor files and directories for changes
- **Change Tracking**: Track and query file operation history
- **Streaming Support**: Handle large files efficiently with streaming
- **HTTP Interface**: Streamable HTTP interface with Server-Sent Events (SSE)
- **Resource Support**: Access files and directories through MCP resources
- **Progress Reporting**: Real-time progress updates for long operations
- **Rate Limiting**: Protection against excessive requests
- **Enhanced Security**: Path validation and input sanitization
- **Robust Error Handling**: Comprehensive error handling and reporting
- **Type Safety**: Full TypeScript support with strict type checking
- **Docker Support**: Containerized deployment with volume mounting

## Installation

### Installing via Smithery

To install File Operations Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@bsmi021/mcp-file-operations-server):

```bash
npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude
```

### Manual Installation
```bash
npm install
```

### Docker Installation

See [DOCKER.md](./DOCKER.md) for comprehensive Docker setup instructions including local drive mounting for Windows and Linux.

**Quick Docker Start:**
```bash
# Stdio transport (for MCP clients)
docker run -it --rm -v "$(pwd):/workspace" ghcr.io/bsmi021/mcp-file-operations-server

# HTTP transport (for web/remote access)
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http ghcr.io/bsmi021/mcp-file-operations-server
```

## Usage

### Transport Modes

The server supports two transport modes:

#### 1. Stdio Transport (Default)
For direct integration with MCP clients like Claude Desktop:

```bash
npm start
```

#### 2. HTTP Transport with SSE (New in v1.5)
For remote connections and web applications:

```bash
npm run start:http
```

The HTTP server provides:
- **SSE Endpoint**: `GET http://localhost:3001/sse` - Establishes streaming connection
- **Messages Endpoint**: `POST http://localhost:3001/messages` - Receives client messages  
- **Health Check**: `GET http://localhost:3001/health` - Server status
- **Sessions**: `GET http://localhost:3001/sessions` - Active connection info

### Starting the Server

#### Development Mode

```bash
# Stdio transport with auto-reload
npm run dev

# HTTP transport with auto-reload
npm run dev:http
```

#### Production Mode

```bash
# Stdio transport
npm start

# HTTP transport
npm run start:http

# Custom port for HTTP
npm run start:http -- --port 8080
```

### Available Tools

#### Basic File Operations

- `copy_file`: Copy a file to a new location
- `read_file`: Read content from a file
- `write_file`: Write content to a file
- `move_file`: Move/rename a file
- `delete_file`: Delete a file
- `append_file`: Append content to a file

#### Directory Operations

- `make_directory`: Create a directory
- `remove_directory`: Remove a directory
- `copy_directory`: Copy a directory recursively (with progress reporting)

#### Watch Operations

- `watch_directory`: Start watching a directory for changes
- `unwatch_directory`: Stop watching a directory

#### Change Tracking

- `get_changes`: Get the list of recorded changes
- `clear_changes`: Clear all recorded changes

### Available Resources

#### Static Resources

- `file:///recent-changes`: List of recent file system changes

#### Resource Templates

- `file://{path}`: Access file contents
- `metadata://{path}`: Access file metadata
- `directory://{path}`: List directory contents

### Example Usage

#### Using Stdio Transport (MCP Clients)

```typescript
// Copy a file
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// Watch a directory
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// Access file contents through resource
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// Copy directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Progress token in result can be used to track progress
console.log(result.progressToken);
```

#### Using HTTP Transport (Web/Remote)

**Connecting via JavaScript:**

```javascript
// Establish SSE connection
const eventSource = new EventSource('http://localhost:3001/sse');
let sessionId = null;

eventSource.onopen = function() {
    console.log('Connected to MCP server');
};

eventSource.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    // Extract session ID from first message
    if (!sessionId && message.sessionId) {
        sessionId = message.sessionId;
    }
    
    console.log('Received:', message);
};

// Send a message to the server
async function sendMessage(method, params) {
    const message = {
        jsonrpc: '2.0',
        id: Date.now(),
        method: method,
        params: params
    };
    
    const response = await fetch('http://localhost:3001/messages', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-Session-ID': sessionId
        },
        body: JSON.stringify(message)
    });
    
    return response.json();
}

// Example: List tools
sendMessage('tools/list', {});

// Example: Read a file
sendMessage('tools/call', {
    name: 'read_file',
    arguments: { path: '/workspace/example.txt' }
});
```

**Using curl for testing:**

```bash
# Start SSE connection in background
curl -N http://localhost:3001/sse &

# Check server health
curl http://localhost:3001/health

# List active sessions
curl http://localhost:3001/sessions
```

**Interactive Web Client:**

A complete interactive example is available at [`examples/http-client.html`](./examples/http-client.html). Open this file in a web browser to test the HTTP interface with a user-friendly GUI.

## What's New in v1.5

### MCP SDK v1.5 Upgrade
- **Streamable HTTP Interface**: New HTTP transport with Server-Sent Events (SSE)
- **Enhanced API**: Upgraded to MCP SDK v1.5 with improved zod-based schemas
- **Multiple Connections**: Support for simultaneous HTTP connections with session management
- **Better Type Safety**: Improved TypeScript integration and error handling

### Streaming Features
- **Large File Support**: Efficient streaming for large file operations
- **Real-time Progress**: Progress updates via SSE for long-running operations
- **Session Management**: Multiple client connections with isolated sessions
- **HTTP API**: RESTful endpoints alongside traditional MCP protocol

## Docker Support

### Quick Start with Docker

```bash
# Build the image
docker build -t mcp-file-operations-server .

# Run with stdio (for MCP clients)
docker run -it --rm -v "$(pwd):/workspace" mcp-file-operations-server

# Run with HTTP interface
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http mcp-file-operations-server
```

### Volume Mounting

**Windows:**
```cmd
docker run -it --rm -v "C:\MyProject:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server
```

**Linux/macOS:**
```bash
docker run -it --rm -v "/home/user/project:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server
```

For comprehensive Docker setup instructions including local drive mounting for Windows and Linux, see [DOCKER.md](./DOCKER.md).

## Rate Limits

The server implements rate limiting to prevent abuse:

- **Tools**: 100 requests per minute
- **Resources**: 200 requests per minute
- **Watch Operations**: 20 operations per minute

Rate limit errors include a retry-after period in the error message.

## Security Features

### Path Validation

All file paths are validated to prevent directory traversal attacks:

- No parent directory references (`../`)
- Proper path normalization
- Input sanitization

### Resource Protection

- Rate limiting on all operations
- Proper error handling and logging
- Input validation on all parameters
- Safe resource cleanup

## Progress Reporting

Long-running operations like directory copying provide progress updates:

```typescript
interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}
```

Progress can be tracked through the progress token returned in the operation result.

## Development

### Building

```bash
npm run build
```

### Linting

```bash
npm run lint
```

### Formatting

```bash
npm run format
```

### Testing

```bash
npm test
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `MCP_HTTP_PORT` | `3001` | Port for HTTP transport |

### Transport Selection

- **Stdio**: Best for MCP clients like Claude Desktop, direct integration
- **HTTP**: Best for web applications, remote access, development/testing

The server can be configured through various settings:

- **Rate Limiting**: Configure request limits and windows
- **Progress Reporting**: Control update frequency and detail level
- **Resource Access**: Configure resource permissions and limits
- **Security Settings**: Configure path validation rules
- **Change Tracking**: Set retention periods and storage options
- **Watch Settings**: Configure debounce times and recursive watching

## Error Handling

The server provides detailed error information through the `FileOperationError` class and MCP error codes:

### Standard MCP Error Codes

- `InvalidRequest`: Invalid parameters or request format
- `MethodNotFound`: Unknown tool or resource requested
- `InvalidParams`: Invalid parameters (e.g., path validation failure)
- `InternalError`: Server-side errors

### Custom Error Types

- File operation failures
- Rate limit exceeded
- Path validation errors
- Resource access errors

Each error includes:

- Specific error code
- Detailed error message
- Relevant metadata (file paths, limits, etc.)
- Stack traces in development mode

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.