dabito/hledit-mcp

hledit-mcp is an MCP server exposing hledit's hash-anchored file edits to standard MCP clients such as Claude Code, Claude Desktop, and Cursor.
Same idea as pi-hledit (the Pi-native integration), but over MCP instead of Pi's extension API, so the same edit primitive can be used from MCP-compatible clients.
Official MCP Registry: io.github.dabito/hledit-mcp.
Instead of asking an agent to reproduce old text exactly, hledit read annotates each line with a stable anchor:
Write commands reference anchors such as 6#M9A. Before changing the file, hledit recomputes the hash at that line. If the file changed since it was read, the anchor is rejected and no write happens — the agent gets a stale error and a remap hint instead of silently corrupting the wrong line.
Demo
See docs/demo/transcript.md for a deterministic MCP stdio transcript showing stale-write rejection over the actual hledit-mcp tool surface.
The transcript is generated by docs/demo/hledit-mcp-demo.mjs, which drives dist/index.js through @modelcontextprotocol/sdk's stdio client. It does not call hledit directly.
MCP server for stale-write-safe file editing
hledit-mcp gives MCP-compatible coding agents one file-editing tool that reads line anchors, validates those anchors against current file contents, and rejects stale writes before touching disk. It is for local workspace edits where you want explicit stale-context failure instead of blind text replacement.
Why MCP, separately from pi-hledit
pi-hledit and hledit-mcp share the same tool contract (core.ts in this repo — arg-building, batch translation, result formatting) and the same underlying hledit CLI. Only the registration/execution glue differs: pi-hledit wires that contract into Pi's registerTool, this wires it into @modelcontextprotocol/sdk's McpServer. MCP has no equivalent of Pi's renderCall/renderResult terminal rendering, so this package doesn't have one either — that layer is genuinely Pi-specific chrome, not part of the portable tool contract.
Use hledit-mcp when you want stale-write rejection over an MCP tool boundary instead of relying on a host's native text replacement behavior.
Requirements
- Go 1.21+ to install the hledit CLI (or a prebuilt binary on PATH)
- Node.js 18+
- An MCP-compatible client
Install
Install the hledit CLI first:
Then configure your MCP client to run hledit-mcp. For Claude Code, verify the current CLI syntax with claude mcp add --help; recent versions use:
Claude Desktop and other MCP clients can use the same stdio server shape:
Set HLEDIT_CWD to the workspace the MCP client should allow hledit to edit.
Configuration
| Variable | Default | Description |
| --- | --- | --- |
| HLEDIT_BIN | hledit (on PATH) | Path to the hledit binary, if not on PATH. |
| HLEDIT_CWD | server's process.cwd() | Working directory hledit resolves relative paths against. Keep this scoped to the workspace you expect the MCP client to edit. |
| HLEDIT_MCP_DIFF | 0 | Opt-in textual diff output for successful edit/batch calls. Off by default to keep MCP/model context compact. Set 1, true, or yes to enable. |
| HLEDIT_MCP_DIFF_MAX_LINES | 80 | Max diff lines when HLEDIT_MCP_DIFF is enabled, including the omission marker. Minimum accepted value: 3. |
| HLEDIT_MCP_DIFF_CONTEXT | 2 | Context lines around changed ranges when diff output is enabled. Minimum accepted value: 0. |