The MCP File Editor Server is a comprehensive tool for advanced file operations, enabling reading, writing, searching, and editing of files and directories with robust error handling and comprehensive testing.
File Reading: Read entire files or specific line ranges with optional line number prefixes
Text Replacement: Replace content using regex patterns with support for single or multiple occurrences
Content Management: Delete content between specific lines, insert content at specific positions (before/after lines or at end), and replace entire line blocks
Advanced Multi-Line Editing: Perform multiple line replacements in a single operation with automatic line number adjustment
File & Directory Searching: Search for regex patterns within individual files or across directories, with context lines and include/exclude filters
Directory Operations: List files and subdirectories with size information and recursive support
Quality & Integration: Features robust error handling, path validation, content verification, and 80+ test cases for reliability. Designed for seamless integration with MCP-compatible clients via stdio.
Built on Node.js runtime environment for server execution and JavaScript-based file operations
Distributed and installed via npm package manager, with npm-based dependency management
Implemented in TypeScript providing type-safe file manipulation operations and modern JavaScript features
Uses Vitest testing framework for comprehensive test coverage of all file editing operations
Integrates Zod for schema validation of tool parameters and input validation
MCP File Editor Server
A comprehensive Model Context Protocol (MCP) server that provides advanced file operations for reading, writing, searching, and editing files. This server offers 9 powerful tools for file manipulation with robust error handling and comprehensive test coverage.
Features
Core Tools
read_file
- Read file contents with flexible optionsFull file reading or specific line ranges
Optional line number prefixes
Support for partial file reading
replace_in_file
- Regex-based string replacementSingle or multiple occurrence replacement
Complex regex pattern support
Safe replacement with occurrence limits
delete_from_file
- Remove content between line numbersLine content verification for safety
Single or multi-line deletion
Precise line range targeting
insert_into_file
- Insert content at specific positionsBefore/after line placement
End-of-file appending
Line content verification
replace_lines_in_file
- Replace content between linesMulti-line content replacement
Line content verification
Flexible content insertion
multireplace_lines_in_file
- Multiple line replacements with automatic adjustmentPerform multiple edits in a single operation
Automatic line number adjustment after each edit
Detailed success/failure reporting for each edit
Handles complex line shifting scenarios
search_file
- Search within individual filesRegex pattern matching
Context lines (before/after)
Detailed match reporting
list_files
- Directory content listingFile and directory enumeration
File size information
Recursive directory support
search_directory
- Search across multiple filesDirectory-wide regex search
Include/exclude pattern filtering
Recursive subdirectory searching
Key Features
Robust Error Handling: User-friendly error messages with actionable guidance
Path Validation: Absolute path enforcement with helpful error messages
Content Verification: Line content verification to prevent accidental edits
Comprehensive Testing: 80 test cases covering all functionality
TypeScript Implementation: Full type safety and modern JavaScript features
FastMCP Framework: Built on the FastMCP library for optimal performance
Installation
Prerequisites
Node.js 16.x or later
npm or yarn package manager
Install Dependencies
Build the Project
Usage
Cursor-compatible MCP server config
Starting the Server
The server will start and listen for MCP client connections via stdio transport.
MCP Client Integration
This server is designed to work with MCP-compatible clients. The server communicates via stdio and supports the following MCP tools:
Example Tool Usage
Testing
Run the comprehensive test suite:
The test suite includes:
73 total tests across 4 test files
Unit tests for all 8 tools
Error handling validation
Edge case coverage
Integration testing with MCP client
Test Coverage
read-file.test.ts
- 16 tests for file reading operationsediting-tools.test.ts
- 26 tests for file modification tools (including multireplace_lines_in_file)search-tools.test.ts
- 22 tests for search and directory operationsutils.test.ts
- 16 tests for utility functions
API Reference
Tool Parameters
read_file
file_path
(string, required): Absolute path to the fileshow_line_numbers
(boolean, optional): Prefix lines with numbersstart_line
(number, optional): Starting line number (1-based)end_line
(number, optional): Ending line number (1-based)full
(boolean, optional): Read entire file (mutually exclusive with line ranges)
replace_in_file
file_path
(string, required): Absolute path to the fileregex_source
(string, required): Regular expression patterntarget
(string, required): Replacement stringmultiple
(boolean, optional): Allow multiple replacements
delete_from_file
file_path
(string, required): Absolute path to the fileline_start
(number, required): Starting line numberline_end
(number, required): Ending line numberline_start_contents
(string, required): Expected content of starting line
insert_into_file
file_path
(string, required): Absolute path to the fileline_number
(number, required): Target line number (0 for end)line_contents
(string, required): Expected content of target linewhere
(enum, required): 'before' or 'after'contents
(string, required): Content to insert
replace_lines_in_file
file_path
(string, required): Absolute path to the fileline_start
(number, required): Starting line numberline_end
(number, required): Ending line numberline_start_contents
(string, required): Expected content of starting linecontents
(string, required): Replacement content
multireplace_lines_in_file
file_path
(string, required): Absolute path to the fileedits
(array, required): Array of edit operationsline_start
(number, required): Starting line number (1-based)line_end
(number, required): Ending line number (1-based)line_start_contents
(string, required): Expected content of starting linecontents
(string, required): New content to replace the lines with
search_file
file_path
(string, required): Absolute path to the fileregexp
(string, required): Regular expression patternlines_before
(number, optional): Context lines before matcheslines_after
(number, optional): Context lines after matches
list_files
directory_path
(string, required): Absolute path to the directory
search_directory
directory_path
(string, required): Absolute path to the directoryregexp
(string, required): Regular expression patternrecursive
(boolean, optional): Search subdirectorieslines_before
(number, optional): Context lines before matcheslines_after
(number, optional): Context lines after matchesinclude
(string, optional): File pattern to includeexclude
(string, optional): File/directory pattern to exclude
Error Handling
The server provides detailed error messages for common issues:
Path validation: Clear messages for relative paths and non-existent files
Content verification: Helpful guidance when line content doesn't match
File operations: Descriptive errors for read/write failures
Parameter validation: Specific guidance for invalid parameters
Contributing
Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request
License
This project is licensed under the MIT License. See LICENSE file for details.
Architecture
The server is built with:
TypeScript for type safety and modern JavaScript features
FastMCP framework for MCP protocol implementation
Zod for schema validation
Vitest for comprehensive testing
fs-extra for enhanced file system operations
The architecture follows clean separation of concerns with:
Main server implementation in
src/index.ts
Utility functions in
src/utils.ts
Comprehensive test suite with proper MCP client integration
Modular tool implementations with consistent error handling
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Enables comprehensive file operations including reading, writing, searching, and editing files with advanced features like regex-based replacements, line-specific modifications, and directory-wide search capabilities. Provides 8 robust tools for safe file manipulation with content verification and detailed error handling.
Related MCP Servers
- -securityFlicense-qualityThis server provides an interface for performing basic file system operations such as navigation, reading, writing, and file analysis, allowing users to manage directories and files efficiently.Last updated -4
- AsecurityAlicenseAqualityProvides comprehensive document processing, including reading, converting, and manipulating various document formats with advanced text and HTML processing capabilities.Last updated -162415MIT License
- AsecurityFlicenseAqualityProvides tools for making small, targeted edits to files using stream editors like sed and awk, enabling efficient modifications without full file replacement.Last updated -101
- AsecurityFlicenseAqualityEnables secure filesystem operations with directory sandboxing and optional read-only mode. Supports file reading/writing, directory management, file searching, and text operations while restricting access to specified directories.Last updated -12