Edit File Lines MCP Server
A TypeScript-based MCP server that provides tools for making precise line-based edits to text files within allowed directories.
Features
Main Editing Tool
`edit_file_lines`
Make line-based edits to a file using string or regex pattern matching. Each edit can:
- Replace entire lines
- Replace specific text matches while preserving line formatting
- Use regex patterns for complex matches
- Handle multiple lines and multiple edits
- Preview changes with dry run mode
Example file (
src/components/App.tsx):Example Use Cases
- Simple String Replacement
Output:
State ID: fcbf740a
Use this ID with approve_edit to apply the changes.
- Multi-line Content with Preserved Structure
Output:
State ID: f2ce973f
Use this ID with approve_edit to apply the changes.
- Complex JSX Structure Modification
Output:
State ID: f1f1d27b
Use this ID with approve_edit to apply the changes.
- Configuration Update with Whitespace Preservation
Output:
State ID: 20e93c34
Use this ID with approve_edit to apply the changes.
- Flexible Whitespace Matching
Output:
Additional Tools
`approve_edit`
Apply changes from a previous dry run of
edit_file_lines. This tool provides a two-step editing process for safety. Here is an example workflow:- First, make a dry run edit:
Output:
State ID: fcbf740a
Use this ID with approve_edit to apply the changes.
- Then, approve the changes using the state ID:
Output:
- Verify the changes:
Output:
Note that state IDs expire after a short time for security. Attempting to use an expired or invalid state ID will result in an error:
Output:
`get_file_lines`
Inspect specific lines in a file with optional context lines. This tool is useful for verifying line content before making edits.
Output:
`search_file`
Search a file for text patterns or regular expressions to find specific line numbers and their surrounding context. This tool is particularly useful for locating the exact lines you want to edit with
edit_file_lines.Features:
- Simple text search with optional case sensitivity
- Regular expression support
- Whole word matching
- Configurable context lines
- Returns line numbers, content, and surrounding context with line numbers
Arguments:
Example use cases:
- Simple text search:
Output:
- Case-sensitive whole word search:
Output:
- Finding JSX components:
Output:
Common workflows:
- Find then edit:
- Find all usages:
- Find specific prop patterns:
Important Notes
- Whitespace Handling
- Pattern Matching
- Best Practices
Development
Install dependencies:
Build the server:
For development with auto-rebuild:
Testing
Run the test suite:
Additional testing utilities:
Test Tools Script
Test the MCP tools directly against sample files:
This script:
- Resets test fixtures to a known state
- Connects to the MCP server
- Tests each tool in sequence:
- Shows the output of each operation
- Verifies changes were applied correctly
Reset Fixtures Script
Reset test fixtures to their original state:
Use this script to:
- Reset test files to a known state before testing
- Clean up after failed tests
- Ensure consistent test environment
- Create missing fixture directories
Usage
The server requires one or more allowed directories to be specified when starting:
All file operations will be restricted to these directories for security.
Environment Variables
MCP_EDIT_STATE_TTL: Time-to-live in milliseconds for edit states (default: 60000). Edit states will expire after this duration and must be recreated.
Installation
To use with Claude Desktop, add the server config:
On MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.jsonError Handling
The tool provides clear error messages for common issues:
- Match Not Found
- Invalid Regex
- Multiple Edits on Same Line
Security Considerations
- All file operations are restricted to explicitly allowed directories
- Symlinks are validated to prevent escaping allowed directories
- Parent directory traversal is prevented
- Path normalization is performed for consistent security checks
- Invalid line numbers and character positions are rejected
- Line ending normalization ensures consistent behavior across platforms
- Edit states expire after 60 seconds for security
- Edit approvals require exact match of file path and edits
Debugging
Use the Test Tools script to test the MCP tools directly against sample files. The MCP Inspector might help, but it currently does not support handing input that are not string values.
Edit File Lines MCP Server
A TypeScript-based MCP server that provides tools for making precise line-based edits to text files within allowed directories.
Features
Main Editing Tool
`edit_file_lines`
Make line-based edits to a file using string or regex pattern matching. Each edit can:
- Replace entire lines
- Replace specific text matches while preserving line formatting
- Use regex patterns for complex matches
- Handle multiple lines and multiple edits
- Preview changes with dry run mode
Example file (
src/components/App.tsx):Example Use Cases
- Simple String Replacement
Output:
State ID: fcbf740a
Use this ID with approve_edit to apply the changes.
- Multi-line Content with Preserved Structure
Output:
State ID: f2ce973f
Use this ID with approve_edit to apply the changes.
- Complex JSX Structure Modification
Output:
State ID: f1f1d27b
Use this ID with approve_edit to apply the changes.
- Configuration Update with Whitespace Preservation
Output:
State ID: 20e93c34
Use this ID with approve_edit to apply the changes.
- Flexible Whitespace Matching
Output:
Additional Tools
`approve_edit`
Apply changes from a previous dry run of
edit_file_lines. This tool provides a two-step editing process for safety. Here is an example workflow:- First, make a dry run edit:
Output:
State ID: fcbf740a
Use this ID with approve_edit to apply the changes.
- Then, approve the changes using the state ID:
Output:
- Verify the changes:
Output:
Note that state IDs expire after a short time for security. Attempting to use an expired or invalid state ID will result in an error:
Output:
`get_file_lines`
Inspect specific lines in a file with optional context lines. This tool is useful for verifying line content before making edits.
Output:
`search_file`
Search a file for text patterns or regular expressions to find specific line numbers and their surrounding context. This tool is particularly useful for locating the exact lines you want to edit with
edit_file_lines.Features:
- Simple text search with optional case sensitivity
- Regular expression support
- Whole word matching
- Configurable context lines
- Returns line numbers, content, and surrounding context with line numbers
Arguments:
Example use cases:
- Simple text search:
Output:
- Case-sensitive whole word search:
Output:
- Finding JSX components:
Output:
Common workflows:
- Find then edit:
- Find all usages:
- Find specific prop patterns:
Important Notes
- Whitespace Handling
- Pattern Matching
- Best Practices
Development
Install dependencies:
Build the server:
For development with auto-rebuild:
Testing
Run the test suite:
Additional testing utilities:
Test Tools Script
Test the MCP tools directly against sample files:
This script:
- Resets test fixtures to a known state
- Connects to the MCP server
- Tests each tool in sequence:
- Shows the output of each operation
- Verifies changes were applied correctly
Reset Fixtures Script
Reset test fixtures to their original state:
Use this script to:
- Reset test files to a known state before testing
- Clean up after failed tests
- Ensure consistent test environment
- Create missing fixture directories
Usage
The server requires one or more allowed directories to be specified when starting:
All file operations will be restricted to these directories for security.
Environment Variables
MCP_EDIT_STATE_TTL: Time-to-live in milliseconds for edit states (default: 60000). Edit states will expire after this duration and must be recreated.
Installation
To use with Claude Desktop, add the server config:
On MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.jsonError Handling
The tool provides clear error messages for common issues:
- Match Not Found
- Invalid Regex
- Multiple Edits on Same Line
Security Considerations
- All file operations are restricted to explicitly allowed directories
- Symlinks are validated to prevent escaping allowed directories
- Parent directory traversal is prevented
- Path normalization is performed for consistent security checks
- Invalid line numbers and character positions are rejected
- Line ending normalization ensures consistent behavior across platforms
- Edit states expire after 60 seconds for security
- Edit approvals require exact match of file path and edits
Debugging
Use the Test Tools script to test the MCP tools directly against sample files. The MCP Inspector might help, but it currently does not support handing input that are not string values.