Readedit

npm version CI License: MIT

Combine Read+Edit into single tool calls — 80-95% fewer tool calls for multi-file refactoring.

An MCP server that gives any AI coding assistant batch file operations. Instead of separate Read → Edit calls per file, do it all in one shot.

Quick Start

No install needed — run directly with npx:

npx mcp-readedit

Or install globally for faster startup:

npm install -g mcp-readedit

Then add it to your MCP client (see Client Setup below).

Client Setup

Claude Desktop

Add to ~/.claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

claude mcp add readedit -- npx mcp-readedit

Cursor

Add to .cursor/mcp.json in your project:

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

Windsurf

Go to Settings → MCP Servers and add:

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

Cline (VS Code Extension)

In Cline settings, add to MCP Servers:

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

Continue

Add to .continue/config.yaml:

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

Zed

Add to your Zed settings.json:

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

Tools

Tool	What it does
read_edit	Read a file, optionally edit it — 1 call instead of 2
multi_edit	Edit multiple files at once
multi_read_edit	Read + optionally edit multiple files — the powerhouse
get_gain	Show your token savings statistics

read_edit — Single file read + optional edit

Read a file and optionally replace text in one call. Returns file content.

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

Options: use_regex (boolean), replace_all (boolean), offset (line number), limit (line count). Omit old_string/new_string to just read.

multi_edit — Edit multiple files

Batch edits across files in a single call. Use when you already have the file contents.

{
  "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 — Read + edit multiple files

The most powerful tool. Read and optionally edit any number of files in one call.

{
  "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 }
  ]
}

Options: include_content (boolean, default false) and include_original (boolean, default false) control what's returned.

get_gain — Token savings stats

{ "breakdown": "summary" }

Breakdown types: summary (default), daily, recent, all.

Before / After

Refactoring a feature across 9 files:

Without MCP ReadEdit — 52 tool calls:

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

With MCP ReadEdit — 4 tool calls:

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

Result: 48 calls saved (~9,600 tokens)

How Gain Tracking Works

Each tool call is recorded to a local SQLite database. The tracker calculates what it would have taken with standard Read+Edit calls:

• read_edit with edit: 2 standard calls → 1 optimized call
• multi_edit (N files): 2N standard calls → 1 optimized call
• multi_read_edit (N files): 2N standard calls → 1 optimized call

Token savings are estimated at ~200 tokens per avoided call (JSON overhead, tool result wrapping). The database auto-creates on first use.

CLI Usage

If installed globally (npm install -g mcp-readedit), the readedit command gives terminal access to gain stats:

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

Works with npx too: npx mcp-readedit starts the server, readedit gain runs the CLI.

AGENTS.md / CLAUDE.md Integration

Add these instructions to your project's CLAUDE.md, AGENTS.md, or .cursorrules to make your AI coding assistant automatically use ReadEdit tools:

## 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

For global usage (all projects), add to ~/.claude/AGENTS.md instead.

Contributing

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

Issues and PRs welcome at github.com/abnersajr/mcp-readedit.

License

MIT