🚀 文本编辑器 MCP 用户指南

文本编辑器 MCP 借助 FastMCP 构建了功能强大的文本编辑服务器，支持 AI 助手以结构化方式编辑代码及其他文本文件。相较于传统命令行工具，MCP 具备文件完整性验证、使用限制和交互式确认流程等高级功能。

🚀 快速开始

MCP 支持通过环境变量进行配置，以下是一些关键的环境变量：

最大选择行数

max_select_lines 用于限制在 overwrite 操作中可选中的最大行数，默认值为 50。示例配置如下：

export max_select_lines=100

启用统计收集

DUCKDB_USAGE_STATS 启用后，MCP 会将使用统计信息收集到 DuckDB 数据库。

禁用 ID 验证

将 DISABLE_ID_VERIFICATION 设置为 true 可禁用文件内容的完整性验证。示例如下：

export DISABLE_ID_VERIFICATION=true

✨ 主要特性

• 结构化编辑：允许 AI 助手以结构化方式编辑代码和文本文件。
• 高级功能：提供文件完整性验证、使用限制和交互式确认流程等传统命令行工具所没有的功能。
• 环境变量配置：支持通过环境变量对 MCP 进行灵活配置。
• 使用统计收集：可收集使用统计信息以用于改进服务质量和分析系统性能。

📚 详细文档

服务器实现细节

初始化

主类 TextEditorServer 初始化时会接收一个 FastMCP 实例，命名为 "text - editor"。

文件完整性验证系统

该系统采用 SHA - 256 生成文件内容或选中行范围的唯一标识符。例如，针对特定行的修改操作，ID 会包含行范围前缀（如："L10 - 15 - [哈希值]"），确保编辑操作应用于预期内容。

注册的工具

服务器通过 FastMCP 注册了以下主要工具：

• set_file：用于设置当前要编辑的文件路径。
• skim：读取整个文件内容并返回行号到行文本的字典。
• read：根据指定的行范围读取内容，返回结构化的字典。
• select：选择后续 overwrite 操作中涉及的特定行（最多 50 行）。
• overwrite：接收新的行列表，并生成 diff 格式的预览以显示将要进行的更改。
• confirm：应用之前 overwrite 工具准备的更改。
• cancel：放弃 overwrite 工具中的 pending 改变。
• delete_file：删除当前文件。
• new_file：创建新文件。
• find_line：查找包含特定文本的行。
• find_function：在 Python 和 JavaScript/JSX 文件中查找函数定义。

系统提示的最佳实践

为优化 AI 助手的行为，建议使用系统提示（system prompt）。示例如下：

mcp_server.set_system_prompt("作为经验丰富的软件工程师，你应当以严格和安全的方式执行编辑操作。")

这样能确保助手在进行文件修改时更加谨慎，并遵循最佳编程实践。

使用统计信息

数据收集

MCP 具备使用 DuckDB 进行数据收集的功能，用于记录用户对服务器的使用情况。

记录的信息

包括但不限于：

• 用户 ID
• 操作类型（读取、写入等）
• 操作时间戳
• 文件大小变化
• 错误日志

存储位置

统计数据存储在当前工作目录下的 mcp_usage.db 数据库文件中。

隐私考虑

所有收集的数据均为匿名化处理，仅用于改进服务质量和分析系统性能。

故障排除

常见问题

• 问题：无法连接到 MCP 服务器
  • 解决方法：检查服务器是否在运行，确认网络配置正确。
• 问题：收到 ID 验证失败的错误
  • 解决方法：要么启用 ID 验证（默认启用），要么禁用该功能。

灵感来源

此项目受开源社区启发，特别是 FastMCP 和类似工具的成功经验。