mcp-multi-edit

Multi Edit MCP 服务

一个 MCP 服务，让 Claude 能够在一次工具调用中执行多项查找和替换操作，并保证原子性——所有编辑要么全部成功，要么全部不生效。

由 Essential AI Solutions 为 Claude Code 和 Claude Desktop 构建。

为什么选择 Multi Edit？

Claude 内置的 Edit 工具每次调用只能处理一项查找和替换。重命名文件中的变量或重构多个文件时，就需要单独调用数十次工具——每次调用都会消耗上下文令牌并增加延迟。

Multi Edit 可将这些操作批量合并为一次调用：

Without multi_edit:      105 tool calls   |   15,750 tokens
With multi_edit:          21 tool calls   |    7,850 tokens   (-80% calls, -50% tokens)
With multi_edit_files:     6 tool calls   |    4,550 tokens   (-94% calls, -71% tokens)

基准测试采用真实场景（批量重命名、日志迁移、跨文件重构）。 完整详情请参阅 benchmarks/results/BENCHMARK-REPORT.md。

快速开始

Claude Code

在项目根目录中添加 .mcp.json：

{
  "mcpServers": {
    "Multi Edit from Essential AI Solutions (essentialai.uk)": {
      "command": "npx",
      "args": ["-y", "@essentialai/mcp-multi-edit"]
    }
  }
}

重启 Claude Code。然后将随附的 CLAUDE.md 添加到项目根目录，以便 Claude 自动优先使用 multi_edit，而不是内置的 Edit 工具：

## Editing Files

When making multiple edits to the same file or across multiple files,
prefer using the `multi_edit` and `multi_edit_files` MCP tools over
the built-in Edit tool. These batch edits atomically in a single call.

完成——此后，只要 multi_edit 是合适的工具，Claude 就会使用它。

显示名称： Claude Code 会使用 mcpServers 中的键名作为服务的显示名称。你可以将键名更改为任意名称。

替代方式： 通过 CLI 使用单行命令：

claude mcp add --transport stdio multi-edit -- npx -y @essentialai/mcp-multi-edit

注意： CLI 仅接受简单名称（字母、数字、连字符、下划线）。如需完整的品牌显示名称，请使用上述 .mcp.json 方式。

Claude Desktop

添加到配置文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "Multi Edit from Essential AI Solutions (essentialai.uk)": {
      "command": "npx",
      "args": ["-y", "@essentialai/mcp-multi-edit"]
    }
  }
}

重启 Claude Desktop。

完整安装指南： docs/installation.md

工具

multi_edit —— 单个文件，多项编辑

在一个文件上批量执行多项查找和替换操作。编辑会按顺序以原子方式应用。

{
  "file_path": "/project/src/app.ts",
  "edits": [
    { "old_string": "const oldName = getValue()", "new_string": "const newName = getValue()" },
    { "old_string": "console.log", "new_string": "logger.info", "replace_all": true }
  ]
}

参数	类型	默认值	说明
file_path	string	必填	文件的绝对路径
edits	array	必填	查找和替换操作（按顺序应用）
edits[].old_string	string	必填	要查找的文本（精确匹配）
edits[].new_string	string	必填	替换文本
edits[].replace_all	boolean	false	替换所有匹配项
dry_run	boolean	false	预览更改，但不应用
backup	boolean	true	编辑前创建 .bak 备份

multi_edit_files —— 多个文件，一次原子操作

协调多个文件的编辑。如果任何文件操作失败，所有文件都会自动回滚。

{
  "files": [
    {
      "file_path": "/project/src/types.ts",
      "edits": [
        { "old_string": "interface UserData {", "new_string": "interface UserProfile {" }
      ]
    },
    {
      "file_path": "/project/src/api.ts",
      "edits": [
        { "old_string": "UserData", "new_string": "UserProfile", "replace_all": true }
      ]
    }
  ]
}

参数	类型	默认值	说明
files	array	必填	文件编辑操作数组
files[].file_path	string	必填	文件的绝对路径
files[].edits	array	必填	此文件的编辑操作（格式同上）
dry_run	boolean	false	预览更改，但不应用

完整用法指南及示例： docs/usage.md

功能

• 原子操作 —— 所有编辑要么全部成功，要么全部不应用，不会产生部分状态
• 多文件回滚 —— 如果任一文件失败，所有之前已更改的文件都会恢复
• 试运行预览 —— 提交前准确查看将发生哪些更改
• 自动备份 —— 每次编辑前都会创建 .bak 文件（使用 backup: false 禁用）
• 结构化错误 —— 提供机器可读的错误代码和恢复提示，以便自动重试
• 冲突检测 —— 当 old_string 匹配多个位置时发出警告
• 路径验证 —— 强制使用绝对路径、解析符号链接并检查路径是否存在

错误代码

代码	可重试	描述
MATCH_NOT_FOUND	是	在文件中找不到 old_string
AMBIGUOUS_MATCH	是	old_string 匹配多个位置
VALIDATION_FAILED	是	输入架构无效
FILE_NOT_FOUND	否	文件不存在
PERMISSION_DENIED	否	文件权限不足
BACKUP_FAILED	否	无法创建备份文件

当 retryable 为 true 时，Claude 会读取响应中的 recovery_hints，调整输入并自动重试。

故障排除指南： docs/troubleshooting.md

要求

• Node.js 20 或更高版本
• Claude Code 或 Claude Desktop

开发

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm test              # Run 264 tests
npm run test:coverage # Coverage report (90%+)
npm run benchmark     # Run benchmark suite
npm run dev           # Watch mode

项目结构

src/
  index.ts              # MCP server entry (stdio transport)
  server.ts             # Server factory and tool registration
  tools/
    multi-edit.ts       # multi_edit tool handler
    multi-edit-files.ts # multi_edit_files tool handler
  core/
    editor.ts           # File editing engine (atomic read-modify-write)
    validator.ts        # Zod input validation schemas
    reporter.ts         # Result formatting and diff generation
    errors.ts           # Error classification and envelope creation
  types/
    index.ts            # TypeScript type definitions

文档

文档	描述
安装指南	Claude Code 和 Claude Desktop 的所有设置选项
使用指南	详细的工具参考和示例
故障排除	常见问题及解决方案
变更日志	版本历史
基准测试报告	性能测量结果

许可证

PolyForm Noncommercial License 1.0.0

可免费用于个人和非商业用途。商业许可请联系 [email protected]。

---

由 Essential AI Solutions 构建