MCP Text Editor Server
A Model Context Protocol (MCP) server that provides line-oriented text file editing capabilities through a standardized API. Optimized for LLM tools with efficient partial file access to minimize token usage.
Quick Start for Claude.app Users
To use this editor with Claude.app, add the following configuration to your prompt:
or with docker:
Overview
MCP Text Editor Server is designed to facilitate safe and efficient line-based text file operations in a client-server architecture. It implements the Model Context Protocol, ensuring reliable file editing with robust conflict detection and resolution. The line-oriented approach makes it ideal for applications requiring synchronized file access, such as collaborative editing tools, automated text processing systems, or any scenario where multiple processes need to modify text files safely. The partial file access capability is particularly valuable for LLM-based tools, as it helps reduce token consumption by loading only the necessary portions of files.
Key Benefits
- Line-based editing operations
- Token-efficient partial file access with line-range specifications
- Optimized for LLM tool integration
- Safe concurrent editing with hash-based validation
- Atomic multi-file operations
- Robust error handling with custom error types
- Comprehensive encoding support (utf-8, shift_jis, latin1, etc.)
Features
- Line-oriented text file editing and reading
- Smart partial file access to minimize token usage in LLM applications
- Get text file contents with line range specification
- Read multiple ranges from multiple files in a single operation
- Line-based patch application with correct handling of line number shifts
- Edit text file contents with conflict detection
- Flexible character encoding support (utf-8, shift_jis, latin1, etc.)
- Support for multiple file operations
- Proper handling of concurrent edits with hash-based validation
- Memory-efficient processing of large files
Requirements
- Python 3.11 or higher
- POSIX-compliant operating system (Linux, macOS, etc.) or Windows
- Sufficient disk space for text file operations
- File system permissions for read/write operations
- Install Python 3.11+
- Install uv (recommended) or pip
- Create virtual environment and install dependencies
Requirements
- Python 3.13+
- POSIX-compliant operating system (Linux, macOS, etc.) or Windows
- File system permissions for read/write operations
Installation
Run via uvx
Installing via Smithery
To install Text Editor Server for Claude Desktop automatically via Smithery:
Manual Installation
- Install Python 3.13+
Docker Installation
- Install uv (recommended) or pip
- Create virtual environment and install dependencies
Usage
Start the server:
Start the server with docker:
with inspector:
MCP Tools
The server provides several tools for text file manipulation:
get_text_file_contents
Get the contents of one or more text files with line range specification.
Single Range Request:
Multiple Ranges Request:
Parameters:
file_path: Path to the text file
line_start/start: Line number to start from (1-based)
line_end/end: Line number to end at (inclusive, null for end of file)
encoding: File encoding (default: "utf-8"). Specify the encoding of the text file (e.g., "shift_jis", "latin1")
Single Range Response:
Multiple Ranges Response:
patch_text_file_contents
Apply patches to text files with robust error handling and conflict detection. Supports editing multiple files in a single operation.
Request Format:
Important Notes:
- Always get the current hash and range_hash using get_text_file_contents before editing
- Patches are applied from bottom to top to handle line number shifts correctly
- Patches must not overlap within the same file
- Line numbers are 1-based
end: nullcan be used to append content to the end of file
- File encoding must match the encoding used in get_text_file_contents
Success Response:
Error Response with Hints:
}
}
- Edit file content:
- Handle conflicts:
Error Handling
The server handles various error cases:
- File not found
- Permission errors
- Hash mismatches (concurrent edit detection)
- Invalid patch ranges
- Overlapping patches
- Encoding errors (when file cannot be decoded with specified encoding)
- Line number out of bounds
Security Considerations
- File Path Validation: The server validates all file paths to prevent directory traversal attacks
- Access Control: Proper file system permissions should be set to restrict access to authorized directories
- Hash Validation: All file modifications are validated using SHA-256 hashes to prevent race conditions
- Input Sanitization: All user inputs are properly sanitized and validated
- Error Handling: Sensitive information is not exposed in error messages
Troubleshooting
Common Issues
- Permission Denied
- Hash Mismatch and Range Hash Errors
- Encoding Issues
- Connection Issues
- Performance Issues
Development
Setup
- Clone the repository
- Create and activate a Python virtual environment
- Install development dependencies:
uv pip install -e ".[dev]"
- Run tests:
make all
Code Quality Tools
- Ruff for linting
- Black for code formatting
- isort for import sorting
- mypy for type checking
- pytest-cov for test coverage
Testing
Tests are located in the
tests directory and can be run with pytest:Current test coverage: 90%
Project Structure
License
MIT
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and code quality checks
- Submit a pull request
Type Hints
This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.
Error Handling
All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.
Testing
New features should include appropriate tests. Try to maintain or improve the current test coverage.
Code Style
All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.
MCP Text Editor Server
A Model Context Protocol (MCP) server that provides line-oriented text file editing capabilities through a standardized API. Optimized for LLM tools with efficient partial file access to minimize token usage.
Quick Start for Claude.app Users
To use this editor with Claude.app, add the following configuration to your prompt:
or with docker:
Overview
MCP Text Editor Server is designed to facilitate safe and efficient line-based text file operations in a client-server architecture. It implements the Model Context Protocol, ensuring reliable file editing with robust conflict detection and resolution. The line-oriented approach makes it ideal for applications requiring synchronized file access, such as collaborative editing tools, automated text processing systems, or any scenario where multiple processes need to modify text files safely. The partial file access capability is particularly valuable for LLM-based tools, as it helps reduce token consumption by loading only the necessary portions of files.
Key Benefits
- Line-based editing operations
- Token-efficient partial file access with line-range specifications
- Optimized for LLM tool integration
- Safe concurrent editing with hash-based validation
- Atomic multi-file operations
- Robust error handling with custom error types
- Comprehensive encoding support (utf-8, shift_jis, latin1, etc.)
Features
- Line-oriented text file editing and reading
- Smart partial file access to minimize token usage in LLM applications
- Get text file contents with line range specification
- Read multiple ranges from multiple files in a single operation
- Line-based patch application with correct handling of line number shifts
- Edit text file contents with conflict detection
- Flexible character encoding support (utf-8, shift_jis, latin1, etc.)
- Support for multiple file operations
- Proper handling of concurrent edits with hash-based validation
- Memory-efficient processing of large files
Requirements
- Python 3.11 or higher
- POSIX-compliant operating system (Linux, macOS, etc.) or Windows
- Sufficient disk space for text file operations
- File system permissions for read/write operations
- Install Python 3.11+
- Install uv (recommended) or pip
- Create virtual environment and install dependencies
Requirements
- Python 3.13+
- POSIX-compliant operating system (Linux, macOS, etc.) or Windows
- File system permissions for read/write operations
Installation
Run via uvx
Installing via Smithery
To install Text Editor Server for Claude Desktop automatically via Smithery:
Manual Installation
- Install Python 3.13+
Docker Installation
- Install uv (recommended) or pip
- Create virtual environment and install dependencies
Usage
Start the server:
Start the server with docker:
with inspector:
MCP Tools
The server provides several tools for text file manipulation:
get_text_file_contents
Get the contents of one or more text files with line range specification.
Single Range Request:
Multiple Ranges Request:
Parameters:
file_path: Path to the text file
line_start/start: Line number to start from (1-based)
line_end/end: Line number to end at (inclusive, null for end of file)
encoding: File encoding (default: "utf-8"). Specify the encoding of the text file (e.g., "shift_jis", "latin1")
Single Range Response:
Multiple Ranges Response:
patch_text_file_contents
Apply patches to text files with robust error handling and conflict detection. Supports editing multiple files in a single operation.
Request Format:
Important Notes:
- Always get the current hash and range_hash using get_text_file_contents before editing
- Patches are applied from bottom to top to handle line number shifts correctly
- Patches must not overlap within the same file
- Line numbers are 1-based
end: nullcan be used to append content to the end of file
- File encoding must match the encoding used in get_text_file_contents
Success Response:
Error Response with Hints:
}
}
- Edit file content:
- Handle conflicts:
Error Handling
The server handles various error cases:
- File not found
- Permission errors
- Hash mismatches (concurrent edit detection)
- Invalid patch ranges
- Overlapping patches
- Encoding errors (when file cannot be decoded with specified encoding)
- Line number out of bounds
Security Considerations
- File Path Validation: The server validates all file paths to prevent directory traversal attacks
- Access Control: Proper file system permissions should be set to restrict access to authorized directories
- Hash Validation: All file modifications are validated using SHA-256 hashes to prevent race conditions
- Input Sanitization: All user inputs are properly sanitized and validated
- Error Handling: Sensitive information is not exposed in error messages
Troubleshooting
Common Issues
- Permission Denied
- Hash Mismatch and Range Hash Errors
- Encoding Issues
- Connection Issues
- Performance Issues
Development
Setup
- Clone the repository
- Create and activate a Python virtual environment
- Install development dependencies:
uv pip install -e ".[dev]"
- Run tests:
make all
Code Quality Tools
- Ruff for linting
- Black for code formatting
- isort for import sorting
- mypy for type checking
- pytest-cov for test coverage
Testing
Tests are located in the
tests directory and can be run with pytest:Current test coverage: 90%
Project Structure
License
MIT
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and code quality checks
- Submit a pull request
Type Hints
This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.
Error Handling
All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.
Testing
New features should include appropriate tests. Try to maintain or improve the current test coverage.
Code Style
All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.