用途
hledit-mcp 是一个 MCP 服务器，把 hledit 的哈希锚定文件编辑能力提供给标准 MCP 客户端，例如 Claude Code、Claude Desktop 和 Cursor。它与 pi-hledit（Pi 原生集成）思路相同，但通过 MCP 而非 Pi 的扩展 API 实现，因此同一编辑原语可在兼容 MCP 的客户端中使用。官方 MCP Registry 标识为 io.github.dabito/hledit-mcp。
它适用于本地工作区编辑场景：你希望获得显式的过期上下文失败，而不是盲目的文本替换。
主要能力
- 哈希锚定编辑：读取文件时，hledit read 会为每一行标注一个稳定锚点，例如 6#M9A。
- 过期写入拒绝：写入命令引用锚点；在更改文件前，hledit 会重新计算该行哈希。如果文件自读取后已变化，锚点被拒绝，不会发生写入，智能体收到过期错误和重映射提示，而不是静默损坏错误的行。
- 单一工具、三种操作，与 pi-hledit 的契约完全一致：read（获取锚点）、edit（单次更改）、batch（多次更改）。
- 成功编辑和批量调用返回简洁摘要，当安装的 hledit CLI 提供行增量元数据（hledit >= 1.2.4）时包含 Lines: +N -M。较旧版本仍可用，只是省略行增量摘要。
- 上下文 grep：当设置 grep 时使用较小的默认窗口（context:2）；传入 context:0 可获得仅匹配输出。
- 可选 diff：设置 HLEDIT_MCP_DIFF=1 可为成功编辑追加一个受限的围栏 diff 块；关闭可获得最省 token 的 MCP 响应。
- 默认读取有界：当省略 offset / limit 时，服务器使用 offset=1 和 limit=2000。
使用方式
前置条件：Go 1.21+ 用于安装 hledit CLI（或使用 PATH 中的预构建二进制），以及一个兼容 MCP 的客户端。
先安装 hledit CLI，然后配置 MCP 客户端运行 hledit-mcp。对于 Claude Code，用 claude mcp add --help 确认当前 CLI 语法；近期版本使用相应命令。Claude Desktop 和其他 MCP 客户端可使用相同的 stdio 服务器形态。设置 HLEDIT_CWD 为 MCP 客户端应允许 hledit 编辑的工作区。
工作流：read 获取锚点 → edit（单次更改）或 batch（多次更改）。如果编辑返回 stale，重新读取以获取新锚点后再重试——锚点所在行自读取后已移动或改变。
首选批量形态使用结构化 edits，以便 MCP/RPC 层处理转义。也提供上下文 grep 示例和仅匹配 grep 示例。过渡期间仍支持旧式 JSON 字符串 edits。
适用场景
- 在 MCP 工具边界上需要过期写入拒绝，而不是依赖宿主原生文本替换行为。
- 使用 Claude Code、Claude Desktop、Cursor 等 MCP 兼容客户端的编码智能体进行本地工作区编辑。
限制与说明
- MCP 没有 Pi 的 renderCall / renderResult 终端渲染等价物，因此本包也没有该层；那层是 Pi 特有的界面，不属于可移植工具契约。
- 已发布的 bin / main 指向 dist/index.js，用 esbuild（build.mjs）构建并通过普通 node 运行，以保持 >=18 Node 要求。直接用 node（无 tsx）运行 index.ts 仅在 Node ≥22.6 上有效，因其内置 TypeScript 类型剥离；较旧的 LTS 版本完全不支持。
- 单元测试 core.test.ts 覆盖与 pi-hledit 测试套件相同的契约，减去 Pi 特有的渲染断言。e2e.test.ts 通过 @modelcontextprotocol/sdk 的 Client / StdioClientTransport 在真实 MCP stdio 握手上驱动构建后的 dist/index.js。
- 哈希行编辑思路来自 Can Bölük / @can1357 的编码智能体 harness 工作，尤其是相关文章和 oh-my-pi；更多先前技术见 hledit 的 credits。
- 相关包：hledit（两个集成包装的独立 CLI）、pi-hledit（Pi 原生集成，相同工具契约）。
演示
参见 docs/demo/transcript.md，其中包含一个确定性的 MCP stdio 记录，展示在实际 hledit-mcp 工具表面上拒绝过期写入。该记录由 docs/demo/hledit-mcp-demo.mjs 生成，它通过 @modelcontextprotocol/sdk 的 stdio 客户端驱动 dist/index.js，不直接调用 hledit。
