Editor MCP

这是一个基于 Python 的文本编辑器服务器，使用 FastMCP 构建，提供强大的文件操作工具。该服务器通过标准化的 API 实现文本文件的读取、编辑和管理，并采用独特的多步骤方法，显著提高 LLM 和 AI 助手代码编辑的准确性和可靠性。

功能特性

• 文件选择: 使用绝对路径设置要操作的文件
• 读取操作:
  • 使用 skim 读取带有行号的整个文件
  • 使用 read 读取带有前缀行号的特定行范围
  • 使用 find_line 在文件中查找特定文本
  • 使用 find_function 在 Python 和 JavaScript/JSX 文件中查找并提取函数定义
• 编辑操作:
  • 具有差异预览的两步编辑过程
  • 使用 ID 验证选择和覆盖文本
  • 使用选择 → 覆盖 → 确认/取消模式的清晰编辑工作流程
  • Python (.py) 和 JavaScript/React (.js, .jsx) 文件的语法检查
  • 创建带有内容的新文件
• 文件管理:
  • 创建具有适当初始化的新文件
  • 从文件系统中删除文件
  • 使用 listdir 列出目录内容
• 测试支持:
  • 使用 run_tests 运行 Python 测试
  • 设置 Python 路径以进行正确的模块解析
• 安全特性:
  • 内容 ID 验证以防止冲突
  • 行数限制以防止资源耗尽
  • 语法检查以保持代码完整性
  • 受保护的路径以限制对敏感文件的访问

安全风险

editor-mcp 包含强大的功能，但也带来一定的安全考虑：

• 越狱风险: 当读取包含有害指令的文件时，editor-mcp 可能会被越狱。被编辑文件中的恶意内容可能包含操纵 AI 助手的指令。
• 任意代码执行: 如果启用了运行测试，则存在通过操纵的测试文件或恶意 Python 代码执行任意代码的风险。
• 数据暴露: 如果未配置适当的路径保护，访问文件系统操作可能会暴露敏感信息。

为了减轻这些风险：

1. 使用 PROTECTED_PATHS 环境变量来限制对敏感文件和目录的访问。
2. 除非绝对必要，否则在生产环境中禁用测试运行功能。
3. 在打开文件之前仔细检查文件，尤其是在文件来自不受信任的来源时。
4. 考虑在具有有限权限的沙盒环境中运行编辑器。

LLM 的关键优势

此文本编辑器的独特设计解决了通常影响 LLM 代码编辑的关键问题：

• 防止上下文丢失 - 传统方法通常会导致 LLM 在几次编辑后失去对代码库的概览。此实现通过多步骤过程维护上下文。

• 避免资源密集型重写 - LLM 通常默认在感到困惑时替换整个文件，这既昂贵又缓慢且效率低下。此编辑器强制执行选择性编辑。

• 提供可视化反馈 - 差异预览系统允许 LLM 在提交更改之前实际查看和验证更改，从而大大减少错误。

• 强制执行语法检查 - Python 和 JavaScript/React 的自动验证确保不会提交损坏的代码。

• 改进编辑推理 - 多步骤方法使 LLM 有时间在步骤之间进行推理，从而减少随意生成 token。

资源管理

编辑器实施了多项安全措施，以确保系统稳定并防止资源耗尽：

• 最大编辑行数: 默认情况下，编辑器对任何单个编辑操作强制执行 50 行的限制

安装

此 MCP 是使用 Claude Desktop 开发和测试的。您可以在任何平台上下载 Claude Desktop。 对于 Linux 上的 Claude Desktop，您可以使用非官方安装脚本（使用官方文件），推荐的存储库： https://github.com/emsi/claude-desktop/tree/main

安装 Claude Desktop 后，请按照以下说明安装此特定 MCP：

使用 UVX 轻松安装（推荐）

安装 Editor MCP 的最简单方法是使用提供的安装脚本：

# 克隆存储库
git clone https://github.com/danielpodrazka/editor-mcp.git
cd editor-mcp

# 运行安装脚本
chmod +x install.sh
./install.sh

此脚本将：

1. 检查是否已安装 UVX，如果需要则安装它
2. 在开发模式下安装 Editor MCP
3. 使 editor-mcp 命令在您的 PATH 中可用

手动安装

使用 UVX

# 直接从 GitHub 安装
uvx install git+https://github.com/danielpodrazka/mcp-text-editor.git

# 或者从本地克隆安装
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
uvx install -e .

使用传统的 pip

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

# 或者从本地克隆安装
git clone https://github.com/danielpodrazka/mcp-text-editor.git
cd mcp-text-editor
pip install -e .

使用 Requirements (Legacy)

从锁定文件安装：

uv pip install -r uv.lock

生成锁定的 requirements 文件：

uv pip compile requirements.in -o uv.lock

用法

启动服务器

安装后，您可以使用以下方法之一启动 Editor MCP 服务器：

# 使用已安装的脚本
editor-mcp

# 或者使用 Python 模块
python -m text_editor.server

MCP 配置

您可以将 Editor MCP 添加到您的 MCP 配置文件中：

{
  "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"
       }
     }
  }
}

环境变量配置

Editor MCP 支持多个环境变量来自定义其行为：

• MAX_SELECT_LINES: "100" - 单个操作中可以编辑的最大行数（默认为 50）

• ENABLE_JS_SYNTAX_CHECK: "0" - 启用/禁用 JavaScript 和 JSX 语法检查（默认为 "1" - 启用）

• FAIL_ON_PYTHON_SYNTAX_ERROR: "1" - 启用后，Python 语法错误将自动取消覆盖操作（默认启用）

• FAIL_ON_JS_SYNTAX_ERROR: "0" - 启用后，JavaScript/JSX 语法错误将自动取消覆盖操作（默认禁用）

• PROTECTED_PATHS: 以逗号分隔的文件模式或路径列表，这些文件模式或路径无法访问，支持通配符（例如，".env,.env,/etc/passwd"）

从源代码构建时的示例 MCP 配置

{
  "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"
        }
     }
  }
}

可用工具

Editor MCP 提供了 13 个强大的工具，用于文件操作、编辑和测试：

1. set_file

设置当前要操作的文件。

参数:

• filepath (str): 文件的绝对路径

返回值:

• 带有文件路径的确认消息

2. skim

从当前文件读取完整文本。每行都以其行号为前缀。

返回值:

• 包含带有行号的行、总行数和最大编辑行数设置的字典

示例输出:

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

3. read

从当前文件读取从起始行到结束行的文本。

参数:

• start (int): 起始行号（基于 1 的索引）
• end (int): 结束行号（基于 1 的索引）

返回值:

• 包含带有行号作为键的行以及起始行和结束行信息的字典

示例输出:

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

4. select

从当前文件中选择一系列行以进行后续覆盖操作。

参数:

• start (int): 起始行号（基于 1）
• end (int): 结束行号（基于 1）

返回值:

• 包含选定行、行范围和用于验证的 ID 的字典

注意:

• 此工具根据 max_select_lines 验证选择
• 选择详细信息存储起来以供在覆盖工具中使用
• 必须在使用覆盖工具之前使用此工具

5. overwrite

准备使用新文本覆盖当前文件中的一系列行。

参数:

• new_lines (list): 用于覆盖选定范围的新行列表

返回值:

• 显示建议更改的差异预览

注意:

• 这是两步过程中的第一步：
  1. 首先调用 overwrite() 以生成差异预览
  2. 然后调用 confirm() 以应用或 cancel() 以放弃挂起的更改
• 此工具允许使用新内容替换先前选择的行
• 新行的数量可能与原始选择不同
• 对于 Python 文件（.py 扩展名），在写入之前执行语法检查
• 对于 JavaScript/React 文件（.js, .jsx 扩展名），语法检查是可选的，可以通过 ENABLE_JS_SYNTAX_CHECK 环境变量禁用

6. confirm

应用来自覆盖操作的挂起更改。

返回值:

• 带有状态和消息的操作结果

注意:

• 这是编辑过程第二步中的两种可能操作之一
• 成功应用更改后，将删除选择

7. cancel

放弃来自覆盖操作的挂起更改。

返回值:

• 带有状态和消息的操作结果

注意:

• 这是编辑过程第二步中的两种可能操作之一
• 取消更改后，选择保持不变

8. delete_file

删除当前设置的文件。

返回值:

• 带有状态和消息的操作结果

9. new_file

创建一个新文件。

参数:

• absolute_file_path (str): 新文件的路径

返回值:

• 带有状态和内容 ID（如果适用）的操作结果

注意:

• 如果当前文件存在且不为空，则此工具将失败

10. find_line

在当前文件中查找与提供的文本匹配的行。

参数:

• search_text (str): 要在文件中搜索的文本

返回值:

• 包含带有行号和总匹配数的匹配行的字典

示例输出:

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

注意:

• 如果未设置文件路径，则返回错误
• 搜索每行中的精确文本匹配项
• 该 ID 可用于后续编辑操作

11. find_function

在当前 Python 或 JavaScript/JSX 文件中查找函数或方法定义。

参数:

• function_name (str): 要查找的函数或方法的名称

返回值:

• 包含带有行号、起始行和结束行的函数行的字典

示例输出:

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

注意:

• 对于 Python 文件，此工具使用 Python 的 AST 和 tokenize 模块来准确识别函数边界，包括装饰器和文档字符串
• 对于 JavaScript/JSX 文件，此工具使用以下方法的组合：
  • 主要方法：Babel AST 解析（如果可用）（需要 Node.js 和 Babel 包）
  • 备用方法：当 Babel 不可用时，使用正则表达式模式匹配函数声明
• 支持各种 JavaScript 函数类型，包括标准函数、异步函数、箭头函数和 React hooks
• 如果未设置文件路径或未找到该函数，则返回错误

12. listdir

列出目录的内容。

参数:

• dirpath (str): 要列出的目录的路径

返回值:

• 包含文件名列表和查询路径的字典

13. run_tests 和 set_python_path

用于使用 pytest 运行 Python 测试和配置 Python 环境的工具。

• 设置为 "0"、"false" 或 "no" 以禁用 JavaScript 语法检查
• 如果您没有安装 Babel 和相关依赖项，这将非常有用
• FAIL_ON_PYTHON_SYNTAX_ERROR: 控制 Python 语法错误是否自动取消覆盖操作（默认值：1）
  • 启用后，Python 文件中的语法错误将导致自动取消覆盖操作
  • 这些行将保持选中状态，以便您可以修复错误并重试
• FAIL_ON_JS_SYNTAX_ERROR: 控制 JavaScript/JSX 语法错误是否自动取消覆盖操作（默认值：0）
  • 启用后，JavaScript/JSX 文件中的语法错误将导致自动取消覆盖操作
  • 这些行将保持选中状态，以便您可以修复错误并重试
• DUCKDB_USAGE_STATS: 控制是否在 DuckDB 数据库中收集使用情况统计信息（默认值：0）
  • 设置为 "1"、"true" 或 "yes" 以启用工具使用情况统计信息的收集
  • 启用后，记录有关每个工具调用的信息，包括时间戳和参数
• STATS_DB_PATH: 将存储统计信息的 DuckDB 数据库的路径（默认值："text_editor_stats.duckdb"）
  • 仅当启用 DUCKDB_USAGE_STATS 时才使用
• PROTECTED_PATHS: 以逗号分隔的文件模式或绝对路径列表，这些文件模式或绝对路径将被拒绝访问
  • 示例：*.env,.env*,config*.json,*secret*,/etc/passwd,/home/user/credentials.txt
  • 支持精确的文件路径和灵活的 glob 模式，通配符可以位于任何位置：
    • *.env - 匹配以 .env 结尾的文件，例如 .env、dev.env、prod.env
    • .env* - 匹配以 .env 开头的文件，例如 .env、.env.local、.env.production
    • *secret* - 匹配名称中包含“secret”的任何文件
  • 提供针对意外暴露敏感配置文件和凭据的保护
  • 这些行将保持选中状态，以便您可以修复错误并重试

开发

先决条件

editor-mcp 需要：

• Python 3.7+
• FastMCP 包
• black（用于 Python 代码格式检查）
• Babel（用于 JavaScript/JSX 语法检查，如果使用这些文件）

安装开发依赖项：

# 使用 pip
pip install pytest pytest-asyncio pytest-cov

# 使用 uv
uv pip install pytest pytest-asyncio pytest-cov

对于 JavaScript/JSX 语法验证，您需要 Node.js 和 Babel。文本编辑器使用 npx babel 在编辑这些文件类型时检查 JS/JSX 语法：

# JavaScript/JSX 语法检查所需
npm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react
# 如果您愿意，也可以全局安装这些
# npm install -g @babel/core @babel/cli @babel/preset-env @babel/preset-react

编辑器需要：

• @babel/core 和 @babel/cli - 用于语法检查的核心 Babel 包
• @babel/preset-env - 用于标准 JavaScript (.js) 文件
• @babel/preset-react - 用于 React JSX (.jsx) 文件

运行测试

# 运行测试
pytest -v

# 运行带有覆盖率的测试
pytest -v --cov=text_editor

测试结构

测试套件涵盖：

1. set_file 工具

   • 设置有效文件
   • 设置不存在的文件

2. read 工具

   • 文件状态验证
   • 读取整个文件
   • 读取特定行范围
   • 空文件等边缘情况
   • 无效范围处理

3. select 工具

   • 行范围验证
   • 根据 max_select_lines 进行选择验证
   • 选择存储以供后续操作

4. overwrite 工具

   • 使用 ID 验证选定的内容
   • 内容替换验证
   • Python 和 JavaScript/React 文件的语法检查
   • 生成更改的差异预览

5. confirm 和 cancel 工具

   • 应用或取消挂起的更改
   • 两步验证过程

6. delete_file 工具

   • 文件删除验证

7. new_file 工具

   • 文件创建验证
   • 处理现有文件

8. find_line 工具

   • 在文件中查找文本匹配项
   • 处理特定的搜索词
   • 不存在文件的错误处理
   • 处理没有匹配项的情况
   • 处理现有文件

工作原理

多步骤编辑方法

与传统的代码编辑方法（LLM 只是搜索要编辑的行并进行替换，这通常会在多次编辑后导致混淆）不同，此编辑器实现了一个结构化的多步骤工作流程，从而大大提高了编辑准确性：

1. set_file - 首先，LLM 设置它想要编辑的文件
2. skim - LLM 读取整个文件以获得完整的概览
3. read - LLM 检查与任务相关的特定部分，这些行与数字一起显示，以获得更好的上下文
4. select - 准备好编辑后，LLM 选择特定的行（限制为可配置的数量，默认为 50）
5. overwrite - LLM 提出替换内容，从而生成 git diff 样式的预览，该预览准确显示将要更改的内容
6. confirm/cancel - 在查看预览后，LLM 可以应用或放弃更改

这种结构化的工作流程迫使 LLM 仔细推理每次编辑，并防止常见的错误，例如意外覆盖整个文件。通过在提交更改之前查看更改的预览，LLM 可以验证其编辑是否正确。

ID 验证系统

服务器使用 FastMCP 通过明确定义的 API 公开文本编辑功能。ID 验证系统通过验证内容在读取和修改操作之间是否已更改来确保数据完整性。

ID 机制使用 SHA-256 生成文件内容或选定行范围的唯一标识符。对于特定于行的操作，ID 包括一个前缀，指示行范围（例如，“L10-15-[hash]”）。这有助于确保将编辑应用于预期内容。

实现细节

主要的 TextEditorServer 类：

1. 使用名为“text-editor”的 FastMCP 实例初始化
2. 从环境变量设置可配置的 max_select_lines 限制（默认值：50）
3. 将当前文件路径维护为状态
4. 通过 FastMCP 注册 13 个主要工具：
   • set_file: 验证并设置当前文件路径
   • skim: 读取文件的全部内容，返回行号到行文本的字典
   • read: 从指定的行范围读取行，返回行内容的结构化字典
   • select: 选择行以进行后续覆盖操作
   • overwrite: 接受新行列表并准备用于更改内容的差异预览
   • confirm: 应用来自覆盖操作的挂起更改
   • cancel: 放弃来自覆盖操作的挂起更改
   • delete_file: 删除当前文件
   • new_file: 创建一个新文件
   • find_line: 查找包含特定文本的行
   • find_function: 在 Python 和 JavaScript/JSX 文件中查找函数或方法定义
   • listdir: 列出目录的内容
   • run_tests 和 set_python_path: 用于运行 Python 测试的工具

默认情况下，服务器使用 FastMCP 的 stdio 传输运行，从而可以轻松地与各种客户端集成。

获得最佳结果的系统提示

为了获得 AI 助手的最佳结果，建议使用系统提示（请参阅 system_prompt.md），该提示有助于指导 AI 进行可管理的安全编辑。

此系统提示有助于 AI 助手：

1. 进行增量更改 - 将编辑分解为更小的部分
2. 维护代码完整性 - 进行保持代码功能的更改
3. 在资源限制内工作 - 避免可能使系统不堪重负的操作
4. 遵循验证工作流程 - 在编辑后对错误进行最终检查

通过在与 AI 助手一起工作时合并此系统提示，您将获得更可靠的编辑行为，并避免自动化代码编辑中的常见陷阱。

使用情况统计信息

文本编辑器 MCP 可以在启用时收集使用情况统计信息，从而提供对编辑工具使用方式的见解：

• 数据收集: 启用 DUCKDB_USAGE_STATS 时，统计信息收集在 DuckDB 数据库中
• 跟踪的信息: 记录工具名称、参数、时间戳、当前文件路径、工具响应和请求/客户端 ID
• 存储位置: 数据存储在 STATS_DB_PATH 指定的 DuckDB 文件中
• 隐私: 所有内容都存储在您机器的本地

收集的统计信息可以帮助了解使用模式、识别常见工作流程并优化编辑器以进行最频繁的操作。

您可以使用任何 DuckDB 客户端通过标准 SQL 查询数据库，以分析使用模式。

故障排除

如果您遇到问题：

1. 检查文件权限
2. 验证文件路径是否为绝对路径
3. 确保环境使用 Python 3.7+

灵感

灵感来自一个类似的项目：https://github.com/tumf/mcp-text-editor，起初我 fork 了它，但我决定从头开始重写整个代码库，所以只有总体思路保持不变。