Lupul-Augmentat/docs/tools/file-operations.md

# File Operations Tools

The MCP server provides several built-in tools for file system operations with comprehensive security controls.

## FileReadTool

Reads the contents of a file with security restrictions.

### Input Schema
```typescript
{
  path: string;        // File path (relative or absolute)
  encoding?: 'utf8' | 'binary';  // Default: 'utf8'
}
```

### Output Schema
```typescript
{
  content: string;     // File contents
  size: number;        // File size in bytes
  path: string;        // Absolute file path
}
```

### Security Features
- Prevents directory traversal attacks
- Only allows access to files within current working directory or system temp directory
- File size limit: 10MB
- Requires `file:read` permission

### Example Usage
```javascript
const result = await mcp.callTool('file_read', {
  path: './config.json',
  encoding: 'utf8'
});
console.log(result.content);
```

## FileWriteTool

Writes content to a file with security restrictions.

### Input Schema
```typescript
{
  path: string;        // File path (relative or absolute)
  content: string;     // Content to write
  encoding?: 'utf8' | 'binary' | 'base64';  // Default: 'utf8'
  mode?: 'overwrite' | 'append';             // Default: 'overwrite'
}
```

### Output Schema
```typescript
{
  path: string;        // Absolute file path
  size: number;        // File size after write
  mode: string;        // Write mode used
}
```

### Security Features
- Prevents directory traversal attacks
- Only allows writing within current working directory or system temp directory
- Blocks writing to system directories (/etc, /sys, /proc, /dev)
- Requires `file:write` permission
- Automatically creates parent directories if needed

### Example Usage
```javascript
// Write text file
await mcp.callTool('file_write', {
  path: './output.txt',
  content: 'Hello, World!'
});

// Write binary file
await mcp.callTool('file_write', {
  path: './image.png',
  content: 'iVBORw0KGgoAAAANS...', // base64 encoded
  encoding: 'base64'
});

// Append to file
await mcp.callTool('file_write', {
  path: './log.txt',
  content: 'New log entry\n',
  mode: 'append'
});
```

## FileListTool

Lists files and directories with filtering options.

### Input Schema
```typescript
{
  path: string;              // Directory path
  recursive?: boolean;       // Recurse into subdirectories
  pattern?: string;          // Glob pattern filter (e.g., '*.txt')
  includeHidden?: boolean;   // Include hidden files (starting with .)
}
```

### Output Schema
```typescript
{
  path: string;              // Directory path
  entries: Array<{
    path: string;            // Full path
    type: 'file' | 'directory' | 'symlink' | 'other';
    name: string;            // File/directory name
    size: number;            // Size in bytes
    modified: string;        // ISO date string
  }>;
  totalSize: number;         // Total size of all files
}
```

### Security Features
- Prevents directory traversal attacks
- Only allows listing within current working directory or system temp directory
- Requires `file:read` permission
- Skips inaccessible items instead of failing

### Example Usage
```javascript
// List directory contents
const result = await mcp.callTool('file_list', {
  path: './src'
});

// List recursively with pattern
const jsFiles = await mcp.callTool('file_list', {
  path: './src',
  recursive: true,
  pattern: '*.js'
});

// Include hidden files
const allFiles = await mcp.callTool('file_list', {
  path: './',
  includeHidden: true
});
```

## Error Handling

All file operation tools follow consistent error handling:

- **File not found**: Returns clear error message with the path
- **Permission denied**: Returns error when lacking required permissions
- **Invalid paths**: Blocks directory traversal and system paths
- **Size limits**: Enforces reasonable limits to prevent abuse

## Best Practices

1. **Always use relative paths** when possible for better portability
2. **Check permissions** before attempting operations
3. **Handle errors gracefully** - file operations can fail for many reasons
4. **Use appropriate encodings** - utf8 for text, base64 for binary data
5. **Be mindful of file sizes** - large files can impact performance