convez.ai
MCP ServerDevOps & InfraestruturaAvançado
scopweb

MCP Filesystem Server Ultra-Fast

scopweb/mcp-filesystem-go-ultra

Servidor filesystem ultrarrápido em Go com 17 tools, pipeline e auditoria

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de alta performance em Go para manipulação de arquivos com 17 ferramentas consolidadas, sistema de pipeline, auditoria, dashboard e suporte a WSL. Otimizado para Claude Desktop e Claude Code com cache inteligente, edição segura com rollback e operações em lote atômicas.

Instalação

$npx convez-ai scopweb/mcp-filesystem-go-ultra

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
4

Casos de uso

  • Manipulação eficiente de grandes projetos com centenas de arquivos
  • Automação de operações em lote com pipeline DAG e dry-run
  • Desenvolvimento seguro com backup automático, avaliação de risco e rollback
  • Operações cross-platform WSL/Windows com tradução transparente de caminhos
  • Auditoria e observabilidade com logging JSON Lines e dashboard em tempo real

Veredito

Ferramenta técnica sólida e bem-engineered para gerenciamento de filesystem em escala, com cache de 3 camadas, pipeline paralelo e auditoria completa. Ideal para fluxos automatizados complexos, porém requer Go 1.26+ e curva de aprendizado para explorar todo o potencial do sistema.

README

A tradução para o português deste README ainda está na fila.

MCP Filesystem Server Ultra-Fast

v4.5.2 · Go · MCP 2025-11-25 · 17 core tools + git + help + fs super-tool

A high-performance Model Context Protocol filesystem server written in Go. Designed for use with Claude Desktop and Claude Code, with first-class support for large files, WSL/Windows interoperability, and token-efficient responses.


Features

  • 17 core tools + git + help (consolidated from 59 in v3.x) — all functionality preserved, zero tool bloat
  • 31 tools total (16 core + 13 aliases) with Claude Code-compatible names (View, Edit, Write, LS, GlobTool, GrepTool, etc.)
  • MCP spec-compliant annotations — readOnlyHint, destructiveHint, idempotentHint on every tool
  • Intelligent editing with automatic backup, risk assessment, and rollback on failure
  • 3-tier cache (BigCache + go-cache) with file watcher invalidation for O(1) reads
  • Streaming and chunked I/O for files up to 50 MB without blocking
  • WSL ↔ Windows path translation — accepts /mnt/c/..., C:\..., and /tmp/... transparently
  • Compact mode — minimal token responses (~90% reduction) for high-volume Claude Desktop sessions
  • Risk assessment — edits above configurable thresholds (30 / 50 / 90% change) require explicit confirmation
  • Hook system — pre/post hooks for write, edit, delete, create, move, and copy events
  • Plan mode — dry-run analysis with diff preview and risk report before applying changes
  • Pipeline system — 12 actions with conditions, templates, DAG-based parallel execution (5–22× fewer round-trips)
  • Atomic batch operations — grouped file operations with rollback on failure
  • Audit logging — JSON Lines operation log + metrics snapshots for observability
  • Dashboard — separate HTTP binary for real-time metrics, operation log, and backup recovery
  • Access control — restrict the server to specific directory trees via --allowed-paths

Build

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

# With ripgrep embedded (~4MB larger)
go build -ldflags="-s -w" -trimpath -tags embed_rg -o filesystem-ultra-v4-embed.exe .

# Or use the build scripts
build-windows.bat        # default
build-windows-embed.bat  # with ripgrep

Requires Go 1.26+. No CGO. Tested on Windows 11 and Ubuntu 22.04 (WSL2).

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

# With race detector
go test -race ./...

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

Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\path\\to\\filesystem-ultra-v4.exe",
      "args": [
        "--compact-mode",
        "--cache-size", "200MB",
        "--parallel-ops", "8",
        "--log-level", "error",
        "--log-dir", "C:\\logs\\mcp-filesystem",
        "C:\\your\\project\\"
      ]
    }
  }
}

Linux:

{
  "mcpServers": {
    "filesystem-ultra": {
      "command": "/path/to/filesystem-ultra",
      "args": [
        "--compact-mode",
        "--cache-size", "200MB",
        "--parallel-ops", "8",
        "--log-level", "error",
        "--log-dir", "/home/user/.local/share/mcp-filesystem/logs",
        "/home/user/projects/"
      ]
    }
  }
}

The positional arguments after the flags are the allowed base paths. Omitting paths disables access control entirely.

Key flags

FlagDefaultDescription
--compact-modeoffMinimal token responses
--cache-size100MBIn-memory file cache limit
--parallel-ops2×CPU (max 16)Max concurrent operations
--backup-dirsystem tempDirectory for automatic backups
--backup-max-age72hMaximum backup retention
--backup-max-count50Maximum backup count per file
--risk-threshold-medium30% change that triggers a warning
--risk-threshold-high50% change that requires force: true
--hooks-enabledoffEnable pre/post operation hooks
--hooks-config—Path to hooks configuration JSON
--log-dir—Directory for audit logs and metrics (enables logging)
--log-levelinfoLog level: debug, info, warn, error
--debugoffVerbose debug logging

Tool Discovery

Claude Desktop uses lazy tool loading — it only discovers ~5 tools per query via semantic search, missing most of the 16 available tools.

Three layers solve this:

LayerHow it worksClient support
/filesystem-ultra-tools skillClaude Code skill that calls help on conversation startClaude Code
help toolKeyword-rich description; returns full 16-tool catalogAny MCP client
fs super-toolSingle entry point dispatching to all 16 operations via action paramAny MCP client
server.WithInstructions()Sends catalog during MCP initialize handshakeSpec-compliant clients

Using the skill

The skill ships in .claude/skills/filesystem-ultra-tools/. In Claude Code or Claude Desktop, invoke:

/filesystem-ultra-tools

This calls the help tool and loads the full catalog. You can also add this to your project instructions:

At the start of every conversation, do tool_search for "filesystem help" and then call filesystem-ultra:help()

Available Tools (16 + 6 aliases + fs + help)

Core (5)

ToolDescription
read_fileRead full file, line range (start_line/end_line), head/tail (max_lines+mode), or base64 (encoding:"base64")
write_fileCreate or overwrite file. Supports text (content) and binary (encoding:"base64")
edit_fileFind-and-replace with backup and risk assessment. Modes: exact match (default), search_replace (all occurrences), regex (capture groups), occurrence:N (Nth match)
list_directoryDirectory listing with cache
search_filesSearch by pattern with optional file_types, include_content, include_context, case_sensitive, count_only

Edit+ (1)

ToolDescription
multi_editMultiple find-and-replace operations on the same file in one call via edits_json

File Operations (4)

ToolDescription
move_fileMove or rename file/directory
copy_fileRecursive copy preserving permissions
delete_fileSoft-delete (default) or permanent (permanent: true)
create_directoryCreate directory tree (mkdir -p)

Batch & Pipeline (1)

ToolDescription
batch_operationsAtomic batch ops (request_json), multi-step pipelines (pipeline_json), or batch rename (rename_json) — with rollback on failure

Backup (1)

ToolDescription
backupManage backups via action: list, info, compare, cleanup, restore

Analysis (1)

ToolDescription
analyze_operationDry-run preview via operation: file, edit, delete, write, optimize, compare

WSL (1)

ToolDescription
wslWSL ↔ Windows sync and status. Params: wsl_path/windows_path + direction, or action:"status"

Utility (1)

ToolDescription
server_infoServer diagnostics via action: stats, help, artifact

Info (1)

ToolDescription
get_file_infoSize, permissions, timestamps, type

Dashboard

Separate binary for real-time observability — reads audit logs and serves a web UI.

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

# Run
dashboard.exe --log-dir=C:\logs\mcp-filesystem --backup-dir=C:\backups --port=9100
  • No coupling with MCP server (file-based communication only)
  • Embedded web assets via go:embed (single binary, no dependencies)
  • Real-time updates via SSE (Server-Sent Events)
  • Pages: Dashboard (metrics), Operations (audit log), Backups (enterprise recovery), Statistics, Proxy/Tokens, Edit Analysis

MCP Proxy

Transparent stdio proxy that logs every tool call with timing and token estimates. Sits between Claude Desktop and the MCP server.

# Build
go build -ldflags="-s -w" -trimpath -o mcp-proxy.exe ./cmd/proxy/

# Claude Desktop config — wrap the MCP server with the proxy
# "command": "mcp-proxy.exe",
# "args": ["--model", "sonnet-4", "--log-dir", "C:\\logs\\mcp-proxy", "--", "filesystem-ultra-v4.exe", ...]

Point the dashboard at the proxy logs to see the Proxy / Tokens page:

dashboard.exe --log-dir=C:\logs\mcp-filesystem --proxy-log-dir=C:\logs\mcp-proxy --port=9100

See docs/setup/DASHBOARD_PROXY_SETUP.md for full setup guide.

Audit Logging

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

  • operations.jsonl — JSON Lines audit log (one entry per tool call, auto-rotates at 10MB)
  • metrics.json — Performance metrics snapshot (updated every 30 seconds)

Architecture

main.go                     Entry point — config, CLI flags, server startup (~250 lines)
audit.go                    auditWrap — request normalization + audit logging
format.go                   Response formatters, parseSize, truncateContent, formatSize
help_content.go             getHelpContent() — static help text for all topics
tools_core.go               toolRegistry, registerTools, read_file/write_file/edit_file
tools_search.go             list_directory, search_files, analyze_operation
tools_files.go              create_directory, delete_file, move_file, copy_file, get_file_info
tools_batch.go              multi_edit, batch_operations, backup
tools_platform.go           wsl, server_info
tools_aliases.go            6 aliases, fs super-tool, help tool
core/
  engine.go                 UltraFastEngine — central struct, cache, worker pool, metrics
  edit_operations.go        EditFile, MultiEdit — backup, risk assessment, hooks
  file_operations.go        Rename, SoftDelete, Copy, Move
  streaming_operations.go   StreamingWrite, ChunkedRead, SmartEdit
  search_operations.go      SmartSearch, AdvancedTextSearch
  backup_manager.go         Create, restore, compare, and clean backups
  impact_analyzer.go        Risk assessment (LOW / MEDIUM / HIGH / CRITICAL)
  edit_safety_layer.go      Context validation, stale-edit prevention
  hooks.go                  Pre/post hook system (12 event types)
  large_file_processor.go   Line-by-line and chunk-based processing
  regex_transformer.go      Regex transformations with capture groups
  pipeline.go               Multi-step pipeline execution (sequential + parallel)
  pipeline_types.go         Pipeline types, validation
  pipeline_conditions.go    9 condition types for conditional steps
  pipeline_templates.go     {{step_id.field}} template resolution
  pipeline_scheduler.go     DAG builder, topological sort, destructive step splitting
  batch_operations.go       Atomic batch operations with rollback
  batch_rename.go           Batch file renaming
  audit_logger.go           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)
  path_converter.go         WSL ↔ Windows path conversion
  path_detector.go          Path format detection and WSL distro lookup
  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                 Thresholds and constants
  errors.go                 PathError, ValidationError, EditError, PipelineStepError, etc.
cache/
  intelligent.go            BigCache (files) + go-cache (dirs + metadata)
cmd/
  proxy/
    main.go                 Stdio proxy — logs tool calls, timing, token estimates
  dashboard/
    main.go                 HTTP dashboard for logs/metrics/backups
    static/                 Embedded web UI (go:embed)
tests/
  mcp_functions_test.go     Core MCP function tests
  bug5_test.go–bug9_test.go Regression tests
  edit_safety_test.go       Edit safety validation tests
  security/                 Security & fuzzing tests

File size thresholds

ClassSizeStrategy
Small< 100 KBDirect I/O
Medium< 500 KBStreaming
Large< 5 MBChunking
Very large< 50 MBSpecial handling
Over limit≥ 50 MBEdit rejected

Security

  • IsPathAllowed() resolves symlinks via filepath.EvalSymlinks() before containment check — prevents symlink escape from allowed paths
  • Allowed-path root protection (v4.2.1) — delete_file, soft_delete, and move_file reject the --allowed-paths root itself, preventing os.RemoveAll() from wiping an entire tree
  • Strict parameter validation — unknown params rejected, types enforced (core/param_validator.go)
  • Temp files and backup IDs use crypto/rand (not timestamps)
  • Backup IDs are sanitized to [a-zA-Z0-9_-] to prevent path traversal
  • Temp files and backup metadata written with 0600 permissions
  • copyDirectory() skips symlinks
  • No unsafe package usage in production code

Dependencies

PackageVersionPurpose
github.com/mark3labs/mcp-gov0.44.1MCP server SDK
github.com/allegro/bigcache/v3v3.1.0File content cache
github.com/patrickmn/go-cachev2.1.0Directory and metadata cache
github.com/panjf2000/ants/v2v2.11.5Goroutine pool
github.com/fsnotify/fsnotifyv1.9.0File system event watching

Documentation

Full documentation at filesystem.scopweb.com.

Changelog

See CHANGELOG.md for the full version history.

Current release: v4.2.1 — allowed-path root protection, main.go split, dry_run fix.


License

MIT

Ver o original no GitHub

Bom para

Relacionados