Development Guide

Project Overview

MCP Filesystem Server Ultra-Fast (v4.1.0) — A high-performance MCP (Model Context Protocol) filesystem server written in Go, optimized for Claude Desktop and Claude Code. Provides 16 MCP tools (consolidated from 59 in v3.x) for file operations, search, editing, backups, streaming, and WSL/Windows integration. All tools include MCP spec-compliant annotations (readOnlyHint, destructiveHint, idempotentHint).

Build & Test

# Build (Windows) — v4 binary
go build -ldflags="-s -w" -trimpath -o filesystem-ultra-v4.exe .

# Or use the build script
build-windows.bat

# Run all tests
go test ./tests/...
go test ./core/...
go test ./tests/security/...

# Run with race detector
go test -race ./...

# Run security fuzzing
go test -fuzz=Fuzz ./tests/security

# Run specific test
go test ./tests/ -run TestName -v

# Build dashboard (separate binary)
go build -ldflags="-s -w" -trimpath -o dashboard.exe ./cmd/dashboard/

Tool Inventory (16 tools)

CORE (5):      read_file, write_file, edit_file, list_directory, search_files
EDIT+ (1):     multi_edit
FILES (4):     move_file, copy_file, delete_file, create_directory
BATCH (1):     batch_operations  (pipelines + batch rename)
BACKUP (1):    backup            (restore via action:"restore")
ANALYSIS (1):  analyze_operation (file, optimize, write, edit, delete)
WSL (1):       wsl               (sync + status via action param)
UTIL (1):      server_info       (help, stats, artifact via action param)
INFO (1):      get_file_info

Key consolidations (v3 → v4)

• read_file replaces: read_file, chunked_read_file, intelligent_read, read_file_range, read_base64
• write_file replaces: write_file, create_file, streaming_write_file, intelligent_write, write_base64
• edit_file replaces: edit_file, smart_edit_file, intelligent_edit, recovery_edit, search_and_replace, replace_nth_occurrence, regex_transform_file
• search_files replaces: smart_search, advanced_text_search, count_occurrences
• batch_operations replaces: execute_pipeline, batch_rename_files
• backup replaces: restore_backup, list_backups, get_backup_info, compare_with_backup, cleanup_backups
• wsl replaces: wsl_sync, wsl_status, wsl_to_windows_copy, windows_to_wsl_copy, configure_autosync
• server_info replaces: stats, get_help, artifact, performance_stats, get_edit_telemetry
• analyze_operation replaces: analyze_file, analyze_write, analyze_edit, analyze_delete, get_optimization_suggestion

Architecture

main.go                    # Entry point: CLI flags, 16 MCP tool registrations, server startup
core/
  engine.go                # UltraFastEngine - central struct with cache, worker pool, metrics
  edit_operations.go       # EditFile, MultiEdit with backup, risk assessment, hooks
  file_operations.go       # RenameFile, SoftDeleteFile, CopyFile, MoveFile, etc.
  streaming_operations.go  # StreamingWriteFile, ChunkedReadFile, SmartEditFile
  search_operations.go     # SmartSearch, AdvancedTextSearch
  backup_manager.go        # BackupManager - create/restore/compare/cleanup backups
  impact_analyzer.go       # Risk assessment (LOW/MEDIUM/HIGH/CRITICAL)
  edit_safety_layer.go     # EditSafetyValidator - context validation, stale edit prevention
  hooks.go                 # Pre/post operation hook system (12 event types)
  large_file_processor.go  # Line-by-line and chunk-based processing
  regex_transformer.go     # Advanced regex transformations with capture groups
  batch_operations.go      # Batch file operations with rollback
  batch_rename.go          # Batch file renaming
  normalizer.go            # Self-Learning Request Normalizer (14 built-in rules)
  audit_logger.go          # AuditLogger - JSON Lines operation log + MetricsSnapshot writer
  claude_optimizer.go      # Claude Desktop auto-optimization (small/large file strategy)
  plan_mode.go             # Dry-run analysis (analyze_write, analyze_edit, analyze_delete)
  pipeline.go              # Pipeline executor: sequential/parallel dispatch, action handlers
  pipeline_types.go        # Types: PipelineRequest, PipelineStep, StepResult, validation
  pipeline_conditions.go   # 9 condition types: evaluation and validation
  pipeline_templates.go    # {{step_id.field}} template resolution
  pipeline_scheduler.go    # DAG builder, topological sort, destructive step splitting
  path_converter.go        # WSL <-> Windows path conversion
  path_detector.go         # Path format detection
  wsl_sync.go              # WSL/Windows file synchronization
  autosync_config.go       # Auto-sync configuration system
  watcher.go               # File watcher for cache invalidation
  mmap.go                  # Memory-mapped file I/O (Windows fallback)
  config.go                # Performance thresholds and constants
  errors.go                # Custom error types (PathError, ValidationError, EditError, etc.)
cache/
  intelligent.go           # 3-tier cache: BigCache (files) + go-cache (dirs) + go-cache (metadata)
mcp/
  mcp.go                   # MCP type definitions (legacy, mostly unused)
tests/
  mcp_functions_test.go    # Core MCP function tests
  bug5_test.go - bug23_test.go  # Regression tests
  normalizer_test.go       # Normalizer unit tests
  pipeline_test.go         # Pipeline integration tests
  edit_safety_test.go      # Edit safety validation tests
  security/                # Security & fuzzing tests (package: security)
cmd/
  dashboard/
    main.go              # Separate binary: HTTP dashboard for logs/metrics/backups
    static/              # Embedded web UI (go:embed) - HTML + vanilla JS + CSS

Key Dependencies

Package	Purpose
github.com/mark3labs/mcp-go v0.43.2	MCP server SDK
github.com/allegro/bigcache/v3 v3.1.0	High-performance file content cache
github.com/patrickmn/go-cache v2.1.0	Directory/metadata cache
github.com/panjf2000/ants/v2 v2.11.5	Goroutine worker pool
github.com/fsnotify/fsnotify v1.9.0	File system event watching

Go version: 1.26.0

Core Patterns

Access Control

if len(e.config.AllowedPaths) > 0 {
    if !e.isPathAllowed(path) {
        return nil, &PathError{Op: "operation", Path: path, Err: fmt.Errorf("access denied")}
    }
}

isPathAllowed() resolves symlinks via filepath.EvalSymlinks() before checking containment. Allowed paths resolved once at engine startup. Empty AllowedPaths = no restrictions.

Error Handling

Custom error types in core/errors.go: PathError, ValidationError, CacheError, EditError, ContextError. Always wrap with fmt.Errorf("context: %w", err).

MCP Tool Response

// Success
return mcp.NewToolResultText("result text"), nil

// Error
return mcp.NewToolResultError("error message"), nil

Tool Registration (main.go)

s.AddTool(mcp.NewTool("tool_name",
    mcp.WithDescription("description"),
    mcp.WithString("param", mcp.Description("desc"), mcp.Required()),
), auditWrap("tool_name", func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // implementation
}, auditLogger))

All handlers wrapped with auditWrap() for normalization + audit logging. Parameter extraction: request.GetArguments() returns map[string]interface{}, use request.RequireString("param") or type assertions.

Concurrency

• engine.operationSem channel-based semaphore limits parallel ops
• engine.pool (ants worker pool) for goroutine management
• sync.RWMutex for shared caches (regex cache, env detection)
• All public methods accept context.Context

File Size Thresholds (core/config.go)

• Small: < 100KB (direct I/O)
• Medium: < 500KB (streaming)
• Large: < 5MB (chunking)
• VeryLarge: < 50MB (special handling, edit rejected above this)

Risk Assessment

• MEDIUM: > 20% of file modified
• HIGH: > 75% of file modified
• CRITICAL: > 90% of file modified (blocked without force: true)
• Only CRITICAL blocks operations. MEDIUM/HIGH auto-proceed with backup + warning.

Backup System

Backups stored in configurable dir (default: temp/mcp-batch-backups). Backup IDs are timestamp-random format. Metadata stored as JSON alongside backup files. Sanitized against path traversal.

Code Conventions

• Naming: PascalCase for exported types/functions, camelCase for unexported
• Imports: stdlib first, then third-party, then local packages
• Context: All public operations accept context.Context as first param
• Compact mode: Many functions check e.config.CompactMode to return shorter responses
• Path normalization: NormalizePath() called early in every tool handler for WSL/Windows compat
• Language: Code in English, user-facing docs in both English and Spanish

Configuration (CLI Flags)

Key flags parsed in main.go:

• --allowed-paths — Comma-separated or positional args for allowed base paths
• --compact-mode — Minimal token responses for Claude Desktop
• --cache-size — Cache memory limit (default: 100MB)
• --parallel-ops — Max concurrent ops (default: 2x CPU, max 16)
• --hooks-enabled / --hooks-config — Hook system
• --backup-dir / --backup-max-age / --backup-max-count — Backup config
• --risk-threshold-medium / --risk-threshold-high — Risk thresholds
• --debug / --log-level — Logging (debug, info, warn, error — configures slog JSON handler)
• --log-dir — Directory for audit logs and metrics snapshots (enables operation logging)
• --normalizer-rules — Path to external normalizer rules JSON file

Logging & Dashboard

Audit Logging (—log-dir)

When --log-dir is set, the MCP server writes:

• operations.jsonl — JSON Lines audit log (one entry per tool call, auto-rotates at 10MB, keeps last 3)
• metrics.json — Performance metrics snapshot (updated every 30 seconds)
• normalizer_stats.json — Normalizer activity (by tool, by rule, recent normalizations)

All 16 tools are wrapped with auditWrap() in main.go which records timing, status, path, bytes_in/out, file_size, args summary, risk level, lines_changed, and matches count. Zero overhead when --log-dir is not set.

Dashboard Binary

Separate binary in cmd/dashboard/ — reads log files and serves a web UI:

dashboard.exe --log-dir=<same as MCP server> --backup-dir=<backup path> --port=9100

• No coupling with MCP server (file-based communication only)
• Embedded web assets via go:embed (single binary)
• Real-time updates via SSE (Server-Sent Events)
• Pages: Dashboard (metrics), Operations (audit log), Backups (enterprise recovery), Statistics, Normalizer, Error Patterns, Edit Analysis

Request Normalizer

Data-driven normalization engine between MCP transport and tool handlers. Handles Claude Desktop parameter mismatches automatically.

6 Rule Types

Type	Description	Example
param_alias	Rename parameter	old_str → old_text
param_default	Add missing parameter	Missing id → auto-generated
type_coerce	Convert string to type	"true" → true (bool)
json_accept_both	Accept raw JSON or string	[{...}] → "[{...}]"
nested_alias	Rename field inside JSON	step type → action
nested_default	Add missing nested field	step missing id → auto-generated

14 Built-in Rules

Covers: old_str/new_str aliases, string-to-bool coercion for force/count_only/dry_run/permanent/recursive, raw JSON array acceptance for edits_json, pipeline type→action alias, and auto-generated step IDs.

Custom rules via --normalizer-rules rules.json.

Pipeline Transformation System

12-action pipeline system via batch_operations with pipeline_json parameter.

Actions

Action	Type	Description
search	Read	Search files by pattern
read_ranges	Read	Read file contents
count_occurrences	Read	Count pattern occurrences
edit	Write	Search-and-replace
multi_edit	Write	Multiple edits per file
regex_transform	Write	Regex with capture groups
copy	Write	Copy files
rename	Write	Rename/move files
delete	Write	Soft-delete files
aggregate	Meta	Combine content from steps
diff	Meta	Unified diff between files
merge	Meta	Union/intersection of file lists

Features

• Step chaining: input_from and input_from_all for data flow between steps
• Conditional steps: 9 condition types (has_matches, count_gt, file_exists, etc.)
• Template variables: {{step_id.field}} resolves to prior step results
• Parallel execution: parallel: true enables DAG-based scheduling
• Safety: dry_run, force, stop_on_error, create_backup flags
• Progress tracking: Per-step audit entries when --log-dir is set

Security Notes

• All temp files use crypto/rand for names (not predictable timestamps)
• Backup IDs sanitized: only alphanumeric, -, _ allowed
• isPathAllowed() resolves symlinks before containment check
• copyDirectory() skips symlinks
• Temp files and backup metadata use 0600 permissions
• No unsafe package usage in production code
• Line endings normalized via normalizeLineEndings() before risk assessment