Hledit MCP Server

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.

Instead of asking an agent to reproduce old text exactly, hledit read annotates each line with a stable anchor:

5#HY:func main() {
6#MX:    fmt.Println("hello")
7#NP:}

Write commands reference anchors such as 6#MX. 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.

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:

claude mcp add hledit npx hledit-mcp

Or add it manually to your client's MCP server config:

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

Configuration

Tool

hledit

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

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.

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.