{
  "markdown": "# hledit-mcp\n[![npm version](https://img.shields.io/npm/v/hledit-mcp.svg)](https://www.npmjs.com/package/hledit-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.dabito%2Fhledit--mcp-blue)](https://registry.modelcontextprotocol.io/?search=hledit)\n[![Glama](https://glama.ai/mcp/servers/dabito/hledit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/dabito/hledit-mcp)\n\n`hledit-mcp` is an MCP server exposing [`hledit`](https://github.com/dabito/hledit)'s hash-anchored file edits to standard MCP clients such as Claude Code, Claude Desktop, and Cursor.\n\nSame idea as [`pi-hledit`](https://github.com/dabito/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.\nOfficial MCP Registry: [`io.github.dabito/hledit-mcp`](https://registry.modelcontextprotocol.io/?search=hledit).\n\nInstead of asking an agent to reproduce old text exactly, `hledit read` annotates each line with a stable anchor:\n\n```text\n5#K7Q:func main() {\n6#M9A:    fmt.Println(\"hello\")\n7#R2C:}\n```\n\nWrite 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.\n\n## Demo\n\nSee [`docs/demo/transcript.md`](docs/demo/transcript.md) for a deterministic MCP stdio transcript showing stale-write rejection over the actual `hledit-mcp` tool surface.\n\nThe transcript is generated by [`docs/demo/hledit-mcp-demo.mjs`](docs/demo/hledit-mcp-demo.mjs), which drives `dist/index.js` through `@modelcontextprotocol/sdk`'s stdio client. It does not call `hledit` directly.\n\n## MCP server for stale-write-safe file editing\n\n`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.\n\n## Why MCP, separately from pi-hledit\n\n`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.\n\nUse `hledit-mcp` when you want stale-write rejection over an MCP tool boundary instead of relying on a host's native text replacement behavior.\n\n## Requirements\n\n- [Go 1.21+](https://go.dev/) to install the `hledit` CLI (or a prebuilt binary on `PATH`)\n- Node.js 18+\n- An MCP-compatible client\n\n## Install\n\nInstall the `hledit` CLI first:\n\n```bash\ngo install github.com/dabito/hledit@latest\n```\n\nThen configure your MCP client to run `hledit-mcp`. For Claude Code, verify the current CLI syntax with `claude mcp add --help`; recent versions use:\n\n```bash\nclaude mcp add hledit -- npx -y hledit-mcp\n```\n\nClaude Desktop and other MCP clients can use the same stdio server shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"hledit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"hledit-mcp\"],\n      \"env\": {\n        \"HLEDIT_CWD\": \"/path/to/workspace\"\n      }\n    }\n  }\n}\n```\n\nSet `HLEDIT_CWD` to the workspace the MCP client should allow `hledit` to edit.\n\n### Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `HLEDIT_BIN` | `hledit` (on `PATH`) | Path to the `hledit` binary, if not on `PATH`. |\n| `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. |\n| `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. |\n| `HLEDIT_MCP_DIFF_MAX_LINES` | `80` | Max diff lines when `HLEDIT_MCP_DIFF` is enabled, including the omission marker. Minimum accepted value: `3`. |\n| `HLEDIT_MCP_DIFF_CONTEXT` | `2` | Context lines around changed ranges when diff output is enabled. Minimum accepted value: `0`. |\n| `HLEDIT_MCP_DIFF_MAX_CELLS` | `40000` | Max LCS comparison cells before diff body is omitted. Minimum accepted value: `1`. |\n\n## Tool\n\n### `hledit`\n\nOne tool, three operations, matching `pi-hledit`'s contract exactly:\n\n| `op`    | Purpose                                            |\n| ------- | --------------------------------------------------- |\n| `read`  | Read annotated lines with LN#HASH anchors             |\n| `edit`  | Apply a single replace/insert/delete/replace-range  |\n| `batch` | Apply multiple anchor-referenced edits in one call  |\n\n| Name         | Type    | Required           | Description                                                          |\n| ------------ | ------- | ------------------ | ---------------------------------------------------------------------- |\n| `op`         | string  | ✓                  | `\"read\"`, `\"edit\"`, or `\"batch\"`                                      |\n| `path`       | string  | ✓                  | File path                                                             |\n| `offset`     | number  |                    | 1-indexed starting line (`read`)                                      |\n| `limit`      | number  |                    | Max lines to return (`read`); defaults to `2000`                     |\n| `context`    | number  |                    | Surrounding lines around each grep match; defaults to `2` when `grep` is set, use `0` for match-only output |\n| `grep`       | string  |                    | Filter lines by substring (`read`)                                    |\n| `action`     | string  |                    | `replace`, `insert`, `delete`, or `replace-range` (`edit`)             |\n| `end_anchor` | string  |                    | End anchor for `replace-range`/range delete                           |\n| `content`    | string  |                    | Replacement/inserted content; empty = delete                          |\n| `after`      | boolean |                    | For `action:\"insert\"`, insert after the anchor                       |\n| `edits`      | array or string | for `batch` | Preferred: structured array of batch edit ops (`replace`/`delete`/`insert`). Legacy JSON string still accepted. |\n\nWorkflow: `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.\n\nSuccessful `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.\n\nContextual grep uses a small default window (`context:2`) when `grep` is set; pass `context:0` for match-only output.\n\nSet `HLEDIT_MCP_DIFF=1` to append a capped fenced `diff` block for successful edits. Leave it off for the most token-economical MCP responses.\n\nPreferred batch shape uses structured `edits` so the MCP/RPC layer handles escaping:\n\n```json\n{\n  \"op\": \"batch\",\n  \"path\": \"src/file.ts\",\n  \"edits\": [\n    { \"op\": \"replace\", \"anchor\": \"12#NKT\", \"lines\": [\"const ok = true;\"] }\n  ]\n}\n```\nContextual grep example:\n\n```json\n{ \"op\": \"read\", \"path\": \"src/file.ts\", \"grep\": \"validateToken\" }\n```\n\nMatch-only grep example:\n\n```json\n{ \"op\": \"read\", \"path\": \"src/file.ts\", \"grep\": \"validateToken\", \"context\": 0 }\n```\n\n\nLegacy JSON-string `edits` remains supported during the transition.\n\nDefault `read` calls are bounded: when `offset`/`limit` are omitted, the server uses `offset=1` and `limit=2000`.\n\n## Development\n\n```bash\nnpm install\nnpm test          # typecheck + build + unit/e2e tests + lint\nnpm run build      # compile index.ts+core.ts to dist/index.js\nnpm start         # run the server directly from source via tsx (stdio transport)\n```\n\nUnit 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.\n\nThe 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.\n\n## Credits and prior art\n\nThe 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.”](https://blog.can.ac/2026/02/12/the-harness-problem/) and [`oh-my-pi`](https://github.com/can1357/oh-my-pi). See [`hledit`'s credits](https://github.com/dabito/hledit#credits-and-prior-art) for more prior art.\n\n## Related packages\n\n- [`hledit`](https://github.com/dabito/hledit) — the standalone CLI both integrations wrap.\n- [`pi-hledit`](https://github.com/dabito/pi-hledit) — the Pi-native integration, same tool contract.\n",
  "bytes": 9697,
  "sha": "e0048ec64f2e841758e2e3ed75c6f91634bc19c3f8f08c00c89c6ef9c2f0483b",
  "repo_slug": "dabito/hledit-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dabito_hledit_mcp_3a583de7/readme"
}