Architecture

System Overview

MCP Filesystem Ultra is built with a modular, high-performance architecture designed for maximum efficiency and reliability.

Core Components

Engine (`core/engine.go`)

The central UltraFastEngine struct coordinates all operations:

Worker pool: Goroutine management with ants/v2
Operation semaphore: Concurrency control
Metrics tracking: Real-time performance monitoring
Cache management: Intelligent caching layer

Cache System (`cache/intelligent.go`)

3-tier caching architecture:

BigCache: File content (O(1) operations)
go-cache: Directory listings
go-cache: Metadata (file info, stats)

Hit rates: 98.9% in production

File Operations (`core/file_operations.go`)

RenameFile: Atomic rename with validation
SoftDeleteFile: Safe deletion to filesdelete/
CopyFile: Recursive copy with permission preservation
MoveFile: Atomic move operations
GetFileInfo: Detailed file metadata

Edit Operations (`core/edit_operations.go`)

EditFile: Intelligent multi-line search and replace
MultiEdit: Batch editing with rollback
Backup system: Automatic backups before modifications
Risk assessment: 4-level risk evaluation (LOW/MEDIUM/HIGH/CRITICAL)
Safety hooks: Pre/post edit validation

Streaming Operations (`core/streaming_operations.go`)

StreamingWriteFile: Chunk-based writing for large files
ChunkedReadFile: Memory-efficient reading
SmartEditFile: Edit files >1MB without loading into memory

Search Operations (`core/search_operations.go`)

SmartSearch: Filename and content search
AdvancedTextSearch: Regex search with context

Claude Optimizer (`core/claude_optimizer.go`)

Auto-optimization for Claude Desktop:

File size detection
Strategy selection (direct vs streaming)
Progress reporting
Error recovery

Data Flow

┌─────────────┐
│ Claude      │
│ Desktop     │
└──────┬──────┘
       │ MCP Protocol
       ▼
┌─────────────┐
│ main.go     │ ← Tool registrations (16 tools)
│ MCP Server  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Engine      │ ← Central coordinator
│ (core)      │
└──────┬──────┘
       │
       ├─────► Cache ────► BigCache
       │                   go-cache
       │
       ├─────► File Ops ──► OS Filesystem
       │
       ├─────► Search ────► Walker + Matcher
       │
       └─────► Backup ────► Backup Manager

Key Design Patterns

Pool Pattern

type UltraFastEngine struct {
    pool *ants.Pool  // Goroutine pool
    operationSem chan struct{}  // Semaphore
}

Reuses goroutines for better performance and lower GC pressure.

Cache Pattern

// 3-tier cache hierarchy
fileCache *bigcache.BigCache     // Hot path
dirCache *cache.Cache            // Warm path
metaCache *cache.Cache           // Cold path

Strategy Pattern

Auto-selects optimal strategy based on file size:

< 50KB: Direct I/O
50KB - 500KB: Buffered I/O
> 500KB: Streaming

Observer Pattern

File watcher invalidates cache on external changes:

watcher *fsnotify.Watcher

Performance Optimizations

1. Parallel Operations

Max concurrent ops: 2x CPU cores (default)
Configurable via --parallel-ops
Channel-based semaphore

2. Intelligent Caching

Cache size: 100MB - 500MB
LRU eviction
Auto-invalidation on modifications
98.9% hit rate

3. Memory Mapping

Large files use mmap when available
Fallback to buffered I/O on Windows
Zero-copy for read operations

4. Streaming

Chunk size: 64KB - 1MB (adaptive)
Progress reporting every 5%
Backpressure handling

Security Architecture

Access Control

if len(e.config.AllowedPaths) > 0 {
    if !e.isPathAllowed(path) {
        return PathError{Op: op, Path: path, Err: ErrAccessDenied}
    }
}

Symlink Protection (v3.13.0)

resolvedPath, err := filepath.EvalSymlinks(path)
// Prevents symlink traversal attacks

Backup Security

Unique IDs with crypto/rand
Sanitized paths (no .., /, \)
Restricted permissions (0600)

Dependencies

Package	Purpose	Version
`github.com/mark3labs/mcp-go`	MCP SDK	v0.43.2
`github.com/allegro/bigcache/v3`	File cache	v3.1.0
`github.com/patrickmn/go-cache`	Dir/meta cache	v2.1.0
`github.com/panjf2000/ants/v2`	Worker pool	v2.11.5
`github.com/fsnotify/fsnotify`	File watching	v1.9.0

Error Handling

Custom error types in core/errors.go:

PathError: File path issues
ValidationError: Input validation
CacheError: Cache operations
EditError: Edit operations
ContextError: Context issues

All errors wrapped with context using fmt.Errorf("op: %w", err).

Configuration

Loaded from CLI flags in main.go:

type Config struct {
    AllowedPaths []string
    CacheSize int64
    ParallelOps int
    CompactMode bool
    // ... 20+ more options
}

Metrics & Monitoring

Real-time metrics via server_info({ action: "stats" }) tool:

Operations per second
Cache hit rate
Average response time
Memory usage
Per-operation counters

Next Steps

Intelligent Operations - Auto-optimization system
Performance & Tokens - Optimization strategies
Security - Security features and testing