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

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

Output Schema

{
  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

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

{
  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

{
  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

// 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

{
  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

{
  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

// 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