File Controller MCP Server

🚀 Advanced MCP Server for File and Directory Operations

MCP server for file and directory operations with project path validation, cross-drive support, terminal controller, and streaming support for large files (>512MB).

🌟 Key Features

• 🔒 Security First: All tools require absolute project paths with rigorous validation
• 📁 Complete File Operations: Read, write, create, delete, move, copy, rename, search
• 🌐 Cross-Platform: Works with local drives, network drives, and mapped drives
• ⚡ High Performance: Streaming support for massive files without memory issues
• 🎯 Precision Control: Byte-range reading with line/character level control
• 💻 Terminal Integration: Execute commands with process management
• 🔍 Advanced Search: Glob patterns and content search with regex support

🛠️ MCP Tools, Resources & Prompts Available

Core File Operations

• read_file - Advanced file reading with pagination, encoding support, and batch processing
• file_info - Detailed file analysis (encoding, MIME type, permissions) with batch support
• list_content - Directory listing with rich metadata and batch directory scanning

File Management

• create_folder - Recursive directory creation with batch folder creation
• move - Move files/directories with validation and batch operations
• copy - Copy files/directories recursively with batch support
• delete - Safe file/directory removal with batch deletion
• rename - Rename with filename sanitization and batch renaming

Advanced Features

• search_file - Glob pattern file search
• search_content - Content search with regex and filters
• terminal_controller - Command execution with process management

Batch Operations

• create_folders - Create multiple directories in one call
• batch_operations - Execute multiple file operations (move, delete, copy, rename) in batch

📚 MCP Resources (Fontes de Instrução)

• mcp-usage-guide - Guia completo de uso do MCP e ferramentas

🚀 Quick Start

Installation

npm install -g @andrebuzeli/file-controller

Basic Usage with MCP Client

// All tools require projectPath for security
const result = await mcp.read_file({
  projectPath: '/absolute/path/to/your/project',
  filePath: 'src/index.js',
  should_read_entire_file: false,
  start_line_one_indexed: 1,
  end_line_one_indexed_inclusive: 50
});

// Rich metadata returned
{
  content: "file content...",
  meta: {
    projectPath: "/absolute/path/to/your/project",
    filePath: "src/index.js",
    linesRead: 50,
    totalLines: 150,
    fileSize: "2.3 KB"
  }
}

📋 Advanced Usage

Large File Handling

// Read specific byte range from massive files
const result = await mcp.read_file({
  projectPath: '/project',
  filePath: 'huge-dataset.csv',
  should_read_entire_file: false,
  start_line_one_indexed: 1000000,
  end_line_one_indexed_inclusive: 1000050
});

Terminal Operations

// Execute commands with full process control
const result = await mcp.terminal_controller({
  projectPath: '/project',
  action: 'execute_async',
  command: 'npm',
  args: ['run', 'build'],
  shell_type: 'bash'
});

// Manage running processes
await mcp.terminal_controller({
  action: 'kill_process',
  processId: 'proc_123'
});

Advanced Search

// Search with glob patterns
const files = await mcp.search_file({
  projectPath: '/project',
  searchPath: 'src',
  pattern: '**/*.js',
  recursive: true
});

// Content search with filters
const matches = await mcp.search_content({
  projectPath: '/project',
  searchPath: 'src',
  searchText: 'TODO',
  filePattern: '**/*.js',
  caseSensitive: false
});

Batch Operations (All Tools Support Batch Mode)

// Create multiple directories - NEW: use create_folder with folderPaths array
const result = await mcp.create_folder({
  projectPath: '/project',
  folderPaths: ['src/components', 'src/utils', 'tests/unit', 'tests/integration'],
  continueOnError: true
});

// Move multiple files - NEW: use move with operations array
const moveResult = await mcp.move({
  projectPath: '/project',
  operations: [
    { sourcePath: 'old-file.txt', destinationPath: 'archive/old-file.txt' },
    { sourcePath: 'temp.log', destinationPath: 'logs/temp.log' }
  ],
  continueOnError: true
});

// Read multiple files - NEW: use read_file with filePaths array
const filesContent = await mcp.read_file({
  projectPath: '/project',
  filePaths: ['package.json', 'README.md', 'src/index.js'],
  should_read_entire_file: true,
  continueOnError: true
});

// Get info for multiple files - NEW: use file_info with filePaths array
const filesInfo = await mcp.file_info({
  projectPath: '/project',
  filePaths: ['package.json', 'server.js', 'README.md'],
  detect_encoding: true,
  count_lines: true
});

// List multiple directories - NEW: use list_content with directoryPaths array
const directoriesContent = await mcp.list_content({
  projectPath: '/project',
  directoryPaths: ['src', 'tests', 'docs'],
  continueOnError: true
});

🔒 Security Features

• Path Validation: All operations require absolute project paths
• Scope Enforcement: Prevents access outside project directory
• Input Sanitization: Safe filename handling for all platforms
• Process Isolation: Secure terminal command execution

⚡ Performance Optimizations

• Smart Caching: Path validation cache (1000 entries)
• Memory Safe: 16MB response limit, 512MB file limit
• Streaming: Large file support without memory exhaustion
• Async Processing: Non-blocking operations for better responsiveness

🛠️ Technical Details

MCP Protocol Compliance

• Transport: Stdio (stdin/stdout)
• Schema Validation: Zod-based input validation
• Error Handling: Structured error responses
• Metadata: Rich context information in all responses

Supported Platforms

• Windows: Drive letters, UNC paths, mapped drives
• Unix/Linux: Absolute paths, network mounts
• Cross-Platform: Consistent behavior across OS

📊 Version History

v2.10.0 (Current)

• 🚀 BREAKING: All file operation tools now support batch mode natively
• ✨ NEW: Every tool (read_file, file_info, create_folder, move, delete, rename, copy, list_content) accepts both single operations and arrays for batch processing
• 🔧 IMPROVED: Unified batch interface across all tools - no need for separate batch tools
• 📊 ENHANCED: Consistent error handling and reporting for batch operations
• 🔄 MAINTAINED: Full backward compatibility - existing single-operation calls work unchanged

v2.8.0

• ✨ NEW: create_folders - Create multiple directories in a single call
• ✨ NEW: batch_operations - Execute multiple file operations (move, delete, copy, rename) in batch
• 🔧 IMPROVED: Better performance for bulk operations
• 📊 ENHANCED: Detailed reporting for batch operations with success/failure tracking

v2.7.1

• Added 3 MCP resources for documentation and tool usage guidance
• Removed prompts to focus on resources for AI agents
• Improved logging and error handling

v2.0.0

• ✨ NEW: Project path validation for all tools
• 🔒 SECURITY: Enhanced scope validation
• 📊 IMPROVED: Consistent metadata across responses

v1.9.3

• 🚀 NEW: Streaming support for large files (>512MB)
• 🔍 NEW: Advanced search capabilities
• 🐛 FIXED: Memory limit issues

🤝 Integration

With Cursor IDE

Install globally and configure MCP settings in Cursor to use this server for file operations.

With VSCode + MCP Extension

Configure the MCP extension to point to the installed server binary.

Using MCP Resources & Prompts

// Access usage guide
const guide = await mcp.resources.read({ uri: 'file://mcp-usage-guide.json' });

// Get basic instructions
const instructions = await mcp.prompts.get({ name: 'mcp-usage-instructions' });

// Get practical examples
const examples = await mcp.prompts.get({ name: 'practical-examples' });

Programmatic Usage

import { spawn } from 'child_process';

const mcpProcess = spawn('file-controller', [], {
  stdio: ['pipe', 'pipe', 'pipe']
});

// Send MCP requests via stdin
// Receive responses via stdout

🐛 Troubleshooting

Common Issues

• Path Errors: Ensure all paths are absolute and within project scope
• Permission Errors: Check file system permissions
• Memory Issues: Use pagination for large files (>100MB)

Debug Mode

Enable verbose logging by setting environment variables or checking MCP client logs.

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ for the MCP ecosystem