hledit MCP

hledit-mcp

hledit-mcp は、Claude Code、Claude Desktop、Cursor などの標準的な MCP クライアントに、hledit のハッシュアンカー付きファイル編集機能を提供する MCP サーバーです。

Pi ネイティブの統合である pi-hledit と同じ発想ですが、Pi の拡張 API ではなく MCP を介しているため、同じ編集プリミティブを MCP 対応クライアントから利用できます。 公式 MCP Registry：io.github.dabito/hledit-mcp。

エージェントに古いテキストを正確に再現させる代わりに、hledit read は各行に安定したアンカーを付けます。

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

書き込みコマンドでは、6#M9A のようなアンカーを指定します。ファイルを変更する前に、hledit はその行のハッシュを再計算します。読み取り後にファイルが変更されていた場合、アンカーは拒否され、書き込みは行われません。エージェントには、誤った行を気づかないまま破損させる代わりに、stale エラーと再マッピングのヒントが返されます。

デモ

実際の hledit-mcp ツールを通じて、古いアンカーによる書き込みが拒否される様子を示した、決定論的な MCP stdio の記録については、docs/demo/transcript.md をご覧ください。

この記録は、dist/index.js を @modelcontextprotocol/sdk の stdio クライアント経由で実行する docs/demo/hledit-mcp-demo.mjs によって生成されます。hledit を直接呼び出すことはありません。

古い書き込みを安全に扱うファイル編集用 MCP サーバー

hledit-mcp は、行アンカーを読み取り、現在のファイル内容と照合してアンカーを検証し、ディスクに変更を加える前に古いアンカーによる書き込みを拒否するファイル編集ツールを、MCP 対応のコーディングエージェントに提供します。これは、無条件なテキスト置換ではなく、古いコンテキストを明示的に検出して失敗させたいローカルワークスペースの編集向けです。

pi-hledit とは別に MCP を使う理由

pi-hledit と hledit-mcp は、同じツール契約（このリポジトリの core.ts。引数の構築、バッチ変換、結果のフォーマット）と、同じ基盤となる hledit CLI を共有しています。異なるのは登録と実行をつなぐ部分だけです。pi-hledit はその契約を Pi の registerTool に接続し、こちらは @modelcontextprotocol/sdk の McpServer に接続します。MCP には Pi の renderCall／renderResult に相当するターミナル表示機能がないため、このパッケージにもありません。このレイヤーは持ち運び可能なツール契約の一部ではなく、Pi 固有の装飾だからです。

ホストのネイティブなテキスト置換の動作に頼らず、MCP ツールの境界で古い書き込みを拒否したい場合は、hledit-mcp を使用してください。

要件

• hledit CLI のインストールには Go 1.21+（または PATH 上にあるビルド済みバイナリ）
• Node.js 18+
• MCP 対応クライアント

インストール

まず hledit CLI をインストールします。

go install github.com/dabito/hledit@latest

次に、hledit-mcp を実行するよう MCP クライアントを設定します。Claude Code では、claude mcp add --help で現在の CLI 構文を確認してください。最近のバージョンでは次のように指定します。

claude mcp add hledit -- npx -y hledit-mcp

Claude Desktop やその他の MCP クライアントでも、同じ stdio サーバー形式を使用できます。

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

HLEDIT_CWD に、MCP クライアントが hledit に編集を許可するワークスペースを設定してください。

設定

変数	デフォルト	説明
HLEDIT_BIN	hledit（PATH 上）	PATH 上にない場合の hledit バイナリへのパスです。
HLEDIT_CWD	サーバーの process.cwd()	hledit が相対パスを解決する際の作業ディレクトリです。MCP クライアントに編集させる想定のワークスペースに限定してください。
HLEDIT_MCP_DIFF	0	edit／batch 呼び出しが成功したときに、テキスト形式の差分を出力するかどうかを指定します。MCP／モデルのコンテキストを簡潔に保つため、デフォルトでは無効です。有効にするには 1、true、または yes を設定してください。
HLEDIT_MCP_DIFF_MAX_LINES	80	HLEDIT_MCP_DIFF が有効な場合の差分の最大行数です。省略マーカーを含みます。設定可能な最小値：3。
HLEDIT_MCP_DIFF_CONTEXT	2	差分出力が有効な場合に、変更範囲の前後に表示するコンテキスト行数です。設定可能な最小値：0。
HLEDIT_MCP_DIFF_MAX_CELLS	40000	差分本文を省略するまでの LCS 比較セルの最大数です。設定可能な最小値：1。

ツール

hledit

1 つのツールで 3 つの操作を実行でき、pi-hledit の仕様に完全に準拠しています。

op	目的
read	LN#HASH アンカー付きの行を読み取ります
edit	1 つの置換／挿入／削除／範囲置換を適用します
batch	1 回の呼び出しで、複数のアンカー参照編集を適用します

名前	型	必須	説明
op	文字列	✓	"read"、"edit"、または "batch"
path	文字列	✓	ファイルパス
offset	数値		開始行（1 始まり）（read）
limit	数値		返す最大行数（read）。デフォルトは 2000
context	数値		各 grep マッチ前後の行数。grep が設定されている場合のデフォルトは 2 です。マッチした行のみを出力するには 0 を指定します
grep	文字列		部分文字列で行を絞り込みます（read）
action	文字列		replace、insert、delete、または replace-range（edit）
end_anchor	文字列		replace-range／範囲削除の終了アンカー
content	文字列		置換／挿入する内容。空の場合は削除
after	ブール値		action:"insert" の場合、アンカーの後に挿入します
edits	配列または文字列	batch の場合に必須	推奨形式：バッチ編集操作（replace／delete／insert）の構造化配列。従来の JSON 文字列も引き続き使用できます。

ワークフロー：read でアンカーを取得し、edit（単一の変更）または batch（複数の変更）を実行します。編集結果が stale の場合は、再試行する前に再度読み取って新しいアンカーを取得してください。読み取り後にアンカーの行が移動または変更されています。

edit と batch の成功時には簡潔な概要が返されます。インストール済みの hledit CLI が行差分のメタデータを提供する場合（hledit >= 1.2.4）、Lines: +N -M も含まれます。古いバージョンの hledit でも動作しますが、行差分の概要は表示されません。

コンテキスト付き grep では、grep が設定されている場合のデフォルトで小さなウィンドウ（context:2）を使用します。マッチした行のみを出力するには context:0 を指定してください。

成功した編集の後に、上限付きのフェンス付き diff ブロックを追加するには HLEDIT_MCP_DIFF=1 を設定します。MCP の応答を最もトークン効率よくするには、設定しないでください。

エスケープ処理を MCP/RPC レイヤーに任せるため、構造化された edits を使うバッチ形式を推奨します。

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

コンテキスト付き grep の例：

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

マッチした行のみを出力する grep の例：

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

移行期間中は、従来の JSON 文字列形式の edits も引き続き使用できます。

デフォルトの read 呼び出しには上限があります。offset／limit を省略すると、サーバーは offset=1、limit=2000 を使用します。

開発

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)

core.test.ts のユニットテストでは、Pi 固有のレンダリングに関するアサーション（ここにはレンダリング層がありません）を除き、pi-hledit のテストスイートと同じ仕様をカバーしています。e2e.test.ts は、@modelcontextprotocol/sdk 自身の Client／StdioClientTransport を使い、実際の MCP stdio ハンドシェイクを通じてビルド済みの dist/index.js を実行します。これは TypeScript ソースだけではなく、npx hledit-mcp が実行するものと同じ成果物です。

公開される bin／main は dist/index.js を指しています。このファイルは esbuild（build.mjs）でビルドされ、通常の node で実行されるため、>=18 という Node の要件に偽りはありません。index.ts を node で直接実行する場合（tsx なし）、組み込みの TypeScript 型ストリッピング機能を備えた Node ≥22.6 でのみ動作します。それより古い LTS バージョンには、そのようなサポートは一切ありません。

クレジットと先行事例

hashline-edit のアイデアは、Can Bölük / @can1357 のコーディングエージェントのハーネスに関する取り組み、特に「I Improved 15 LLMs at Coding in One Afternoon. Only the Harness Changed.」とoh-my-piに着想を得ています。その他の先行事例については、hleditのクレジットをご覧ください。

関連パッケージ

• hledit — 両方の統合がラップするスタンドアロンの CLI です。
• pi-hledit — Pi ネイティブの統合で、同じツールコントラクトを使用します。