MCP File System Interaction Server

A comprehensive Model Context Protocol (MCP) server providing advanced file system operations, command execution, and project analysis capabilities.

---

Core Features

File Operations

• Complete file and directory management (create, read, write, edit, delete, move, copy)
• Advanced file editing with line-specific operations
• Batch file operations and renaming with patterns
• File comparison and difference analysis
• Smart file searching with glob patterns and text search

Command Execution

• Standard command execution with configurable timeouts
• Long-running command support with auto-detection
• Process management and monitoring
• Automatic cleanup of running processes
• Extended timeout handling for development servers

Project Analysis

• Visual project structure with Unicode tree display
• Comprehensive project type detection (Python, Node.js, Reflex, etc.)
• File type analysis and statistics
• Large file identification and optimization insights
• Customizable exclusion patterns

Version Control

• Built-in version control system for project snapshots
• Compare versions and track file history
• Backup and restore functionality
• Automatic and manual version creation

System Monitoring

• System information and performance metrics
• Process listing and management
• Network interface information
• Environment variable access
• File permissions and access control

Quick Start

Installation

1. Clone the repository:

git clone <repository-url>
cd mcp_backup

2. Install dependencies:

pip install -r requirements.txt

3. Run the server:

python main.py

Basic Usage

The server provides 25+ tools accessible through the MCP protocol:

# File operations
execute_command("ls -la")
read_file("config.py")
get_project_structure(".", format_type="tree")

# Long-running commands (auto-detected)
execute_command("reflex run")        # Uses 5-minute timeout
execute_command("npm start")         # Auto-detected long runner

# Process management
list_running_processes()
kill_running_process(pid=12345)

# Project analysis
get_project_structure(".", format_type="summary")
analyze_dependencies(".")

Available Tools

File System Operations

Tool	Description
list_directory	List directory contents
read_file / write_file	File I/O operations
edit_file	Line-specific file editing
create_directory	Create directories
delete_item / move_item / copy_item	File management
search_files	Find files with glob patterns
find_in_files	Search text within files
compare_files	File difference analysis
batch_rename	Bulk file renaming

Command Execution

Tool	Description
execute_command	Run system commands
list_running_processes	Show active processes
kill_running_process	Terminate processes
get_command_help	Command documentation

Project Analysis

Tool	Description
get_project_structure	Visual project tree and analysis
find_project_root	Locate project root directory
analyze_dependencies	Project dependency analysis
check_formatting	Code syntax and formatting validation

Version Control

Tool	Description
initialize_version_control	Set up project versioning
create_version	Create project snapshots
list_versions / restore_version	Version management
compare_versions	Compare project states
get_file_history	File change tracking

System Information

Tool	Description
system_info	Comprehensive system metrics
get_environment_vars	Environment variable access
check_permissions	File access permissions
process_list	System process information
network_info	Network interface details

Advanced Features

Long-Running Command Support

Automatically detects and handles development servers:

# Auto-detected long runners (5-minute timeout)
reflex run, reflex dev
npm start, npm run dev, yarn start
flask run, python -m flask run
uvicorn, gunicorn
webpack-dev-server, vite dev
next dev, nuxt dev, ng serve
gatsby develop, hugo server

Project Structure Analysis

Generates comprehensive project insights:

{
  "statistics": {
    "total_files": 45,
    "total_directories": 12,
    "total_size": "234.5KB"
  },
  "analysis": {
    "project_type": "Python + Reflex",
    "file_types": {".py": 15, ".md": 3, ".json": 2},
    "large_files": ["data.json (2.4MB)"]
  }
}

Smart Exclusions

Automatically excludes common build and cache directories:

• __pycache__, .git, .DS_Store
• node_modules, .vscode, .idea
• dist, build, .next, .nuxt
• coverage, .pytest_cache, .mypy_cache

Configuration

Timeout Settings

CONSOLE_TIMEOUT = 15        # Default timeout (seconds)
LONG_RUNNER_TIMEOUT = 300   # Long runner timeout (5 minutes)
MAX_TIMEOUT = 1800          # Maximum allowed timeout (30 minutes)

Command Parameters

• timeout - Custom timeout in seconds (overrides defaults)
• long_runner - Force long-runner mode (5-minute timeout)
• working_directory - Set command execution directory
• approve_dangerous - Allow potentially dangerous commands

Project Structure

mcp_backup/
├── src/
│   ├── server.py              # MCP server implementation
│   ├── config.py              # Configuration settings
│   ├── tool_schemas.py        # Tool schema definitions
│   ├── utils.py               # Utility functions
│   └── tools/
│       ├── file_operations.py    # Core file operations
│       ├── file_editor.py        # Advanced file editing
│       ├── command_executor.py   # Command execution engine
│       ├── project_structure.py  # Project analysis tools
│       ├── version_control.py    # Version management
│       ├── system_tools.py       # System monitoring
│       ├── advanced_file_ops.py  # Advanced file operations
│       ├── project_tools.py      # Project utilities
│       └── code_checker.py       # Code validation
├── main.py                    # Server entry point
├── requirements.txt           # Dependencies
└── README.md                  # This file

Development

Dependencies

• psutil>=5.9.0 - Process management
• mcp>=1.0.0 - MCP protocol implementation
• Standard library modules for file operations

Contributing

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

Use Cases

Development Workflow

• Run development servers with automatic timeout handling
• Monitor and manage running processes
• Analyze project structure and dependencies
• Version control for project snapshots

Code Analysis

• Project structure visualization
• File type distribution analysis
• Large file identification
• Code formatting validation

System Administration

• File system operations and monitoring
• Process management and cleanup
• System information gathering
• Batch file operations

Documentation

• Generate project structure trees
• Create comprehensive project overviews
• Track project evolution over time

Performance

• Memory Efficient: Processes files incrementally
• Smart Exclusions: Automatically skips irrelevant directories
• Process Safety: Robust cleanup of running processes
• Cross-Platform: Works on Windows, macOS, and Linux
• Error Recovery: Graceful handling of permission issues

Safety Features

• Maximum timeout limits prevent infinite processes
• Multiple process killing strategies ensure cleanup
• Permission checking handles restricted directories
• Path validation prevents unsafe operations
• Structured error handling with detailed messages

License

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

Support

• Create an Issue for bug reports or feature requests
• Fork the project and submit a Pull Request
• Star the repository if you find it useful!

---

Ready for production use with comprehensive file system interaction capabilities.