mcp-filesystem-server-ultra

scopweb/mcp-filesystem-server-ultra

3.2

If you are the rightful owner of mcp-filesystem-server-ultra and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Filesystem Server Ultra is an advanced server designed for high-performance file operations, featuring intelligent caching, memory mapping, and robust search capabilities.

MCP Filesystem Server Ultra

Ultra-fast MCP Filesystem Server with intelligent caching, memory mapping, and advanced search capabilities designed for Claude Desktop.

🚀 Features

Core Performance

  • Memory Mapping (mmap): Zero-copy file access for large files
  • Intelligent Caching: Smart caching system that adapts to access patterns
  • Goroutine Pool: Optimized concurrent operations with controlled resource usage
  • Batch Operations: Multiple file operations in single requests

Advanced Operations

  • Smart Search: Regex support, content matching, file type filtering
  • Safe Editing: Atomic file operations with backup support
  • File Comparison: Advanced diff generation and similarity analysis
  • Project Analysis: Comprehensive project structure analysis
  • Refactoring Assistance: Safe code refactoring with dependency analysis
  • Performance Monitoring: Built-in performance analysis and bottleneck detection

Developer Experience

  • Chunked Operations: Handle large files without memory limits
  • Real-time Monitoring: File system watching capabilities
  • Duplicate Detection: Content-based duplicate file detection
  • Report Generation: JSON, HTML, and Markdown reports
  • Benchmark Suite: Built-in performance benchmarking

📊 Performance Benchmarks

Based on comprehensive testing with various file sizes and operations:

Small Files (< 1KB)

  • Read: ~150 ops/ms
  • Write: ~120 ops/ms
  • Search: ~200 ops/ms

Medium Files (1-100KB)

  • Read: ~80 ops/ms
  • Write: ~60 ops/ms
  • Search: ~100 ops/ms

Large Files (> 1MB)

  • Read (mmap): ~40 ops/ms
  • Write (chunked): ~25 ops/ms
  • Search (indexed): ~50 ops/ms

Batch Operations

  • Multi-file read: 5-10x faster than sequential
  • Batch writes: 3-5x faster than individual operations

🛠️ Installation

Pre-built Binaries

Download from Releases

Build from Source

git clone https://github.com/scopweb/mcp-filesystem-server-ultra.git
cd mcp-filesystem-server-ultra
go build -o mcp-filesystem-ultra

⚙️ Configuration

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem-enhanced": {
      "command": "path/to/mcp-filesystem-ultra",
      "args": [
        "--allowed-dirs", "C:\\Users\\YourUser\\Documents",
        "--allowed-dirs", "C:\\Users\\YourUser\\Projects",
        "--cache-size", "100MB",
        "--enable-mmap"
      ]
    }
  }
}

Command Line Options

--allowed-dirs     Directories accessible to the server (required)
--cache-size       Cache size limit (default: 50MB)
--enable-mmap      Enable memory mapping for large files
--goroutine-limit  Max concurrent goroutines (default: 100)
--log-level        Logging level: debug, info, warn, error
--benchmark        Run performance benchmarks

📖 API Reference

Core Operations

  • read_file - Read single file with optional encoding
  • write_file - Write file with content
  • write_file_safe - Atomic write with backup option
  • read_multiple_files - Batch read multiple files
  • list_directory - Enhanced directory listing
  • create_directory - Create directories recursively

Advanced Operations

  • smart_search - Intelligent search with filters
  • search_files - Pattern-based file search
  • compare_files - File comparison with diff
  • analyze_file - Deep file analysis
  • analyze_project - Project structure analysis
  • batch_operations - Multiple operations in one call

Editing & Refactoring

  • edit_file - Replace text without full rewrite
  • assist_refactor - Safe refactoring assistance
  • move_file - Move/rename with validation
  • copy_file - Copy files/directories
  • delete_file - Safe deletion with confirmation

Performance & Analysis

  • performance_analysis - Benchmark file operations
  • find_duplicates - Content-based duplicate detection
  • generate_report - Comprehensive reports
  • plan_task - Task planning for complex operations

Advanced Features

  • chunked_write - Handle large files in chunks
  • split_file - Split large files
  • join_files - Combine file chunks
  • smart_sync - Intelligent file synchronization

🔧 Architecture

Core Components

Engine (core/engine.go)
  • Central coordination of all operations
  • Memory management and resource pooling
  • Performance monitoring and optimization
Caching System (cache/intelligent.go)
  • LRU cache with intelligent eviction
  • Access pattern analysis
  • Memory-aware cache sizing
Search Operations (core/search_operations.go)
  • Regex-based content search
  • File type filtering
  • Parallel search execution
Memory Mapping (core/mmap.go)
  • Zero-copy file access for large files
  • Platform-specific optimizations
  • Automatic fallback for small files

Performance Optimizations

  1. Memory Mapping: Large files accessed via mmap for zero-copy operations
  2. Goroutine Pooling: Controlled concurrency prevents resource exhaustion
  3. Intelligent Caching: Adaptive cache that learns from access patterns
  4. Batch Processing: Multiple operations combined for efficiency
  5. Incremental Search: Resume interrupted searches from last position

🧪 Benchmarking

Run performance tests:

# Basic benchmarks
./mcp-filesystem-ultra --benchmark

# Custom benchmark with specific directory
./mcp-filesystem-ultra --benchmark --test-dir /path/to/test/directory

# Memory profiling
go run main.go --benchmark --profile-memory

Benchmark Results Format

{
  "overall_performance": {
    "total_operations": 5000,
    "avg_response_time_ms": 12.3,
    "operations_per_second": 406,
    "memory_efficiency": 94.2
  },
  "operation_breakdown": {
    "read_operations": 85.3,
    "write_operations": 67.8,
    "search_operations": 124.5
  }
}

🔒 Security Features

  • Directory Restrictions: Access limited to explicitly allowed directories
  • Path Validation: Prevents directory traversal attacks
  • Safe Operations: Atomic writes with rollback capability
  • Input Sanitization: All inputs validated and sanitized
  • Resource Limits: Memory and CPU usage controls

🤝 Contributing

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/amazing-feature
  3. Run tests: go test ./...
  4. Run benchmarks: go run main.go --benchmark
  5. Commit changes: git commit -m 'Add amazing feature'
  6. Push branch: git push origin feature/amazing-feature
  7. Open Pull Request

Development Setup

# Install dependencies
go mod download

# Run tests with coverage
go test -v -cover ./...

# Run benchmarks
go test -bench=. ./bench

# Profile memory usage
go run main.go --benchmark --profile-memory

📄 License

MIT License - see file for details.

🐛 Troubleshooting

Common Issues

High Memory Usage

  • Reduce cache size: --cache-size 25MB
  • Disable mmap for small files: add size threshold

Permission Errors

  • Verify allowed directories in configuration
  • Check file/directory permissions

Performance Issues

  • Enable mmap for large files: --enable-mmap
  • Increase goroutine limit: --goroutine-limit 200
  • Use batch operations for multiple files

Debug Mode

./mcp-filesystem-ultra --log-level debug --allowed-dirs /your/path

📞 Support

Built for Claude Desktop • Optimized for Performance • Production Ready