MCP Start App

A comprehensive Model Context Protocol (MCP) server for advanced local file management and system operations.

Features

🗂️ File Operations

• Read/Write Files: Full support for text file operations with encoding handling
• List Directories: Browse filesystem with size information and hidden file support
• File Information: Detailed metadata including permissions, timestamps, and size
• Path Validation: Robust path handling with security checks

✏️ Advanced File Editing

• Line-based Editing: Edit, insert, or delete specific lines in files
• Find & Replace: Text replacement with regex support across multiple files
• Diff Viewing: Compare current files with backups
• Edit History: Track all file modifications with detailed logs

🔍 Advanced Search Capabilities

• VSCode-like Search: Advanced search across multiple files with context
• File Type Filtering: Search by extension groups (code, web, config, etc.)
• Pattern Matching: Support for wildcards and regex
• Context Display: Show surrounding lines for search results
• File Name Search: Find files by name patterns
• Search Statistics: Analyze file distribution and sizes

💻 System Operations

• Command Execution: Safe execution of system commands
• System Information: Hardware and software details
• Process Management: View running processes
• File Finding: Advanced file discovery with patterns

🔧 Code Tools

• Syntax Validation: Check syntax for Python, JavaScript, JSON, etc.
• Code Formatting: Format code using standard formatters (Black, Prettier)
• Language Detection: Auto-detect programming languages

🔄 Backup & History

• Automatic Backups: Files are backed up before modifications
• Edit Tracking: Complete history of all file operations
• Restoration: Easy restore from backups
• History Analysis: Statistics and insights on editing patterns

🛡️ Security & Safety

• Path Validation: Prevents directory traversal attacks
• File Size Limits: Configurable limits to prevent memory issues
• Command Filtering: Restricted dangerous command execution
• Backup System: Automatic backup before destructive operations

Quick Start

1. Installation

# Clone or navigate to the project
cd /Users/{{USERNAME}}/Documents/mcp-start-app

# Run the installation script (sets up venv and installs everything)
./scripts/install.sh

2. Activation

# Activate the virtual environment
source venv/bin/activate

# Run the server
mcp-start-app

3. Alternative Run Methods

# Using the run script (auto-activates venv)
./scripts/run_server.py

# Direct Python execution
source venv/bin/activate
python -m mcp_start_app.main

Configuration

Claude Desktop Configuration

Add to your Claude Desktop config file:

{
  "mcpServers": {
    "mcp-start-app": {
      "command": "/Users/{{USERNAME}}/Documents/mcp-start-app/scripts/run_server.py",
      "args": []
    }
  }
}

Available Tools

Basic File Operations

• list_files(directory, show_hidden) - List directory contents
• read_file(file_path) - Read text file contents
• write_file(file_path, content) - Write content to file
• get_file_lines(file_path, start_line, end_line) - Get specific lines
• get_file_info(file_path) - Get detailed file information

Advanced File Editing

• edit_file_lines(file_path, start_line, new_content, end_line) - Edit specific lines
• insert_lines(file_path, line_number, content) - Insert new lines
• delete_lines(file_path, start_line, end_line) - Delete lines
• replace_in_file(file_path, search_pattern, replace_with, use_regex) - Find & replace
• get_file_diff(file_path, backup_file) - Show file differences
• get_edit_history(limit, file_path) - View edit history

Advanced Search Tools

• search_adv(search_term, search_path, case_sensitive, whole_word, use_regex, include_patterns, exclude_patterns, file_types, max_results, context_lines, show_hidden) - Advanced multi-file search
• replace_adv(search_term, replace_with, search_path, case_sensitive, whole_word, use_regex, include_patterns, exclude_patterns, file_types, dry_run, backup) - Advanced multi-file replace
• search_files_by_name(filename_pattern, search_path, case_sensitive, exact_match, show_hidden, exclude_patterns) - Search files by name
• search_in_files(search_pattern, directory, file_pattern, use_regex) - Simple text search
• get_search_stats(search_path) - Get directory statistics

System Tools

• run_command(command) - Execute system commands (with safety restrictions)
• get_system_info() - Get comprehensive system information
• find_files(pattern, directory, max_results) - Find files by pattern
• get_running_processes() - View running processes

Code Tools

• validate_syntax(file_path) - Check code syntax
• format_code(file_path, language) - Format code files

Data Tools

• get_local_data(query) - Local data queries

Project Structure

mcp-start-app/
├── 📁 venv/                        # Virtual environment
├── 📁 src/mcp_local/               # Main package
│   ├── 📁 core/                    # Core utilities & config
│   ├── 📁 services/                # Business logic layer
│   ├── 📁 tools/                   # MCP tool implementations
│   │   ├── file_operations.py      # Basic file tools
│   │   ├── file_editing.py         # Advanced editing tools
│   │   ├── search_tools.py         # Search and replace tools
│   │   ├── system_tools.py         # System operation tools
│   │   └── code_tools.py           # Code formatting and validation
│   ├── main.py                     # Entry point
│   └── server.py                   # Server configuration
├── 📁 tests/                       # Test suite
├── 📁 scripts/                     # Installation & run scripts
├── requirements.txt                # Dependencies
├── pyproject.toml                  # Python packaging
└── README.md                       # This file

Development

Running Tests

source venv/bin/activate
pytest                    # Run all tests
pytest --cov             # Run with coverage

Code Quality

source venv/bin/activate
black src/ tests/         # Format code
isort src/ tests/         # Sort imports  
flake8 src/ tests/        # Lint code
mypy src/                 # Type checking

License

This project is licensed under the MIT License.