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. To use this editor with Claude.app, add the following configuration to your prompt: MCP Text Editor Server is designed to facilitate safe and efficient line-based text file operations in a cl
Add this skill
npx mdskills install tumf/mcp-text-editorComprehensive line-oriented text editor with token-efficient partial file access and robust conflict detection
1# MCP Text Editor Server23[](https://codecov.io/gh/tumf/mcp-text-editor)4[](https://smithery.ai/server/mcp-text-editor)5[](https://glama.ai/mcp/servers/k44dnvso10)67A 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.89## Quick Start for Claude.app Users1011To use this editor with Claude.app, add the following configuration to your prompt:1213```shell14code ~/Library/Application\ Support/Claude/claude_desktop_config.json15```1617```json18{19 "mcpServers": {20 "text-editor": {21 "command": "uvx",22 "args": [23 "mcp-text-editor"24 ]25 }26 }27}28```2930## Overview3132MCP 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.3334### Key Benefits3536- Line-based editing operations37- Token-efficient partial file access with line-range specifications38- Optimized for LLM tool integration39- Safe concurrent editing with hash-based validation40- Atomic multi-file operations41- Robust error handling with custom error types42- Comprehensive encoding support (utf-8, shift_jis, latin1, etc.)4344## Features4546- Line-oriented text file editing and reading47- Smart partial file access to minimize token usage in LLM applications48- Get text file contents with line range specification49- Read multiple ranges from multiple files in a single operation50- Line-based patch application with correct handling of line number shifts51- Edit text file contents with conflict detection52- Flexible character encoding support (utf-8, shift_jis, latin1, etc.)53- Support for multiple file operations54- Proper handling of concurrent edits with hash-based validation55- Memory-efficient processing of large files5657## Requirements5859- Python 3.11 or higher60- POSIX-compliant operating system (Linux, macOS, etc.) or Windows61- Sufficient disk space for text file operations62- File system permissions for read/write operations63641. Install Python 3.11+6566```bash67pyenv install 3.11.668pyenv local 3.11.669```70712. Install uv (recommended) or pip7273```bash74curl -LsSf https://astral.sh/uv/install.sh | sh75```76773. Create virtual environment and install dependencies7879```bash80uv venv81source .venv/bin/activate # On Windows: .venv\Scripts\activate82uv pip install -e ".[dev]"83```8485## Requirements8687- Python 3.13+88- POSIX-compliant operating system (Linux, macOS, etc.) or Windows89- File system permissions for read/write operations9091## Installation9293### Run via uvx9495```bash96uvx mcp-text-editor97```9899### Installing via Smithery100101To install Text Editor Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-text-editor):102103```bash104npx -y @smithery/cli install mcp-text-editor --client claude105```106107### Manual Installation1081091. Install Python 3.13+110111```bash112pyenv install 3.13.0113pyenv local 3.13.0114```1151162. Install uv (recommended) or pip117118```bash119curl -LsSf https://astral.sh/uv/install.sh | sh120```1211223. Create virtual environment and install dependencies123124```bash125uv venv126source .venv/bin/activate # On Windows: .venv\Scripts\activate127uv pip install -e ".[dev]"128```129130## Usage131132Start the server:133134```bash135python -m mcp_text_editor136```137138### MCP Tools139140The server provides several tools for text file manipulation:141142#### get_text_file_contents143144Get the contents of one or more text files with line range specification.145146**Single Range Request:**147148```json149{150 "file_path": "path/to/file.txt",151 "line_start": 1,152 "line_end": 10,153 "encoding": "utf-8" // Optional, defaults to utf-8154}155```156157**Multiple Ranges Request:**158159```json160{161 "files": [162 {163 "file_path": "file1.txt",164 "ranges": [165 {"start": 1, "end": 10},166 {"start": 20, "end": 30}167 ],168 "encoding": "shift_jis" // Optional, defaults to utf-8169 },170 {171 "file_path": "file2.txt",172 "ranges": [173 {"start": 5, "end": 15}174 ]175 }176 ]177}178```179180Parameters:181- `file_path`: Path to the text file182- `line_start`/`start`: Line number to start from (1-based)183- `line_end`/`end`: Line number to end at (inclusive, null for end of file)184- `encoding`: File encoding (default: "utf-8"). Specify the encoding of the text file (e.g., "shift_jis", "latin1")185186**Single Range Response:**187188```json189{190 "contents": "File contents",191 "line_start": 1,192 "line_end": 10,193 "hash": "sha256-hash-of-contents",194 "file_lines": 50,195 "file_size": 1024196}197```198199**Multiple Ranges Response:**200201```json202{203 "file1.txt": [204 {205 "content": "Lines 1-10 content",206 "start": 1,207 "end": 10,208 "hash": "sha256-hash-1",209 "total_lines": 50,210 "content_size": 512211 },212 {213 "content": "Lines 20-30 content",214 "start": 20,215 "end": 30,216 "hash": "sha256-hash-2",217 "total_lines": 50,218 "content_size": 512219 }220 ],221 "file2.txt": [222 {223 "content": "Lines 5-15 content",224 "start": 5,225 "end": 15,226 "hash": "sha256-hash-3",227 "total_lines": 30,228 "content_size": 256229 }230 ]231}232```233234#### patch_text_file_contents235236Apply patches to text files with robust error handling and conflict detection. Supports editing multiple files in a single operation.237238**Request Format:**239240```json241{242 "files": [243 {244 "file_path": "file1.txt",245 "hash": "sha256-hash-from-get-contents",246 "encoding": "utf-8", // Optional, defaults to utf-8247 "patches": [248 {249 "start": 5,250 "end": 8,251 "range_hash": "sha256-hash-of-content-being-replaced",252 "contents": "New content for lines 5-8\n"253 },254 {255 "start": 15,256 "end": null, // null means end of file257 "range_hash": "sha256-hash-of-content-being-replaced",258 "contents": "Content to append\n"259 }260 ]261 }262 ]263}264```265266Important Notes:2671. Always get the current hash and range_hash using get_text_file_contents before editing2682. Patches are applied from bottom to top to handle line number shifts correctly2693. Patches must not overlap within the same file2704. Line numbers are 1-based2715. `end: null` can be used to append content to the end of file2726. File encoding must match the encoding used in get_text_file_contents273274**Success Response:**275276```json277{278 "file1.txt": {279 "result": "ok",280 "hash": "sha256-hash-of-new-contents"281 }282}283```284285**Error Response with Hints:**286287```json288{289 "file1.txt": {290 "result": "error",291 "reason": "Content hash mismatch",292 "suggestion": "get", // Suggests using get_text_file_contents293 "hint": "Please run get_text_file_contents first to get current content and hashes"294 }295}296```297298 "result": "error",299 "reason": "Content hash mismatch - file was modified",300 "hash": "current-hash",301 "content": "Current file content"302303 }304}305306```307308### Common Usage Pattern3093101. Get current content and hash:311312```python313contents = await get_text_file_contents({314 "files": [315 {316 "file_path": "file.txt",317 "ranges": [{"start": 1, "end": null}] # Read entire file318 }319 ]320})321```3223232. Edit file content:324325```python326result = await edit_text_file_contents({327 "files": [328 {329 "path": "file.txt",330 "hash": contents["file.txt"][0]["hash"],331 "encoding": "utf-8", # Optional, defaults to "utf-8"332 "patches": [333 {334 "line_start": 5,335 "line_end": 8,336 "contents": "New content\n"337 }338 ]339 }340 ]341})342```3433443. Handle conflicts:345346```python347if result["file.txt"]["result"] == "error":348 if "hash mismatch" in result["file.txt"]["reason"]:349 # File was modified by another process350 # Get new content and retry351 pass352```353354### Error Handling355356The server handles various error cases:357- File not found358- Permission errors359- Hash mismatches (concurrent edit detection)360- Invalid patch ranges361- Overlapping patches362- Encoding errors (when file cannot be decoded with specified encoding)363- Line number out of bounds364365## Security Considerations366367- File Path Validation: The server validates all file paths to prevent directory traversal attacks368- Access Control: Proper file system permissions should be set to restrict access to authorized directories369- Hash Validation: All file modifications are validated using SHA-256 hashes to prevent race conditions370- Input Sanitization: All user inputs are properly sanitized and validated371- Error Handling: Sensitive information is not exposed in error messages372373## Troubleshooting374375### Common Issues3763771. Permission Denied378 - Check file and directory permissions379 - Ensure the server process has necessary read/write access3803812. Hash Mismatch and Range Hash Errors382 - The file was modified by another process383 - Content being replaced has changed384 - Run get_text_file_contents to get fresh hashes3853863. Encoding Issues387 - Verify file encoding matches the specified encoding388 - Use utf-8 for new files389 - Check for BOM markers in files3903914. Connection Issues392 - Verify the server is running and accessible393 - Check network configuration and firewall settings3943955. Performance Issues396 - Consider using smaller line ranges for large files397 - Monitor system resources (memory, disk space)398 - Use appropriate encoding for file type399400## Development401402### Setup4034041. Clone the repository4052. Create and activate a Python virtual environment4063. Install development dependencies: `uv pip install -e ".[dev]"`4074. Run tests: `make all`408409### Code Quality Tools410411- Ruff for linting412- Black for code formatting413- isort for import sorting414- mypy for type checking415- pytest-cov for test coverage416417### Testing418419Tests are located in the `tests` directory and can be run with pytest:420421```bash422# Run all tests423pytest424425# Run tests with coverage report426pytest --cov=mcp_text_editor --cov-report=term-missing427428# Run specific test file429pytest tests/test_text_editor.py -v430```431432Current test coverage: 90%433434### Project Structure435436```437mcp-text-editor/438├── mcp_text_editor/439│ ├── __init__.py440│ ├── __main__.py # Entry point441│ ├── models.py # Data models442│ ├── server.py # MCP Server implementation443│ ├── service.py # Core service logic444│ └── text_editor.py # Text editor functionality445├── tests/ # Test files446└── pyproject.toml # Project configuration447```448449## License450451MIT452453## Contributing4544551. Fork the repository4562. Create a feature branch4573. Make your changes4584. Run tests and code quality checks4595. Submit a pull request460461### Type Hints462463This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.464465### Error Handling466467All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.468469### Testing470471New features should include appropriate tests. Try to maintain or improve the current test coverage.472473### Code Style474475All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.476
Full transparency — inspect the skill content before installing.