mcp-hashline-edit-server 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,12 @@
 # mcp-hashline-edit-server
 
-An MCP (Model Context Protocol) server that provides hashline-based file editing tools — line-addressed edits using content hashes for integrity verification.
+MCP server providing hashline-based file editing — line-addressed edits with content hashes for integrity verification.
 
-Based on the [hashline edit format](https://blog.can.ac/2026/02/12/the-harness-problem/) from [oh-my-pi](https://github.com/can1357/oh-my-pi).
+Based on [hashline edit format](https://blog.can.ac/2026/02/12/the-harness-problem/) from [oh-my-pi](https://github.com/can1357/oh-my-pi).
 
 ## What is Hashline?
 
-When an LLM reads a file, every line comes back tagged with a short content hash:
+LLM reads file, every line tagged with short content hash:
 
 ```
 1:a3|function hello() {
@@ -14,78 +14,104 @@ When an LLM reads a file, every line comes back tagged with a short content hash
 3:0e|}
 ```
 
-When editing, the model references those tags — "replace line `2:f1`", "replace range `1:a3` through `3:0e`", "insert after `3:0e`". If the file changed since the last read, the hashes won't match and the edit is rejected before anything gets corrupted.
+Model references tags when editing — "replace line `2:f1`", "replace range `1:a3` through `3:0e`", "insert after `3:0e`". If file changed since last read, hashes won't match, edit rejected before corruption.
 
-This means the model doesn't need to reproduce old content (or whitespace) to identify what it wants to change. Benchmark results show hashline matches or beats traditional `str_replace` for most models, with the weakest models gaining the most (up to 10x improvement).
+Model doesn't need to reproduce old content/whitespace to identify changes. Benchmarks show hashline matches or beats `str_replace` for most models, weakest models gain most (up to 10x improvement).
 
 ## Requirements
 
-- [Bun](https://bun.sh/) runtime (uses `Bun.hash.xxHash32` for line hashing)
+- [Bun](https://bun.sh/) runtime (`Bun.hash.xxHash32` for line hashing)
+- [ripgrep](https://github.com/BurnSushi/ripgrep) (`rg`) on PATH for `grep` tool
 
 ## Install
 
 ```bash
-cd mcp-hashline-edit-server
-bun install
+npm install mcp-hashline-edit-server
+# or
+bun add mcp-hashline-edit-server
 ```
 
 ## Usage
 
-### With Claude Desktop / Cursor / any MCP client
+### Claude Desktop
 
-Add to your MCP configuration:
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "hashline-edit": {
-      "command": "bun",
-      "args": ["run", "/path/to/mcp-hashline-edit-server/src/index.ts"]
+      "command": "bunx",
+      "args": ["mcp-hashline-edit-server"]
     }
   }
 }
 ```
 
-### Running directly
+### Cursor
+
+Add to `.cursor/mcp.json` (project root or global):
+
+```json
+{
+  "mcpServers": {
+    "hashline-edit": {
+      "command": "bunx",
+      "args": ["mcp-hashline-edit-server"]
+    }
+  }
+}
+```
+
+### Any MCP client
+
+Server runs over stdio:
 
 ```bash
-bun run src/index.ts
+bunx mcp-hashline-edit-server
 ```
 
-The server communicates via stdio using the MCP protocol.
+### From source
+
+```bash
+git clone https://github.com/Submerisble/mcp-hashline-edit-server.git
+cd mcp-hashline-edit-server
+bun install
+bun run src/index.ts
+```
 
 ## Tools
 
 ### `read_file`
 
-Read a file with hashline-prefixed output (`LINE:HASH|content`).
+Read file with hashline-prefixed output (`LINE:HASH|content`).
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `path` | string | File path (relative or absolute) |
-| `offset` | number? | Line number to start from (1-indexed) |
-| `limit` | number? | Max lines to read (default: 2000) |
+| `offset` | number? | Start line (1-indexed) |
+| `limit` | number? | Max lines (default: 2000) |
 
 ### `edit_file`
 
-Edit a file using hash-verified line references. Supports four edit variants:
+Edit file using hash-verified line references. Four edit variants:
 
-**`set_line`** — Replace a single line:
+**`set_line`** — Replace single line:
 ```json
 {"set_line": {"anchor": "2:f1", "new_text": "  return \"universe\";"}}
 ```
 
-**`replace_lines`** — Replace a range:
+**`replace_lines`** — Replace range:
 ```json
 {"replace_lines": {"start_anchor": "1:a3", "end_anchor": "3:0e", "new_text": "function greet() {\n  return \"hi\";\n}"}}
 ```
 
-**`insert_after`** — Insert after a line:
+**`insert_after`** — Insert after line:
 ```json
 {"insert_after": {"anchor": "1:a3", "text": "  // new comment"}}
 ```
 
-**`replace`** — Substring fuzzy replace (fallback, no hashes needed):
+**`replace`** — Fuzzy substring replace (fallback, no hashes needed):
 ```json
 {"replace": {"old_text": "return \"world\"", "new_text": "return \"universe\""}}
 ```
@@ -93,13 +119,13 @@ Edit a file using hash-verified line references. Supports four edit variants:
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `path` | string | File path |
-| `edits` | array | Array of edit operations |
+| `edits` | array | Edit operations |
 
-All edits are validated atomically against the file as last read. Edits are sorted and applied bottom-up automatically.
+Edits validated atomically against file as last read. Sorted, applied bottom-up automatically.
 
 ### `write_file`
 
-Create or overwrite a file.
+Create or overwrite file.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -113,7 +139,7 @@ Search files with hashline-prefixed results.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `pattern` | string | Regex pattern |
-| `path` | string? | File or directory to search |
+| `path` | string? | File or directory |
 | `glob` | string? | Filter by glob (e.g., `*.js`) |
 | `type` | string? | Filter by file type |
 | `i` | boolean? | Case-insensitive |
@@ -121,23 +147,23 @@ Search files with hashline-prefixed results.
 | `post` | number? | Context lines after |
 | `limit` | number? | Max matches (default: 100) |
 
-Requires `rg` (ripgrep) installed on the system.
+Requires `rg` (ripgrep) on system.
 
 ## How the Hash Works
 
 1. Strip trailing `\r`
-2. Remove all whitespace from the line
-3. Compute `xxHash32` on the whitespace-stripped string
-4. Modulo 256, encode as 2-character lowercase hex (`00`-`ff`)
+2. Remove all whitespace
+3. `xxHash32` on whitespace-stripped string
+4. Modulo 256, encode as 2-char lowercase hex (`00`-`ff`)
 
-The hash is whitespace-insensitive — indentation changes alone don't change the hash, making references robust against reformatting.
+Hash whitespace-insensitive — indentation changes don't affect hash, references robust against reformatting.
 
 ## Error Recovery
 
-**Hash mismatch**: The error shows updated `LINE:HASH` refs with `>>>` markers. Copy the new refs and retry.
+**Hash mismatch**: Error shows updated `LINE:HASH` refs with `>>>` markers. Copy new refs, retry.
 
-**No-op error**: The replacement text matches current content. Re-read the file to see current state.
+**No-op error**: Replacement matches current content. Re-read file for current state.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-hashline-edit-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server providing hashline-based file editing tools — line-addressed edits using content hashes for integrity verification",
   "type": "module",
   "main": "src/index.ts",

package/src/descriptions.ts

@@ -10,6 +10,8 @@ Each line is tagged with a content hash: \`LINE:HASH|content\`.
 The LINE:HASH pairs serve as stable, verifiable anchors for the edit_file tool.
 
 Use \`offset\` and \`limit\` for large files (reads up to 2000 lines by default).
+Set \`plain: true\` when reading to understand code structure — returns \`LINE|content\` without hashes.
+Omit or set false when you plan to edit — you'll need the LINE:HASH refs.
 Supports text files only.`;
 
 export const EDIT_FILE_DESCRIPTION = `Edit a file using hash-verified line references.
@@ -24,7 +26,7 @@ and hashes refer to the original state, not after earlier edits in the same arra
 - Copy LINE:HASH refs verbatim from read output — never fabricate or guess hashes
 - new_text/text contains plain replacement lines only — no LINE:HASH prefix, no diff + markers
 - On hash mismatch: use the updated LINE:HASH refs shown by >>> directly
-- If you already edited a file in this turn, re-read before the next edit
+- After a successful edit, the diff output includes LINE:HASH refs for changed/surrounding lines — you can use these directly for follow-up edits without re-reading
 - new_text must differ from the current line content — identical content is rejected
 
 **Edit variants:**
@@ -39,7 +41,10 @@ new_text: "" means delete (for set_line/replace_lines).
 **Recovery:**
 - Hash mismatch (>>> error): copy updated LINE:HASH refs from error and retry
 - No-op error: your replacement matches current content — re-read the file
-- After successful edit, re-read before making another edit to same file`;
+**After a successful edit:**
+The diff output includes LINE:HASH refs for all changed and surrounding lines. You can chain edits
+using these refs without re-reading. Unchanged lines keep their original hashes (hash is content-based,
+not position-based). The edit tool also handles line relocation if numbers shifted.`;
 
 export const WRITE_FILE_DESCRIPTION = `Create or overwrite a file at the specified path.
 

package/src/diff.ts

@@ -2,6 +2,7 @@
  * Diff generation and replace-mode utilities.
  */
 import * as Diff from "diff";
+import { computeLineHash } from "./hashline";
 import { DEFAULT_FUZZY_THRESHOLD, findMatch, type FuzzyMatch } from "./fuzzy";
 import { adjustIndentation, normalizeToLF } from "./normalize";
 
@@ -29,7 +30,8 @@ function countContentLines(content: string): number {
 
 function formatNumberedDiffLine(prefix: "+" | "-" | " ", lineNum: number, width: number, content: string): string {
 	const padded = String(lineNum).padStart(width, " ");
-	return `${prefix}${padded}|${content}`;
+	const hash = computeLineHash(lineNum, content);
+	return `${prefix}${padded}:${hash}|${content}`;
 }
 
 export function generateDiffString(oldContent: string, newContent: string, contextLines = 4): DiffResult {

package/src/hashline.ts

@@ -134,9 +134,15 @@ function restoreOldWrappedLines(oldLines: string[], newLines: string[]): string[
 	return out;
 }
 
+function isSubstantive(line: string): boolean {
+	return line.trim().length > 0;
+}
+
 function stripInsertAnchorEchoAfter(anchorLine: string, dstLines: string[]): string[] {
 	if (dstLines.length <= 1) return dstLines;
-	if (equalsIgnoringWhitespace(dstLines[0], anchorLine)) return dstLines.slice(1);
+	// Don't strip blank lines — two blank lines matching is coincidence, not echo
+	if (!isSubstantive(anchorLine) || !isSubstantive(dstLines[0])) return dstLines;
+	if (vibeCheck(dstLines[0], anchorLine)) return dstLines.slice(1);
 	return dstLines;
 }
 
@@ -145,9 +151,10 @@ function stripRangeBoundaryEcho(fileLines: string[], startLine: number, endLine:
 	if (dstLines.length <= 1 || dstLines.length <= count) return dstLines;
 	let out = dstLines;
 	const beforeIdx = startLine - 2;
-	if (beforeIdx >= 0 && equalsIgnoringWhitespace(out[0], fileLines[beforeIdx])) out = out.slice(1);
+	// Don't strip blank lines — two blank lines matching is coincidence, not echo
+	if (beforeIdx >= 0 && isSubstantive(out[0]) && isSubstantive(fileLines[beforeIdx]) && vibeCheck(out[0], fileLines[beforeIdx])) out = out.slice(1);
 	const afterIdx = endLine;
-	if (afterIdx < fileLines.length && out.length > 0 && equalsIgnoringWhitespace(out[out.length - 1], fileLines[afterIdx])) {
+	if (afterIdx < fileLines.length && out.length > 0 && isSubstantive(out[out.length - 1]) && isSubstantive(fileLines[afterIdx]) && vibeCheck(out[out.length - 1], fileLines[afterIdx])) {
 		out = out.slice(0, -1);
 	}
 	return out;

package/src/server.ts

@@ -40,8 +40,9 @@ export function createServer(): McpServer {
 			path: z.string().describe("Path to the file to read (relative or absolute)"),
 			offset: z.number().optional().describe("Line number to start reading from (1-indexed)"),
 			limit: z.number().optional().describe("Maximum number of lines to read"),
+			plain: z.boolean().optional().describe("If true, return plain numbered lines without hashes (for reading, not editing)"),
 		},
-		async ({ path: filePath, offset, limit }) => {
+		async ({ path: filePath, offset, limit, plain }) => {
 			const absolutePath = resolvePath(filePath);
 
 			try {
@@ -52,7 +53,9 @@ export function createServer(): McpServer {
 				const endLine = Math.min(lines.length, startLine - 1 + maxLines);
 				const selectedLines = lines.slice(startLine - 1, endLine);
 				const selectedContent = selectedLines.join("\n");
-				const formatted = formatHashLines(selectedContent, startLine);
+				const formatted = plain
+					? selectedLines.map((line, i) => `${startLine + i}|${line}`).join("\n")
+					: formatHashLines(selectedContent, startLine);
 
 				const totalLines = lines.length;
 				let header = `File: ${filePath} (${totalLines} lines)`;
@@ -63,7 +66,7 @@ export function createServer(): McpServer {
 					header += ` (${totalLines - endLine} more lines below)`;
 				}
 
-				return { content: [{ type: "text", text: `${header}\n\n${formatted}` }] };
+				return { content: [{ type: "text", text: `${header}\n\n\`\`\`\n${formatted}\n\`\`\`` }] };
 			} catch (err) {
 				try {
 					const stat = await fs.stat(absolutePath);
@@ -72,7 +75,7 @@ export function createServer(): McpServer {
 						const listing = entries
 							.map((e) => `${e.isDirectory() ? "d" : "f"} ${e.name}`)
 							.join("\n");
-						return { content: [{ type: "text", text: `Directory: ${filePath}\n\n${listing}` }] };
+						return { content: [{ type: "text", text: `Directory: ${filePath}\n\n\`\`\`\n${listing}\n\`\`\`` }] };
 					}
 				} catch {
 					// Not a directory either
@@ -186,7 +189,7 @@ export function createServer(): McpServer {
 					resultText += `\n\nWarnings:\n${anchorResult.warnings.join("\n")}`;
 				}
 				if (diffResult.diff) {
-					resultText += `\n\nDiff:\n${diffResult.diff}`;
+					resultText += `\n\nDiff:\n\`\`\`diff\n${diffResult.diff}\n\`\`\``;
 				}
 
 				return { content: [{ type: "text", text: resultText }] };
@@ -238,7 +241,7 @@ export function createServer(): McpServer {
 			limit: z.number().optional().describe("Limit output to first N matches (default: 100)"),
 		},
 		async ({ pattern, path: searchPath, glob: globPattern, type: fileType, i: caseInsensitive, pre, post, limit }) => {
-			const args = ["rg", "--line-number", "--no-heading"];
+			const args = ["rg", "--line-number", "--no-heading", "--with-filename"];
 
 			if (caseInsensitive) args.push("-i");
 			if (pre) args.push("-B", String(pre));
@@ -300,7 +303,7 @@ export function createServer(): McpServer {
 					formatted.push(line);
 				}
 
-				return { content: [{ type: "text", text: formatted.join("\n") }] };
+				return { content: [{ type: "text", text: `\`\`\`\n${formatted.join("\n")}\n\`\`\`` }] };
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
 				return { content: [{ type: "text", text: `grep error: ${message}` }], isError: true };