/file-system-mcp

MCP File System Interaction Server

Python MCP License Platform

Tech Stack

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
  1. Install dependencies:
pip install -r requirements.txt
  1. 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.