editor-mcp

MCP 编辑

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

特征

• 文件选择：使用绝对路径设置要使用的文件
• 读取操作：
  • 使用skim读取带有行号的整个文件
  • 使用read读取带有前缀行号的特定行范围
  • 使用find_line查找文件中的特定文本
  • 使用find_function查找并提取 Python 和 JavaScript/JSX 文件中的函数定义
• 编辑操作：
  • 带有差异预览的两步编辑流程
  • 选择并覆盖带有身份验证的文本
  • 通过选择→覆盖→确认/取消模式简化编辑工作流程
  • 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 有时间在步骤之间进行推理，从而减少随意的标记生成。

资源管理

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

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

安装

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

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

使用 UVX 轻松安装（推荐）

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

该脚本将：

1. 检查是否安装了UVX，如有必要则安装
2. 以开发模式安装 Editor MCP
3. 使editor-mcp命令在你的 PATH 中可用

手动安装

使用 UVX

使用传统 pip

使用需求（遗留）

从锁定文件安装：

生成锁定的需求文件：

用法

启动服务器

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

MCP 配置

您可以将编辑器 MCP 添加到您的 MCP 配置文件中：

环境变量配置

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 配置

可用工具

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

1. set_file

设置要使用的当前文件。

参数：

• filepath （str）：文件的绝对路径

返回：

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

2. skim

从当前文件读取全文。每行都以行号作为前缀。

返回：

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

示例输出：

3. read

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

参数：

• start （int）：起始行号（从 1 开始索引）
• end （int）：结束行号（从 1 开始索引）

返回：

• 字典包含以行号为键的行，以及开始和结束行的信息

示例输出：

4. select

从当前文件中选择一定范围的行以进行后续的覆盖操作。

参数：

• start （int）：起始行号（从 1 开始）
• end （int）：结束行号（从 1 开始）

返回：

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

笔记：

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

5. overwrite

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

参数：

• new_lines （列表）：用于覆盖所选范围的新行列表

返回：

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

笔记：

• 这是两步流程的第一步：
  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）：要在文件中搜索的文本

返回：

• 包含匹配行及其行号和总匹配数的字典

示例输出：

笔记：

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

11. find_function

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

参数：

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

返回：

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

示例输出：

笔记：

• 对于 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 包
• 黑色（用于 Python 代码格式检查）
• Babel（用于检查使用这些文件时的 JavaScript/JSX 语法）

安装开发依赖项：

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

编辑器要求：

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

运行测试

测试结构

测试套件涵盖：

1. set_file 工具
   • 设置有效文件
   • 设置不存在的文件
2. 阅读工具
   • 文件状态验证
   • 读取整个文件
   • 读取特定行范围
   • 诸如空文件之类的边缘情况
   • 无效范围处理
3. 选择工具
   • 行范围验证
   • 针对 max_select_lines 的选择验证
   • 后续操作的选择存储
4. 覆盖工具
   • 使用 ID 验证所选内容
   • 内容替换验证
   • Python 和 JavaScript/React 文件的语法检查
   • 生成变更的差异预览
5. 确认和取消工具
   • 应用或取消待处理的更改
   • 两步验证流程
6. delete_file 工具
   • 文件删除验证
7. new_file 工具
   • 文件创建验证
   • 处理现有文件
8. find_line 工具
   • 在文件中查找文本匹配
   • 处理特定搜索词
   • 不存在文件的错误处理
   • 处理无匹配项的案例
   • 处理现有文件

工作原理

多步骤编辑方法

与传统的代码编辑方法不同，在传统的代码编辑方法中，LLM 只是搜索要编辑的行并进行替换（多次编辑后通常会造成混乱），而此编辑器实现了结构化的多步骤工作流程，可显著提高编辑准确性：

1. set_file - 首先，LLM 设置要编辑的文件
2. skim - LLM 阅读整个文件以获得完整的概述
3. 阅读- LLM 检查与任务相关的特定部分，并在数字旁边显示行，以便更好地理解上下文
4. 选择- 准备编辑时，LLM 选择特定行（限制为可配置数量，默认为 50）
5. 覆盖- LLM 建议替换内容，从而生成一个 git diff 样式的预览，准确显示将要更改的内容
6. 确认/取消- 审阅预览后，LLM 可以应用或放弃更改

这种结构化的工作流程迫使法学硕士 (LLM) 仔细推敲每一次编辑，并避免诸如意外覆盖整个文件之类的常见错误。通过在提交更改之前查看预览，LLM 可以验证其编辑是否正确。

身份验证系统

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

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

实现细节

主要的TextEditorServer类：

1. 使用名为“text-editor”的 FastMCP 实例进行初始化
2. 从环境变量设置可配置的max_select_lines限制（默认值：50）
3. 保持当前文件路径为状态
4. 通过 FastMCP 注册十三个主要工具：
   • 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 ，起初我分叉了它，但我决定从头开始重写整个代码库，因此只有总体思路保持不变。