fast-filesystem-mcp

Reads files larger than Claude's context window (200KB default) by automatically splitting responses into chunks with continuation tokens, allowing sequential retrieval without re-reading. Uses ResponseSizeMonitor to track response size in real-time and ContinuationTokenManager to maintain state across multiple tool calls, enabling Claude to request the next chunk via a token-based continuation pattern rather than offset-based pagination.

Writes file content with automatic backup creation before modification, enabling rollback on failure. Uses CREATE_BACKUP_FILES flag to create timestamped backup copies in a .backups directory, analyzeEditRisk() to assess write safety before committing, and atomic write patterns (write-to-temp-then-rename) to prevent partial writes. Supports append, overwrite, and insert modes with configurable backup retention.

Implements the Model Context Protocol (MCP) server specification, handling tool discovery, tool invocation, and response formatting according to MCP standards. Uses @modelcontextprotocol/sdk for protocol compliance, with 42+ tools registered via ListToolsRequestSchema and executed via CallToolRequestSchema. Supports both stdio and HTTP transport mechanisms with automatic protocol negotiation.

Provides stdio-based transport for Claude Desktop integration, allowing the MCP server to communicate with Claude via standard input/output streams. Implements bidirectional JSON-RPC messaging over stdio, with automatic connection handling and graceful shutdown. Configured via Claude Desktop's configuration file with server startup command and environment variables.

Provides HTTP API wrapper around the MCP server, enabling web-based access to filesystem operations via REST endpoints. Implements request routing, JSON request/response handling, and CORS support for cross-origin requests. Deployable to Vercel as a serverless function with automatic scaling, supporting both local development and cloud deployment.

Creates new files with optional template content, supporting both empty file creation and content-based initialization. Validates file paths for safety, creates parent directories if needed, and supports multiple content sources (string, Buffer, template expansion). Includes automatic backup of existing files if overwrite is requested.

Deletes files and directories with pre-deletion validation, optional trash/recycle bin support (instead of permanent deletion), and confirmation requirements for large deletions. Implements recursive directory deletion with safety checks to prevent accidental data loss, and supports dry-run mode to preview deletions before execution.

Copies files and directories recursively with configurable merge strategies for handling existing files (skip, overwrite, merge, error). Supports selective copying via file type filtering, preserves file permissions and timestamps, and includes progress tracking for large copy operations. Implements atomic copy semantics with rollback on failure.

Moves files and directories with atomic rename semantics where possible, falling back to copy-then-delete for cross-filesystem moves. Handles existing file conflicts with configurable strategies, preserves file metadata, and supports batch moves. Validates source and destination paths for safety before execution.

Monitors response size in real-time as tools execute, automatically chunking responses that exceed Claude's context window limit (200KB default). Uses ResponseSizeMonitor to track serialized response size and ContinuationTokenManager to generate tokens for resuming chunked responses. Implements transparent chunking without requiring tool-level awareness of size limits.

Enforces filesystem access boundaries by validating all file operations against a whitelist of allowed directories using isPathAllowed() and safePath() functions. Prevents directory traversal attacks and unauthorized access by resolving symlinks, normalizing paths, and checking against ALLOWED_DIRECTORIES configuration. All 42+ tools validate paths before execution, blocking operations outside permitted scopes.

Performs high-performance regex and literal string searches across codebases using ripgrep (rg) as the underlying engine, with configurable context lines (before/after match). Returns structured results including file paths, line numbers, matched content, and surrounding context. Supports regex patterns, case-insensitive matching, and file type filtering, with results automatically limited to prevent context overflow.

Provides two complementary text editing modes: block-based editing (replace arbitrary text blocks by matching start/end markers) and line-based editing (insert/replace/delete specific line ranges). Uses string matching for block identification and line number indexing for line operations, with both modes supporting multi-line content and automatic whitespace handling. Includes validation to prevent overlapping edits and risk analysis before execution.

Generates human-readable directory tree representations with configurable depth, file filtering, and pagination for large directories. Uses recursive directory traversal with depth limiting to prevent infinite recursion on circular symlinks, and implements cursor-based pagination to handle directories with thousands of entries. Supports filtering by file type, size, and modification time, with tree formatting optimized for Claude's text rendering.

Executes multiple file operations (copy, move, delete, create) as a coordinated batch with atomic semantics and rollback capability. Validates all operations before execution, creates backups of affected files, and rolls back all changes if any operation fails. Uses a transaction-like pattern with pre-flight validation, execution, and post-execution verification, preventing partial batch completion.

Creates and extracts compressed archives in multiple formats (tar, tar.gz, tar.bz2) with directory synchronization capabilities. Uses Node.js tar library for archive manipulation and supports streaming extraction to handle large archives without loading into memory. Includes integrity verification and automatic format detection based on file extension.

Retrieves comprehensive file and directory metadata including size, modification time, permissions, ownership, and type information. Uses fs.stat() and fs.statSync() for efficient metadata access, with special handling for symlinks (both resolved and unresolved stats). Returns structured metadata objects optimized for Claude's analysis, including human-readable size formatting and permission strings.

Compares two files and generates unified diff output showing additions, deletions, and modifications with configurable context lines. Uses line-by-line comparison with optional binary file detection, and formats output as unified diff (compatible with patch tools). Supports comparing files, directories (recursive), and stdin/file combinations.