Readedit

MCP ReadEdit

为什么？

每次 AI 编码助手编辑文件时，通常都需要两次工具调用：一次读取文件，然后一次编辑文件。要重构 5 个文件？需要调用 10 次。重构 20 个文件？需要调用 40 次——每次调用都会因 JSON 开销消耗令牌、等待往返，并占用上下文。

MCP ReadEdit 将这些成对的操作合并为单次调用。一次完成读取和编辑。在一次调用中批量编辑多个文件。结果：工具调用减少 80–95%，完成速度更快，令牌用量也大幅降低。

将读取和编辑合并为单次工具调用——多文件重构时，工具调用减少 80-95%。

一个为任何 AI 编码助手提供批量文件操作的 MCP 服务。无需逐个文件分别调用读取 → 编辑，一次调用即可完成所有操作。

要求

• Node.js 20+（推荐：最新 LTS 版本）

快速开始

无需安装——直接使用 npx 运行：

npx mcp-readedit

也可以全局安装以加快启动速度：

npm install -g mcp-readedit

然后将其添加到你的 MCP 客户端中（参见下方的客户端设置）。

客户端设置

Claude Desktop

添加到 ~/.claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "readedit": {
      "command": "npx",
      "args": ["mcp-readedit"]
    }
  }
}

Claude Code

claude mcp add readedit -- npx mcp-readedit

Cursor

添加到项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "readedit": {
      "command": "npx",
      "args": ["mcp-readedit"]
    }
  }
}

Windsurf

前往设置 → MCP Servers并添加：

{
  "readedit": {
    "command": "npx",
    "args": ["mcp-readedit"]
    }
}

Cline（VS Code 扩展）

在 Cline 设置中，将其添加到 MCP Servers：

{
  "readedit": {
    "command": "npx",
    "args": ["mcp-readedit"]
  }
}

Continue

添加到 .continue/config.yaml：

mcpServers:
  - name: readedit
    command: npx
    args:
      - mcp-readedit

Zed

添加到 Zed 的 settings.json：

{
  "context_servers": {
    "readedit": {
      "command": "npx",
      "args": ["mcp-readedit"]
    }
  }
}

工具

工具	功能
read_edit	读取文件，并可选择编辑——用 1 次调用代替 2 次
multi_edit	一次编辑多个文件
multi_read_edit	读取并可选择编辑多个文件——功能最强大的工具
get_gain	显示令牌节省统计数据

read_edit — 读取单个文件并可选择编辑

一次调用即可读取文件，并可选择替换文本。返回文件内容。

{
  "file_path": "/absolute/path/to/file.ts",
  "old_string": "text to replace",
  "new_string": "replacement text"
}

选项：use_regex（布尔值）、replace_all（布尔值）、offset（行号）、limit（行数）。省略 old_string/new_string 即可只读取文件。

multi_edit — 编辑多个文件

一次调用即可批量编辑多个文件。适用于你已经有文件内容的情况。

{
  "edits": [
    { "file_path": "/path/a.ts", "old_string": "foo", "new_string": "bar" },
    { "file_path": "/path/b.ts", "old_string": "baz", "new_string": "qux", "replace_all": true }
  ]
}

multi_read_edit — 读取并编辑多个文件

功能最强大的工具。一次调用即可读取任意数量的文件，并可选择编辑。

{
  "operations": [
    { "file_path": "/path/a.ts" },
    { "file_path": "/path/b.ts", "old_string": "old", "new_string": "new" },
    { "file_path": "/path/c.ts", "old_string": "\\d+", "new_string": "0", "use_regex": true }
  ]
}

选项：include_content（布尔值，默认 false）和 include_original（布尔值，默认 false）控制返回的内容。

get_gain — 令牌节省统计

{ "breakdown": "summary" }

统计类型：summary（默认）、daily、recent、all。

使用前 / 使用后

跨 9 个文件重构一项功能：

不使用 MCP ReadEdit——调用 52 次：

Read file1 → Edit file1 → Read file2 → Edit file2 → ... → Read file9 → Edit file9
28 Edit + 19 Read + 5 Write = 52 calls

使用 MCP ReadEdit——调用 4 次：

multi_read_edit (files 1-3) → multi_read_edit (files 4-6) → multi_read_edit (files 7-9) → multi_edit (final batch)

结果：节省 48 次调用（约 9,600 个令牌）

增益追踪的工作原理

每次工具调用都会记录到本地 SQLite 数据库中。追踪器会计算使用标准读取和编辑调用时本来需要多少操作：

• read_edit 并进行编辑：2 次标准调用 → 1 次优化调用
• multi_edit（N 个文件）：2N 次标准调用 → 1 次优化调用
• multi_read_edit（N 个文件）：2N 次标准调用 → 1 次优化调用

每减少一次调用，预计可节省约 200 个令牌（JSON 开销、工具结果封装）。数据库会在首次使用时自动创建。

命令行用法

如果已全局安装（npm install -g mcp-readedit），readedit 命令可在终端中查看增益统计数据：

readedit gain                  # Summary
readedit gain --daily          # Day-by-day breakdown
readedit gain --recent 20      # Last 20 operations
readedit gain --all            # All breakdowns
readedit gain --format json    # JSON export
readedit gain --reset          # Reset statistics

也可使用 npx：npx mcp-readedit 会启动服务，readedit gain 会运行命令行工具。

AGENTS.md / CLAUDE.md 集成

将以下说明添加到项目的 CLAUDE.md、AGENTS.md 或 .cursorrules 中，让 AI 编码助手自动使用 ReadEdit 工具：

## File Operations — MCP ReadEdit

When reading or editing files, ALWAYS prefer MCP ReadEdit tools over separate Read + Edit calls.

### Tool Selection
- **multi_read_edit**: Read and/or edit multiple files (most common — use for any multi-file task)
- **multi_edit**: Edit multiple files when you already have their contents
- **read_edit**: Single file read-only or read+edit
- **get_gain**: Check token savings statistics

### Rules
1. NEVER use separate Read then Edit calls when ReadEdit tools are available
2. Batch file operations: group related files into a single multi_read_edit call
3. Use `use_regex: true` for pattern-based replacements
4. Read-only operations in multi_read_edit always return file content — no need to separately read files first
5. When refactoring across multiple files, plan all edits first, then execute in one multi_read_edit call

如需全局使用（适用于所有项目），请改为添加到 ~/.claude/AGENTS.md。

贡献

git clone https://github.com/abnersajr/mcp-readedit.git
cd mcp-readedit
npm install
npm test

欢迎通过 github.com/abnersajr/mcp-readedit 提交问题和 PR。

许可证

MIT