🚀 编辑文件工具使用文档

本工具遵循MCP协议，专为文件编辑而设计。它能有效解决文件编辑过程中的安全、灵活处理及版本管理等问题，为用户提供安全、智能且高效的文件编辑体验。

🚀 快速开始

启动该编辑文件工具前，需完成依赖安装、服务器构建等操作，同时要指定允许操作的目录。

✨ 主要特性

• 安全限制：所有文件操作均严格限定在预先指定的允许目录内，保障操作安全。
• 智能文本处理：支持正则表达式和字符串匹配，让文本处理更灵活高效。
• 版本控制：支持保存和恢复编辑状态，方便用户回溯操作。
• 校验机制：对文件路径和修改内容进行严格验证，确保操作的准确性。

📦 安装指南

安装依赖

运行以下命令安装所需依赖：

npm install

构建服务器

构建生产环境版本的服务器：

npm run build

开发模式

在开发环境中启用自动重建功能：

npm run watch

💻 使用示例

基础用法

启动服务器时，需指定一个或多个允许目录：

node build/index.js <允许目录> [额外目录...]

所有文件操作都将被限制在这些指定的目录内。

高级用法

示例1：替换特定行内容

{
  "path": "src/components/Button.tsx",
  "edits": [{
    "startLine": 5,
    "endLine": 5,
    "content": "export const Button = () => {"
  }]
}

示例2：批量修改多个位置

{
  "operations": [
    {
      "path": "src/App.tsx",
      "edits": [{
        "startLine": 10,
        "endLine": 10,
        "content": "// 新注释"
      }]
    },
    {
      "path": "src/styles.css",
      "edits": [{
        "startLine": 20,
        "endLine": 20,
        "content": ".button { padding: 1rem; }"
      }]
    }
  ]
}

📚 详细文档

环境变量

错误处理

常见错误及解决方案如下：

1. 未找到匹配项

Error: 没有找到字符串匹配项"oldValue"在第5行

2. 无效正则表达式

Error: 无效的正则表达式模式"([": 未终止的分组

3. 同一行被多次编辑

Error: 第5行受到多个编辑操作的影响

安全注意事项

• 所有文件操作均限于预先指定的允许目录。
• 禁止使用 symlink 来绕过路径限制。
• 防护父目录遍历攻击。
• 严格校验输入的文件路径和修改内容。
• 编辑状态默认60秒后自动过期。

调试指南

推荐使用test:tools脚本对工具进行全面测试：

npm run test:tools

该脚本会执行以下操作：

1. 重置测试用例到初始状态。
2. 连接MCP服务器。
3. 依次测试各个功能模块。
4. 显示每项操作的输出结果。

配置示例

在Claude环境中的配置示例：

export MCP_EDIT_STATE_TTL=360000

帮助与支持

如需帮助或发现任何问题，请联系技术支持团队。