Skip to content
Back to search

mcp-text-editor

A token-efficient MCP server for safe, line-oriented text file editing with partial reads, hash-based conflict detection, and atomic multi-file operations.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tumf--mcp-text-editor/badge.svg)](/listings/tumf--mcp-text-editor)

HTML

<a href="/listings/tumf--mcp-text-editor"><img src="/api/listings/tumf--mcp-text-editor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

To use this editor with Claude.app, add the following configuration to your prompt:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "text-editor": {
      "command": "uvx",
      "args": [
        "mcp-text-editor"
      ]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 403 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Text Editor Server
  2. [![codecov](https://codecov.io/gh/tumf/mcp-text-editor/branch/main/graph/badge.svg?token=52D51U0ZUR)](https://codecov.io/gh/tumf/mcp-text-editor)
  3. [![smithery badge](https://smithery.ai/badge/mcp-text-editor)](https://smithery.ai/server/mcp-text-editor)
  4. [![Glama MCP Server](https://glama.ai/mcp/servers/k44dnvso10/badge)](https://glama.ai/mcp/servers/k44dnvso10)
  5. 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.
  6. ## Quick Start for Claude.app Users
  7. To use this editor with Claude.app, add the following configuration to your prompt:
  8. ```shell
  9. code ~/Library/Application\ Support/Claude/claude_desktop_config.json
  10. ```
  11. ```json
  12. {
  13. "mcpServers": {
  14. "text-editor": {
  15. "command": "uvx",
  16. "args": [
  17. "mcp-text-editor"
  18. ]
  19. }
  20. }
  21. }
  22. ```
  23. ## Overview
  24. 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.
  25. ### Key Benefits
  26. - Line-based editing operations
  27. - Token-efficient partial file access with line-range specifications
  28. - Optimized for LLM tool integration
  29. - Safe concurrent editing with hash-based validation
  30. - Atomic multi-file operations
  31. - Robust error handling with custom error types
  32. - Comprehensive encoding support (utf-8, shift_jis, latin1, etc.)
  33. ## Features
  34. - Line-oriented text file editing and reading
  35. - Smart partial file access to minimize token usage in LLM applications
  36. - Get text file contents with line range specification
  37. - Read multiple ranges from multiple files in a single operation
  38. - Line-based patch application with correct handling of line number shifts
  39. - Edit text file contents with conflict detection
  40. - Flexible character encoding support (utf-8, shift_jis, latin1, etc.)
  41. - Support for multiple file operations
  42. - Proper handling of concurrent edits with hash-based validation
  43. - Memory-efficient processing of large files
  44. ## Requirements
  45. - Python 3.11 or higher
  46. - POSIX-compliant operating system (Linux, macOS, etc.) or Windows
  47. - Sufficient disk space for text file operations
  48. - File system permissions for read/write operations
  49. 1. Install Python 3.11+
  50. ```bash
  51. pyenv install 3.11.6
  52. pyenv local 3.11.6
  53. ```
  54. 2. Install uv (recommended) or pip
  55. ```bash
  56. curl -LsSf https://astral.sh/uv/install.sh | sh
  57. ```
  58. 3. Create virtual environment and install dependencies
  59. ```bash
  60. uv venv
  61. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  62. uv pip install -e ".[dev]"
  63. ```
  64. ## Requirements
  65. - Python 3.13+
  66. - POSIX-compliant operating system (Linux, macOS, etc.) or Windows
  67. - File system permissions for read/write operations
  68. ## Installation
  69. ### Run via uvx
  70. ```bash
  71. uvx mcp-text-editor
  72. ```
  73. ### Installing via Smithery
  74. To install Text Editor Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-text-editor):
  75. ```bash
  76. npx -y @smithery/cli install mcp-text-editor --client claude
  77. ```
  78. ### Manual Installation
  79. 1. Install Python 3.13+
  80. ```bash
  81. pyenv install 3.13.0
  82. pyenv local 3.13.0
  83. ```
  84. 2. Install uv (recommended) or pip
  85. ```bash
  86. curl -LsSf https://astral.sh/uv/install.sh | sh
  87. ```
  88. 3. Create virtual environment and install dependencies
  89. ```bash
  90. uv venv
  91. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  92. uv pip install -e ".[dev]"
  93. ```
  94. ## Usage
  95. Start the server:
  96. ```bash
  97. python -m mcp_text_editor
  98. ```
  99. ### MCP Tools
  100. The server provides several tools for text file manipulation:
  101. #### get_text_file_contents
  102. Get the contents of one or more text files with line range specification.
  103. **Request:**
  104. The tool accepts a `files` array. Each file contains one or more line ranges using
  105. `start` and `end`. File paths must be absolute.
  106. ```json
  107. {
  108. "files": [
  109. {
  110. "file_path": "/absolute/path/to/file.txt",
  111. "ranges": [
  112. {"start": 1, "end": 10},
  113. {"start": 20, "end": null}
  114. ]
  115. }
  116. ],
  117. "encoding": "utf-8"
  118. }
  119. ```
  120. Parameters:
  121. - `file_path`: Absolute path to the text file
  122. - `start`: First line to read (1-based)
  123. - `end`: Last line to read (inclusive); `null` reads through end of file
  124. - `encoding`: File encoding for all requested files (default: `utf-8`)
  125. **Response:**
  126. The top-level object is keyed by absolute file path. `file_hash` protects the
  127. whole-file state; each `range_hash` protects the corresponding range.
  128. ```json
  129. {
  130. "/absolute/path/to/file.txt": {
  131. "file_hash": "sha256-hash-of-the-file",
  132. "ranges": [
  133. {
  134. "content": "Lines 1-10 content",
  135. "start": 1,
  136. "end": 10,
  137. "range_hash": "sha256-hash-of-this-range",
  138. "total_lines": 50,
  139. "content_size": 512
  140. }
  141. ]
  142. }
  143. }
  144. ```
  145. #### patch_text_file_contents
  146. Apply one or more non-overlapping patches to one file. Read the target ranges
  147. first and pass both the current `file_hash` and each matching `range_hash`.
  148. **Request:**
  149. ```json
  150. {
  151. "file_path": "/absolute/path/to/file.txt",
  152. "file_hash": "sha256-hash-from-get-response",
  153. "patches": [
  154. {
  155. "start": 5,
  156. "end": 8,
  157. "range_hash": "sha256-hash-of-lines-5-through-8",
  158. "contents": "New content for lines 5-8\n"
  159. }
  160. ],
  161. "encoding": "utf-8"
  162. }
  163. ```
  164. Important notes:
  165. 1. Obtain current hashes with `get_text_file_contents` immediately before editing.
  166. 2. Use `start` and `end`; `line_start` and `line_end` are not accepted.
  167. 3. Patches are applied from bottom to top and must not overlap.
  168. 4. Line numbers are 1-based.
  169. 5. Use `append_text_file_contents`, `insert_text_file_contents`, or
  170. `delete_text_file_contents` for those specialized operations.
  171. 6. Use the same encoding for the read and patch calls.
  172. **Success response:**
  173. ```json
  174. {
  175. "result": "ok",
  176. "file_hash": "sha256-hash-of-new-file-contents",
  177. "reason": null,
  178. "suggestion": null,
  179. "hint": null
  180. }
  181. ```
  182. **Error response:**
  183. ```json
  184. {
  185. "result": "error",
  186. "reason": "Content range hash mismatch",
  187. "suggestion": "get",
  188. "hint": "Please run get_text_file_contents first to get current content and hashes"
  189. }
  190. ```
  191. ### Common Usage Pattern
  192. 1. Call `get_text_file_contents` for the exact range to replace.
  193. 2. Read `file_hash` and the range's `range_hash` from the keyed response.
  194. 3. Call `patch_text_file_contents` with those hashes and the same range.
  195. 4. If the result is an error, read the file again before retrying.
  196. ```python
  197. path = "/absolute/path/to/file.txt"
  198. contents = await get_text_file_contents({
  199. "files": [{
  200. "file_path": path,
  201. "ranges": [{"start": 5, "end": 8}]
  202. }]
  203. })
  204. file_info = contents[path]
  205. selected_range = file_info["ranges"][0]
  206. result = await patch_text_file_contents({
  207. "file_path": path,
  208. "file_hash": file_info["file_hash"],
  209. "patches": [{
  210. "start": 5,
  211. "end": 8,
  212. "range_hash": selected_range["range_hash"],
  213. "contents": "New content\n"
  214. }]
  215. })
  216. ```
  217. ### Error Handling
  218. The server handles various error cases:
  219. - File not found
  220. - Permission errors
  221. - Hash mismatches (concurrent edit detection)
  222. - Invalid patch ranges
  223. - Overlapping patches
  224. - Encoding errors (when file cannot be decoded with specified encoding)
  225. - Line number out of bounds
  226. ## Security Considerations
  227. - File Path Validation: The server validates all file paths to prevent directory traversal attacks
  228. - Access Control: Proper file system permissions should be set to restrict access to authorized directories
  229. - Hash Validation: All file modifications are validated using SHA-256 hashes to prevent race conditions
  230. - Input Sanitization: All user inputs are properly sanitized and validated
  231. - Error Handling: Sensitive information is not exposed in error messages
  232. ## Troubleshooting
  233. ### Common Issues
  234. 1. Permission Denied
  235. - Check file and directory permissions
  236. - Ensure the server process has necessary read/write access
  237. 2. Hash Mismatch and Range Hash Errors
  238. - The file was modified by another process
  239. - Content being replaced has changed
  240. - Run get_text_file_contents to get fresh hashes
  241. 3. Encoding Issues
  242. - Verify file encoding matches the specified encoding
  243. - Use utf-8 for new files
  244. - Check for BOM markers in files
  245. 4. Connection Issues
  246. - Verify the server is running and accessible
  247. - Check network configuration and firewall settings
  248. 5. Performance Issues
  249. - Consider using smaller line ranges for large files
  250. - Monitor system resources (memory, disk space)
  251. - Use appropriate encoding for file type
  252. ## Development
  253. ### Setup
  254. 1. Clone the repository
  255. 2. Create and activate a Python virtual environment
  256. 3. Install development dependencies: `uv pip install -e ".[dev]"`
  257. 4. Run tests: `make all`
  258. ### Code Quality Tools
  259. - Ruff for linting
  260. - Black for code formatting
  261. - isort for import sorting
  262. - mypy for type checking
  263. - pytest-cov for test coverage
  264. ### Testing
  265. Tests are located in the `tests` directory and can be run with pytest:
  266. ```bash
  267. # Run all tests
  268. pytest
  269. # Run tests with coverage report
  270. pytest --cov=mcp_text_editor --cov-report=term-missing
  271. # Run specific test file
  272. pytest tests/test_text_editor.py -v
  273. ```
  274. Current test coverage: 90%
  275. ### Project Structure
  276. ```
  277. mcp-text-editor/
  278. ├── mcp_text_editor/
  279. │ ├── __init__.py
  280. │ ├── __main__.py # Entry point
  281. │ ├── models.py # Data models
  282. │ ├── server.py # MCP Server implementation
  283. │ ├── service.py # Core service logic
  284. │ └── text_editor.py # Text editor functionality
  285. ├── tests/ # Test files
  286. └── pyproject.toml # Project configuration
  287. ```
  288. ## License
  289. MIT
  290. ## Contributing
  291. 1. Fork the repository
  292. 2. Create a feature branch
  293. 3. Make your changes
  294. 4. Run tests and code quality checks
  295. 5. Submit a pull request
  296. ### Type Hints
  297. This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.
  298. ### Error Handling
  299. All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.
  300. ### Testing
  301. New features should include appropriate tests. Try to maintain or improve the current test coverage.
  302. ### Code Style
  303. All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.