hledit-mcp

hledit-mcp is an MCP server exposing hledit's hash-anchored file edits to any MCP-compatible AI coding agent — Claude Code, Claude Desktop, Cursor, and others.

Same idea as pi-hledit (the Pi-native integration), but over MCP instead of Pi's extension API, so it reaches every MCP host, not just Pi.

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.

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.

Related MCP server: mcp-hashline-edit-server

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.

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.

Related packages

• hledit — the standalone CLI both integrations wrap.

• pi-hledit — the Pi-native integration, same tool contract.