Skip to content

Latest commit

 

History

History
586 lines (439 loc) · 21.4 KB

README.md

File metadata and controls

586 lines (439 loc) · 21.4 KB

Editor MCP

A Python-based text editor server built with FastMCP that provides powerful tools for file operations. This server enables reading, editing, and managing text files through a standardized API with a unique multi-step approach that significantly improves code editing accuracy and reliability for LLMs and AI assistants.

Features

  • File Selection: Set a file to work with using absolute paths
  • Read Operations:
    • Read entire files with line numbers using skim
    • Read specific line ranges with prefixed line numbers using read
    • Find specific text within files using find_line
    • Find and extract function definitions in Python and JavaScript/JSX files using find_function
  • Edit Operations:
    • Two-step editing process with diff preview
    • Select and overwrite text with ID verification
    • Clean editing workflow with select → overwrite → confirm/cancel pattern
    • Syntax checking for Python (.py) and JavaScript/React (.js, .jsx) files
    • Create new files with content
  • File Management:
    • Create new files with proper initialization
    • Delete files from the filesystem
    • List directory contents with listdir
  • Testing Support:
    • Run Python tests with run_tests
    • Set Python paths for proper module resolution
  • Safety Features:
    • Content ID verification to prevent conflicts
    • Line count limits to prevent resource exhaustion
    • Syntax checking to maintain code integrity
    • Protected paths to restrict access to sensitive files

Security Risks

The editor-mcp includes powerful capabilities that come with certain security considerations:

  • Jailbreak Risk: The editor-mcp can potentially be jailbroken when reading a file that has harmful instructions embedded inside. Malicious content in files being edited could contain instructions that manipulate the AI assistant.
  • Arbitrary Code Execution: If running tests is enabled, there is a risk of arbitrary code execution through manipulated test files or malicious Python code.
  • Data Exposure: Access to file system operations could potentially expose sensitive information if proper path protections aren't configured.

To mitigate these risks:

  1. Use the PROTECTED_PATHS environment variable to restrict access to sensitive files and directories.
  2. Disable test running capabilities in production environments unless absolutely necessary.
  3. Carefully review files before opening them, especially if they come from untrusted sources.
  4. Consider running the editor in a sandboxed environment with limited permissions.

Key Advantages For LLMs

This text editor's unique design solves critical problems that typically affect LLM code editing:

  • Prevents Loss of Context - Traditional approaches often lead to LLMs losing overview of the codebase after a few edits. This implementation maintains context through the multi-step process.

  • Avoids Resource-Intensive Rewrites - LLMs typically default to replacing entire files when confused, which is costly, slow, and inefficient. This editor enforces selective edits.

  • Provides Visual Feedback - The diff preview system allows the LLM to actually see and verify changes before committing them, dramatically reducing errors.

  • Enforces Syntax Checking - Automatic validation for Python and JavaScript/React ensures that broken code isn't committed.

  • Improves Edit Reasoning - The multi-step approach gives the LLM time to reason between steps, reducing haphazard token production.

Resource Management

The editor implements several safeguards to ensure system stability and prevent resource exhaustion:

  • Maximum Edit Lines: By default, the editor enforces a 50-line limit for any single edit operation

Installation

This MCP was developed and tested with Claude Desktop. You can download Claude Desktop on any platform. For Claude Desktop on Linux, you can use an unofficial installation script (uses the official file), recommended repository: https://github.com/emsi/claude-desktop/tree/main

Once you have Claude Desktop installed, follow the instructions below to install this specific MCP:

Easy Installation with UVX (Recommended)

The easiest way to install the Editor MCP is using the provided installation script:

# Clone the repository
git clone https://github.com/danielpodrazka/editor-mcp.git
cd editor-mcp

# Run the installation script
chmod +x install.sh
./install.sh

This script will:

  1. Check if UVX is installed and install it if necessary
  2. Install the Editor MCP in development mode
  3. Make the editor-mcp command available in your PATH

Manual Installation

Using UVX

# Install directly from GitHub
uvx install git+https://github.com/danielpodrazka/mcp-text-editor.git

# Or install from a local clone
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
uvx install -e .

Using Traditional pip

pip install git+https://github.com/danielpodrazka/mcp-text-editor.git

# Or from a local clone
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
pip install -e .

Using Requirements (Legacy)

Install from the lock file:

uv pip install -r uv.lock

Generating a locked requirements file:

uv pip compile requirements.in -o uv.lock

Usage

Starting the Server

After installation, you can start the Editor MCP server using one of these methods:

# Using the installed script
editor-mcp

# Or using the Python module
python -m text_editor.server

MCP Configuration

You can add the Editor MCP to your MCP configuration file:

{
  "mcpServers": {
     "text-editor": {
       "command": "editor-mcp",
       "env": {
         "MAX_SELECT_LINES": "100",
         "ENABLE_JS_SYNTAX_CHECK": "0",
         "FAIL_ON_PYTHON_SYNTAX_ERROR": "1",
         "FAIL_ON_JS_SYNTAX_ERROR": "0",
         "PROTECTED_PATHS": "*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/.ssh/id_rsa"
       }
     }
  }
}

Environment Variable Configuration

The Editor MCP supports several environment variables to customize its behavior:

  • MAX_SELECT_LINES: "100" - Maximum number of lines that can be edited in a single operation (default is 50)

  • ENABLE_JS_SYNTAX_CHECK: "0" - Enable/disable JavaScript and JSX syntax checking (default is "1" - enabled)

  • FAIL_ON_PYTHON_SYNTAX_ERROR: "1" - When enabled, Python syntax errors will automatically cancel the overwrite operation (default is enabled)

  • FAIL_ON_JS_SYNTAX_ERROR: "0" - When enabled, JavaScript/JSX syntax errors will automatically cancel the overwrite operation (default is disabled)

  • PROTECTED_PATHS: Comma-separated list of file patterns or paths that cannot be accessed, supporting wildcards (e.g., ".env,.env,/etc/passwd")

Sample MCP Config When Building From Source

{
  "mcpServers": {
     "text-editor": {
       "command": "/home/daniel/pp/venvs/editor-mcp/bin/python",
       "args": ["/home/daniel/pp/editor-mcp/src/text_editor/server.py"],
        "env": {
          "MAX_SELECT_LINES": "100",
          "ENABLE_JS_SYNTAX_CHECK": "0",
          "FAIL_ON_PYTHON_SYNTAX_ERROR": "1",
          "FAIL_ON_JS_SYNTAX_ERROR": "0",
          "PROTECTED_PATHS": "*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/.ssh/id_rsa"
        }
     }
  }
}

Available Tools

The Editor MCP provides 13 powerful tools for file manipulation, editing, and testing:

1. set_file

Sets the current file to work with.

Parameters:

  • filepath (str): Absolute path to the file

Returns:

  • Confirmation message with the file path

2. skim

Reads full text from the current file. Each line is prefixed with its line number.

Returns:

  • Dictionary containing lines with their line numbers, total number of lines, and the max edit lines setting

Example output:

{
  "lines": [
    [1, "def hello():"],
    [2, "    print(\"Hello, world!\")"],
    [3, ""],
    [4, "hello()"]
  ],
  "total_lines": 4,
  "max_select_lines": 50
}

3. read

Reads text from the current file from start line to end line.

Parameters:

  • start (int): Start line number (1-based indexing)
  • end (int): End line number (1-based indexing)

Returns:

  • Dictionary containing lines with their line numbers as keys, along with start and end line information

Example output:

{
  "lines": [
    [1, "def hello():"],
    [2, "    print(\"Hello, world!\")"],
    [3, ""],
    [4, "hello()"]
  ],
  "start_line": 1,
  "end_line": 4
}

4. select

Select a range of lines from the current file for subsequent overwrite operation.

Parameters:

  • start (int): Start line number (1-based)
  • end (int): End line number (1-based)

Returns:

  • Dictionary containing the selected lines, line range, and ID for verification

Note:

  • This tool validates the selection against max_select_lines
  • The selection details are stored for use in the overwrite tool
  • This must be used before calling the overwrite tool

5. overwrite

Prepare to overwrite a range of lines in the current file with new text.

Parameters:

  • new_lines (list): List of new lines to overwrite the selected range

Returns:

  • Diff preview showing the proposed changes

Note:

  • This is the first step in a two-step process:
    1. First call overwrite() to generate a diff preview
    2. Then call confirm() to apply or cancel() to discard the pending changes
  • This tool allows replacing the previously selected lines with new content
  • The number of new lines can differ from the original selection
  • For Python files (.py extension), syntax checking is performed before writing
  • For JavaScript/React files (.js, .jsx extensions), syntax checking is optional and can be disabled via the ENABLE_JS_SYNTAX_CHECK environment variable

6. confirm

Apply pending changes from the overwrite operation.

Returns:

  • Operation result with status and message

Note:

  • This is one of the two possible actions in the second step of the editing process
  • The selection is removed upon successful application of changes

7. cancel

Discard pending changes from the overwrite operation.

Returns:

  • Operation result with status and message

Note:

  • This is one of the two possible actions in the second step of the editing process
  • The selection remains intact when changes are cancelled

8. delete_file

Delete the currently set file.

Returns:

  • Operation result with status and message

9. new_file

Creates a new file.

Parameters:

  • absolute_file_path (str): Path of the new file

Returns:

  • Operation result with status and id of the content if applicable

Note:

  • This tool will fail if the current file exists and is not empty

10. find_line

Find lines that match provided text in the current file.

Parameters:

  • search_text (str): Text to search for in the file

Returns:

  • Dictionary containing matching lines with their line numbers and total matches

Example output:

{
  "status": "success",
  "matches": [
    [2, "    print(\"Hello, world!\")"]
  ],
  "total_matches": 1
}

Note:

  • Returns an error if no file path is set
  • Searches for exact text matches within each line
  • The id can be used for subsequent edit operations

11. find_function

Find a function or method definition in the current Python or JavaScript/JSX file.

Parameters:

  • function_name (str): Name of the function or method to find

Returns:

  • Dictionary containing the function lines with their line numbers, start_line, and end_line

Example output:

{
  "status": "success",
  "lines": [
    [10, "def hello():"],
    [11, "    print(\"Hello, world!\")"],
    [12, "    return True"]
  ],
  "start_line": 10,
  "end_line": 12
}

Note:

  • For Python files, this tool uses Python's AST and tokenize modules to accurately identify function boundaries including decorators and docstrings
  • For JavaScript/JSX files, this tool uses a combination of approaches:
    • Primary method: Babel AST parsing when available (requires Node.js and Babel packages)
    • Fallback method: Regex pattern matching for function declarations when Babel is unavailable
  • Supports various JavaScript function types including standard functions, async functions, arrow functions, and React hooks
  • Returns an error if no file path is set or if the function is not found

12. listdir

Lists the contents of a directory.

Parameters:

  • dirpath (str): Path to the directory to list

Returns:

  • Dictionary containing list of filenames and the path queried

13. run_tests and set_python_path

Tools for running Python tests with pytest and configuring the Python environment.

  • Set to "0", "false", or "no" to disable JavaScript syntax checking
  • Useful if you don't have Babel and related dependencies installed
  • FAIL_ON_PYTHON_SYNTAX_ERROR: Controls whether Python syntax errors automatically cancel the overwrite operation (default: 1)
    • When enabled, syntax errors in Python files will cause the overwrite action to be automatically cancelled
    • The lines will remain selected so you can fix the error and try again
  • FAIL_ON_JS_SYNTAX_ERROR: Controls whether JavaScript/JSX syntax errors automatically cancel the overwrite operation (default: 0)
    • When enabled, syntax errors in JavaScript/JSX files will cause the overwrite action to be automatically cancelled
    • The lines will remain selected so you can fix the error and try again
  • DUCKDB_USAGE_STATS: Controls whether usage statistics are collected in a DuckDB database (default: 0)
    • Set to "1", "true", or "yes" to enable collection of tool usage statistics
    • When enabled, records information about each tool call including timestamps and arguments
  • STATS_DB_PATH: Path where the DuckDB database for statistics will be stored (default: "text_editor_stats.duckdb")
    • Only used when DUCKDB_USAGE_STATS is enabled
  • PROTECTED_PATHS: Comma-separated list of file patterns or absolute paths that will be denied access
    • Example: *.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt
    • Supports both exact file paths and flexible glob patterns with wildcards in any position:
      • *.env - matches files ending with .env, like .env, dev.env, prod.env
      • .env* - matches files starting with .env, like .env, .env.local, .env.production
      • *secret* - matches any file containing 'secret' in the name
    • Provides protection against accidentally exposing sensitive configuration files and credentials
    • The lines will remain selected so you can fix the error and try again

Development

Prerequisites

The editor-mcp requires:

  • Python 3.7+
  • FastMCP package
  • black (for Python code formatting checks)
  • Babel (for JavaScript/JSX syntax checks if working with those files)

Install development dependencies:

# Using pip
pip install pytest pytest-asyncio pytest-cov

# Using uv
uv pip install pytest pytest-asyncio pytest-cov

For JavaScript/JSX syntax validation, you need Node.js and Babel. The text editor uses npx babel to check JS/JSX syntax when editing these file types:

# Required for JavaScript/JSX syntax checking
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react
# You can also install these globally if you prefer
# npm install -g @babel/core @babel/cli @babel/preset-env @babel/preset-react

The editor requires:

  • @babel/core and @babel/cli - Core Babel packages for syntax checking
  • @babel/preset-env - For standard JavaScript (.js) files
  • @babel/preset-react - For React JSX (.jsx) files

Running Tests

# Run tests
pytest -v

# Run tests with coverage
pytest -v --cov=text_editor

Test Structure

The test suite covers:

  1. set_file tool

    • Setting valid files
    • Setting non-existent files

  2. read tool

    • File state validation
    • Reading entire files
    • Reading specific line ranges
    • Edge cases like empty files
    • Invalid range handling

  3. select tool

    • Line range validation
    • Selection validation against max_select_lines
    • Selection storage for subsequent operations

  4. overwrite tool

    • Verification of selected content using ID
    • Content replacement validation
    • Syntax checking for Python and JavaScript/React files
    • Generation of diff preview for changes

  5. confirm and cancel tools

    • Applying or canceling pending changes
    • Two-step verification process

  6. delete_file tool

    • File deletion validation

  7. new_file tool

    • File creation validation
    • Handling existing files

  8. find_line tool

    • Finding text matches in files
    • Handling specific search terms
    • Error handling for non-existent files
    • Handling cases with no matches
    • Handling existing files

How it Works

The Multi-Step Editing Approach

Unlike traditional code editing approaches where LLMs simply search for lines to edit and make replacements (often leading to confusion after multiple edits), this editor implements a structured multi-step workflow that dramatically improves editing accuracy:

  1. set_file - First, the LLM sets which file it wants to edit
  2. skim - The LLM reads the entire file to gain a complete overview
  3. read - The LLM examines specific sections relevant to the task, with lines shown alongside numbers for better context
  4. select - When ready to edit, the LLM selects specific lines (limited to a configurable number, default 50)
  5. overwrite - The LLM proposes replacement content, resulting in a git diff-style preview that shows exactly what will change
  6. confirm/cancel - After reviewing the preview, the LLM can either apply or discard the changes

This structured workflow forces the LLM to reason carefully about each edit and prevents common errors like accidentally overwriting entire files. By seeing previews of changes before committing them, the LLM can verify its edits are correct.

ID Verification System

The server uses FastMCP to expose text editing capabilities through a well-defined API. The ID verification system ensures data integrity by verifying that the content hasn't changed between reading and modifying operations.

The ID mechanism uses SHA-256 to generate a unique identifier of the file content or selected line ranges. For line-specific operations, the ID includes a prefix indicating the line range (e.g., "L10-15-[hash]"). This helps ensure that edits are being applied to the expected content.

Implementation Details

The main TextEditorServer class:

  1. Initializes with a FastMCP instance named "text-editor"
  2. Sets a configurable max_select_lines limit (default: 50) from environment variables
  3. Maintains the current file path as state
  4. Registers thirteen primary tools through FastMCP:
    • set_file: Validates and sets the current file path
    • skim: Reads the entire content of a file, returning a dictionary of line numbers to line text
    • read: Reads lines from specified line range, returning a structured dictionary of line content
    • select: Selects lines for subsequent overwrite operation
    • overwrite: Takes a list of new lines and prepares diff preview for changing content
    • confirm: Applies pending changes from the overwrite operation
    • cancel: Discards pending changes from the overwrite operation
    • delete_file: Deletes the current file
    • new_file: Creates a new file
    • find_line: Finds lines containing specific text
    • find_function: Finds function or method definitions in Python and JavaScript/JSX files
    • listdir: Lists contents of a directory
    • run_tests and set_python_path: Tools for running Python tests

The server runs using FastMCP's stdio transport by default, making it easy to integrate with various clients.

System Prompt for Best Results

For optimal results with AI assistants, it's recommended to use the system prompt (see system_prompt.md) that helps guide the AI in making manageable, safe edits.

This system prompt helps the AI assistant:

  1. Make incremental changes - Breaking down edits into smaller parts
  2. Maintain code integrity - Making changes that keep the code functional
  3. Work within resource limits - Avoiding operations that could overwhelm the system
  4. Follow a verification workflow - Doing final checks for errors after edits

By incorporating this system prompt when working with AI assistants, you'll get more reliable editing behavior and avoid common pitfalls in automated code editing.

example.png

Usage Statistics

The text editor MCP can collect usage statistics when enabled, providing insights into how the editing tools are being used:

  • Data Collection: Statistics are collected in a DuckDB database when DUCKDB_USAGE_STATS is enabled
  • Tracked Information: Records tool name, arguments, timestamp, current file path, tool response, and request/client IDs
  • Storage Location: Data is stored in a DuckDB file specified by STATS_DB_PATH
  • Privacy: Everything is stored locally on your machine

The collected statistics can help understand usage patterns, identify common workflows, and optimize the editor for most frequent operations.

You can query the database using standard SQL via any DuckDB client to analyze usage patterns.

Troubleshooting

If you encounter issues:

  1. Check file permissions
  2. Verify that the file paths are absolute
  3. Ensure the environment is using Python 3.7+

Inspiration

Inspired by a similar project: https://github.com/tumf/mcp-text-editor, which at first I forked, however I decided to rewrite the whole codebase from scratch so only the general idea stayed the same.