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:

5#K7Q:func main() {
6#M9A:    fmt.Println("hello")
7#R2C:}

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:

go install github.com/dabito/hledit@latest

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 mcp add hledit -- npx -y hledit-mcp

Claude Desktop and other MCP clients can use the same stdio server shape:

{
  "mcpServers": {
    "hledit": {
      "command": "npx",
      "args": ["-y", "hledit-mcp"],
      "env": {
        "HLEDIT_CWD": "/path/to/workspace"
      }
    }
  }
}

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.
HLEDIT_MCP_DIFF_MAX_CELLS	40000	Max LCS comparison cells before diff body is omitted. Minimum accepted value: 1.

Tool

hledit

One tool, three operations, matching pi-hledit's contract exactly:

op	Purpose
read	Read annotated lines with LN#HASH anchors
edit	Apply a single replace/insert/delete/replace-range
batch	Apply multiple anchor-referenced edits in one call

Name	Type	Required	Description
op	string	✓	"read", "edit", or "batch"
path	string	✓	File path
offset	number		1-indexed starting line (read)
limit	number		Max lines to return (read); defaults to 2000
context	number		Surrounding lines around each grep match; defaults to 2 when grep is set, use 0 for match-only output
grep	string		Filter lines by substring (read)
action	string		replace, insert, delete, or replace-range (edit)
end_anchor	string		End anchor for replace-range/range delete
content	string		Replacement/inserted content; empty = delete
after	boolean		For action:"insert", insert after the anchor
edits	array or string	for batch	Preferred: structured array of batch edit ops (replace/delete/insert). Legacy JSON string still accepted.

Workflow: read to get anchors → edit (single change) or batch (multiple). If an edit returns stale, re-read to get fresh anchors before retrying — the anchor's line moved or changed since it was read.

Successful edit and batch calls return concise summaries, including Lines: +N -M when the installed hledit CLI provides line delta metadata (hledit >= 1.2.4). Older hledit versions still work; they just omit the line delta summary.

Contextual grep uses a small default window (context:2) when grep is set; pass context:0 for match-only output.

Set HLEDIT_MCP_DIFF=1 to append a capped fenced diff block for successful edits. Leave it off for the most token-economical MCP responses.

Preferred batch shape uses structured edits so the MCP/RPC layer handles escaping:

{
  "op": "batch",
  "path": "src/file.ts",
  "edits": [
    { "op": "replace", "anchor": "12#NKT", "lines": ["const ok = true;"] }
  ]
}

Contextual grep example:

{ "op": "read", "path": "src/file.ts", "grep": "validateToken" }

Match-only grep example:

{ "op": "read", "path": "src/file.ts", "grep": "validateToken", "context": 0 }

Legacy JSON-string edits remains supported during the transition.

Default read calls are bounded: when offset/limit are omitted, the server uses offset=1 and limit=2000.

Development

npm install
npm test          # typecheck + build + unit/e2e tests + lint
npm run build      # compile index.ts+core.ts to dist/index.js
npm start         # run the server directly from source via tsx (stdio transport)

Unit tests in core.test.ts cover the same contract as pi-hledit's test suite, minus the Pi-specific rendering assertions (there's no render layer here). e2e.test.ts drives the built dist/index.js over a real MCP stdio handshake with @modelcontextprotocol/sdk's own Client/StdioClientTransport — the same artifact npx hledit-mcp runs, not just the TypeScript source.

The published bin/main point at dist/index.js, built with esbuild (build.mjs) and run via plain node — this keeps the >=18 Node requirement honest. Running index.ts directly with node (no tsx) only works on Node ≥22.6, which has built-in TypeScript type-stripping; older LTS versions have no such support at all.

Credits and prior art

The hashline-edit idea comes from Can Bölük / @can1357's coding-agent harness work, especially “I Improved 15 LLMs at Coding in One Afternoon. Only the Harness Changed.” and oh-my-pi. See hledit's credits for more prior art.

Related packages

• hledit — the standalone CLI both integrations wrap.
• pi-hledit — the Pi-native integration, same tool contract.