mcp-hashline-edit-server 0.1.0

package/src/normalize.ts

@@ -0,0 +1,278 @@
+/**
+ * Text normalization utilities.
+ *
+ * Handles line endings, BOM, whitespace, and Unicode normalization.
+ */
+
+// Line Endings
+
+export type LineEnding = "\r\n" | "\n";
+
+export function detectLineEnding(content: string): LineEnding {
+	const crlfIdx = content.indexOf("\r\n");
+	const lfIdx = content.indexOf("\n");
+	if (lfIdx === -1) return "\n";
+	if (crlfIdx === -1) return "\n";
+	return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+
+export function normalizeToLF(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+export function restoreLineEndings(text: string, ending: LineEnding): string {
+	return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+// BOM Handling
+
+export interface BomResult {
+	bom: string;
+	text: string;
+}
+
+export function stripBom(content: string): BomResult {
+	return content.startsWith("\uFEFF") ? { bom: "\uFEFF", text: content.slice(1) } : { bom: "", text: content };
+}
+
+// Whitespace Utilities
+
+export function countLeadingWhitespace(line: string): number {
+	let count = 0;
+	for (let i = 0; i < line.length; i++) {
+		const char = line[i];
+		if (char === " " || char === "\t") {
+			count++;
+		} else {
+			break;
+		}
+	}
+	return count;
+}
+
+export function getLeadingWhitespace(line: string): string {
+	return line.slice(0, countLeadingWhitespace(line));
+}
+
+export function detectIndentChar(text: string): string {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		const ws = getLeadingWhitespace(line);
+		if (ws.length > 0) {
+			return ws[0];
+		}
+	}
+	return " ";
+}
+
+// Unicode Normalization
+
+export function normalizeUnicode(s: string): string {
+	return s
+		.trim()
+		.split("")
+		.map((c) => {
+			const code = c.charCodeAt(0);
+			if (
+				code === 0x2010 ||
+				code === 0x2011 ||
+				code === 0x2012 ||
+				code === 0x2013 ||
+				code === 0x2014 ||
+				code === 0x2015 ||
+				code === 0x2212
+			) {
+				return "-";
+			}
+			if (code === 0x2018 || code === 0x2019 || code === 0x201a || code === 0x201b) {
+				return "'";
+			}
+			if (code === 0x201c || code === 0x201d || code === 0x201e || code === 0x201f) {
+				return '"';
+			}
+			if (
+				code === 0x00a0 ||
+				code === 0x2002 ||
+				code === 0x2003 ||
+				code === 0x2004 ||
+				code === 0x2005 ||
+				code === 0x2006 ||
+				code === 0x2007 ||
+				code === 0x2008 ||
+				code === 0x2009 ||
+				code === 0x200a ||
+				code === 0x202f ||
+				code === 0x205f ||
+				code === 0x3000
+			) {
+				return " ";
+			}
+			return c;
+		})
+		.join("");
+}
+
+export function normalizeForFuzzy(line: string): string {
+	const trimmed = line.trim();
+	if (trimmed.length === 0) return "";
+	return trimmed
+		.replace(/[""„‟«»]/g, '"')
+		.replace(/[''‚‛`´]/g, "'")
+		.replace(/[‐‑‒–—−]/g, "-")
+		.replace(/[ \t]+/g, " ");
+}
+
+// Indentation Adjustment
+
+function gcd(a: number, b: number): number {
+	let x = Math.abs(a);
+	let y = Math.abs(b);
+	while (y !== 0) {
+		const temp = y;
+		y = x % y;
+		x = temp;
+	}
+	return x;
+}
+
+interface IndentProfile {
+	lines: string[];
+	indentCounts: number[];
+	min: number;
+	char: " " | "\t" | undefined;
+	spaceOnly: boolean;
+	tabOnly: boolean;
+	mixed: boolean;
+	unit: number;
+	nonEmptyCount: number;
+}
+
+function buildIndentProfile(text: string): IndentProfile {
+	const lines = text.split("\n");
+	const indentCounts: number[] = [];
+	let min = Infinity;
+	let char: " " | "\t" | undefined;
+	let spaceOnly = true;
+	let tabOnly = true;
+	let mixed = false;
+	let nonEmptyCount = 0;
+	let unit = 0;
+
+	for (const line of lines) {
+		if (line.trim().length === 0) continue;
+		nonEmptyCount++;
+		const indent = getLeadingWhitespace(line);
+		indentCounts.push(indent.length);
+		min = Math.min(min, indent.length);
+		if (indent.includes(" ")) tabOnly = false;
+		if (indent.includes("\t")) spaceOnly = false;
+		if (indent.includes(" ") && indent.includes("\t")) mixed = true;
+		if (indent.length > 0) {
+			const currentChar = indent[0] as " " | "\t";
+			if (!char) {
+				char = currentChar;
+			} else if (char !== currentChar) {
+				mixed = true;
+			}
+		}
+	}
+	if (min === Infinity) min = 0;
+	if (spaceOnly && nonEmptyCount > 0) {
+		let current = 0;
+		for (const count of indentCounts) {
+			if (count === 0) continue;
+			current = current === 0 ? count : gcd(current, count);
+		}
+		unit = current;
+	}
+	if (tabOnly && nonEmptyCount > 0) unit = 1;
+
+	return { lines, indentCounts, min, char, spaceOnly, tabOnly, mixed, unit, nonEmptyCount };
+}
+
+function convertLeadingTabsToSpaces(text: string, spacesPerTab: number): string {
+	if (spacesPerTab <= 0) return text;
+	return text
+		.split("\n")
+		.map((line) => {
+			const trimmed = line.trimStart();
+			if (trimmed.length === 0) return line;
+			const leading = getLeadingWhitespace(line);
+			if (!leading.includes("\t") || leading.includes(" ")) return line;
+			const converted = " ".repeat(leading.length * spacesPerTab);
+			return converted + trimmed;
+		})
+		.join("\n");
+}
+
+export function adjustIndentation(oldText: string, actualText: string, newText: string): string {
+	if (oldText === actualText) return newText;
+
+	const oldLines = oldText.split("\n");
+	const newLines = newText.split("\n");
+	if (oldLines.length === newLines.length) {
+		let indentationOnly = true;
+		for (let i = 0; i < oldLines.length; i++) {
+			if (oldLines[i].trim() !== newLines[i].trim()) {
+				indentationOnly = false;
+				break;
+			}
+		}
+		if (indentationOnly) return newText;
+	}
+
+	const oldProfile = buildIndentProfile(oldText);
+	const actualProfile = buildIndentProfile(actualText);
+	const newProfile = buildIndentProfile(newText);
+
+	if (newProfile.nonEmptyCount === 0 || oldProfile.nonEmptyCount === 0 || actualProfile.nonEmptyCount === 0) {
+		return newText;
+	}
+	if (oldProfile.mixed || actualProfile.mixed || newProfile.mixed) return newText;
+
+	if (oldProfile.char && actualProfile.char && oldProfile.char !== actualProfile.char) {
+		if (actualProfile.spaceOnly && oldProfile.tabOnly && newProfile.tabOnly && actualProfile.unit > 0) {
+			let consistent = true;
+			const lineCount = Math.min(oldProfile.lines.length, actualProfile.lines.length);
+			for (let i = 0; i < lineCount; i++) {
+				const oldLine = oldProfile.lines[i];
+				const actualLine = actualProfile.lines[i];
+				if (oldLine.trim().length === 0 || actualLine.trim().length === 0) continue;
+				const oldIndent = getLeadingWhitespace(oldLine);
+				const actualIndent = getLeadingWhitespace(actualLine);
+				if (oldIndent.length === 0) continue;
+				if (actualIndent.length !== oldIndent.length * actualProfile.unit) {
+					consistent = false;
+					break;
+				}
+			}
+			return consistent ? convertLeadingTabsToSpaces(newText, actualProfile.unit) : newText;
+		}
+		return newText;
+	}
+
+	const lineCount = Math.min(oldProfile.lines.length, actualProfile.lines.length);
+	const deltas: number[] = [];
+	for (let i = 0; i < lineCount; i++) {
+		const oldLine = oldProfile.lines[i];
+		const actualLine = actualProfile.lines[i];
+		if (oldLine.trim().length === 0 || actualLine.trim().length === 0) continue;
+		deltas.push(countLeadingWhitespace(actualLine) - countLeadingWhitespace(oldLine));
+	}
+	if (deltas.length === 0) return newText;
+
+	const delta = deltas[0];
+	if (!deltas.every((value) => value === delta)) return newText;
+	if (delta === 0) return newText;
+
+	if (newProfile.char && actualProfile.char && newProfile.char !== actualProfile.char) return newText;
+
+	const indentChar = actualProfile.char ?? oldProfile.char ?? detectIndentChar(actualText);
+	const adjusted = newText.split("\n").map((line) => {
+		if (line.trim().length === 0) return line;
+		if (delta > 0) return indentChar.repeat(delta) + line;
+		const toRemove = Math.min(-delta, countLeadingWhitespace(line));
+		return line.slice(toRemove);
+	});
+	return adjusted.join("\n");
+}

package/src/server.ts

@@ -0,0 +1,312 @@
+/**
+ * MCP server factory — builds and returns the McpServer with all tools registered.
+ *
+ * Tools:
+ *   read_file  — Read files with hashline-prefixed output (LINE:HASH|content)
+ *   edit_file  — Edit files using hash-verified line references
+ *   write_file — Create or overwrite files
+ *   grep       — Search files with hashline-prefixed results
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { computeLineHash, formatHashLines, applyHashlineEdits, parseLineRef, HashlineMismatchError } from "./hashline";
+import { replaceText, generateDiffString } from "./diff";
+import { normalizeToLF, detectLineEnding, restoreLineEndings, stripBom } from "./normalize";
+import { DEFAULT_FUZZY_THRESHOLD } from "./fuzzy";
+import { READ_FILE_DESCRIPTION, EDIT_FILE_DESCRIPTION, WRITE_FILE_DESCRIPTION, GREP_DESCRIPTION } from "./descriptions";
+import type { HashlineEdit } from "./types";
+
+const DEFAULT_MAX_LINES = 2000;
+
+function resolvePath(filePath: string): string {
+	if (path.isAbsolute(filePath)) return filePath;
+	return path.resolve(process.cwd(), filePath);
+}
+
+export function createServer(): McpServer {
+	const server = new McpServer({
+		name: "hashline-edit-server",
+		version: "0.1.0",
+	});
+
+	// read_file tool
+
+	server.tool(
+		"read_file",
+		READ_FILE_DESCRIPTION,
+		{
+			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"),
+		},
+		async ({ path: filePath, offset, limit }) => {
+			const absolutePath = resolvePath(filePath);
+
+			try {
+				const content = await Bun.file(absolutePath).text();
+				const lines = content.split("\n");
+				const startLine = Math.max(1, offset ?? 1);
+				const maxLines = limit ?? DEFAULT_MAX_LINES;
+				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 totalLines = lines.length;
+				let header = `File: ${filePath} (${totalLines} lines)`;
+				if (startLine > 1 || endLine < totalLines) {
+					header += ` [showing lines ${startLine}-${endLine}]`;
+				}
+				if (endLine < totalLines) {
+					header += ` (${totalLines - endLine} more lines below)`;
+				}
+
+				return { content: [{ type: "text", text: `${header}\n\n${formatted}` }] };
+			} catch (err) {
+				try {
+					const stat = await fs.stat(absolutePath);
+					if (stat.isDirectory()) {
+						const entries = await fs.readdir(absolutePath, { withFileTypes: true });
+						const listing = entries
+							.map((e) => `${e.isDirectory() ? "d" : "f"} ${e.name}`)
+							.join("\n");
+						return { content: [{ type: "text", text: `Directory: ${filePath}\n\n${listing}` }] };
+					}
+				} catch {
+					// Not a directory either
+				}
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `Error reading ${filePath}: ${message}` }], isError: true };
+			}
+		},
+	);
+
+	// edit_file tool
+
+	const editItemSchema = z.union([
+		z.object({
+			set_line: z.object({
+				anchor: z.string().describe('Line reference "LINE:HASH"'),
+				new_text: z.string().describe('Replacement content (\\n-separated) — "" for delete'),
+			}),
+		}),
+		z.object({
+			replace_lines: z.object({
+				start_anchor: z.string().describe('Start line ref "LINE:HASH"'),
+				end_anchor: z.string().describe('End line ref "LINE:HASH"'),
+				new_text: z.string().describe('Replacement content (\\n-separated) — "" for delete'),
+			}),
+		}),
+		z.object({
+			insert_after: z.object({
+				anchor: z.string().describe('Insert after this line "LINE:HASH"'),
+				text: z.string().describe("Content to insert (\\n-separated); must be non-empty"),
+			}),
+		}),
+		z.object({
+			replace: z.object({
+				old_text: z.string().describe("Text to find (fuzzy whitespace matching enabled)"),
+				new_text: z.string().describe("Replacement text"),
+				all: z.boolean().optional().describe("Replace all occurrences (default: unique match required)"),
+			}),
+		}),
+	]);
+
+	server.tool(
+		"edit_file",
+		EDIT_FILE_DESCRIPTION,
+		{
+			path: z.string().describe("File path (relative or absolute)"),
+			edits: z.array(editItemSchema).describe("Array of edit operations"),
+		},
+		async ({ path: filePath, edits }) => {
+			const absolutePath = resolvePath(filePath);
+
+			try {
+				const rawContent = await Bun.file(absolutePath).text();
+				const { bom, text: content } = stripBom(rawContent);
+				const originalEnding = detectLineEnding(content);
+				const originalNormalized = normalizeToLF(content);
+				let normalizedContent = originalNormalized;
+
+				// Validate edit shapes
+				for (let i = 0; i < edits.length; i++) {
+					const edit = edits[i] as Record<string, unknown>;
+					if (("old_text" in edit || "new_text" in edit) && !("replace" in edit)) {
+						throw new Error(
+							`edits[${i}] contains 'old_text'/'new_text' at top level. Use {replace: {old_text, new_text}} or {set_line}, {replace_lines}, {insert_after}.`,
+						);
+					}
+					if (!("set_line" in edit) && !("replace_lines" in edit) && !("insert_after" in edit) && !("replace" in edit)) {
+						throw new Error(
+							`edits[${i}] must contain one of: 'set_line', 'replace_lines', 'insert_after', or 'replace'. Got keys: [${Object.keys(edit).join(", ")}].`,
+						);
+					}
+				}
+
+				const anchorEdits = edits.filter(
+					(e): e is HashlineEdit => "set_line" in e || "replace_lines" in e || "insert_after" in e,
+				);
+				const replaceEdits = edits.filter(
+					(e): e is { replace: { old_text: string; new_text: string; all?: boolean } } => "replace" in e,
+				);
+
+				const anchorResult = applyHashlineEdits(normalizedContent, anchorEdits);
+				normalizedContent = anchorResult.content;
+
+				for (const r of replaceEdits) {
+					if (r.replace.old_text.length === 0) throw new Error("replace.old_text must not be empty.");
+					const rep = replaceText(normalizedContent, r.replace.old_text, r.replace.new_text, {
+						fuzzy: true,
+						all: r.replace.all ?? false,
+						threshold: DEFAULT_FUZZY_THRESHOLD,
+					});
+					normalizedContent = rep.content;
+				}
+
+				if (originalNormalized === normalizedContent) {
+					let diagnostic = `No changes made to ${filePath}. The edits produced identical content.`;
+					if (anchorResult.noopEdits && anchorResult.noopEdits.length > 0) {
+						const details = anchorResult.noopEdits
+							.map((e) => `Edit ${e.editIndex}: replacement for ${e.loc} is identical to current content:\n  ${e.loc}| ${e.currentContent}`)
+							.join("\n");
+						diagnostic += `\n${details}\nYour content must differ from what the file already contains. Re-read the file to see the current state.`;
+					}
+					throw new Error(diagnostic);
+				}
+
+				const finalContent = bom + restoreLineEndings(normalizedContent, originalEnding);
+				await Bun.write(absolutePath, finalContent);
+				const diffResult = generateDiffString(originalNormalized, normalizedContent);
+
+				let resultText = `Updated ${filePath}`;
+				if (anchorResult.warnings?.length) {
+					resultText += `\n\nWarnings:\n${anchorResult.warnings.join("\n")}`;
+				}
+				if (diffResult.diff) {
+					resultText += `\n\nDiff:\n${diffResult.diff}`;
+				}
+
+				return { content: [{ type: "text", text: resultText }] };
+			} catch (err) {
+				if (err instanceof HashlineMismatchError) {
+					return { content: [{ type: "text", text: err.message }], isError: true };
+				}
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `Error editing ${filePath}: ${message}` }], isError: true };
+			}
+		},
+	);
+
+	// write_file tool
+
+	server.tool(
+		"write_file",
+		WRITE_FILE_DESCRIPTION,
+		{
+			path: z.string().describe("Path to the file to write (relative or absolute)"),
+			content: z.string().describe("Content to write to the file"),
+		},
+		async ({ path: filePath, content }) => {
+			const absolutePath = resolvePath(filePath);
+			try {
+				await Bun.write(absolutePath, content);
+				const lineCount = content.split("\n").length;
+				return { content: [{ type: "text", text: `Created ${filePath} (${lineCount} lines)` }] };
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `Error writing ${filePath}: ${message}` }], isError: true };
+			}
+		},
+	);
+
+	// grep tool
+
+	server.tool(
+		"grep",
+		GREP_DESCRIPTION,
+		{
+			pattern: z.string().describe("Regex pattern to search for"),
+			path: z.string().optional().describe("File or directory to search (default: cwd)"),
+			glob: z.string().optional().describe("Filter files by glob pattern (e.g., '*.js')"),
+			type: z.string().optional().describe("Filter by file type (e.g., js, py, rust)"),
+			i: z.boolean().optional().describe("Case-insensitive search (default: false)"),
+			pre: z.number().optional().describe("Lines of context before matches"),
+			post: z.number().optional().describe("Lines of context after matches"),
+			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"];
+
+			if (caseInsensitive) args.push("-i");
+			if (pre) args.push("-B", String(pre));
+			if (post) args.push("-A", String(post));
+			if (globPattern) args.push("--glob", globPattern);
+			if (fileType) args.push("--type", fileType);
+
+			const maxMatches = limit ?? 100;
+			args.push("-m", String(maxMatches));
+			args.push("--", pattern);
+
+			const target = searchPath ? resolvePath(searchPath) : process.cwd();
+			args.push(target);
+
+			try {
+				const proc = Bun.spawn(args, {
+					stdout: "pipe",
+					stderr: "pipe",
+					cwd: process.cwd(),
+				});
+
+				const stdout = await new Response(proc.stdout).text();
+				const stderr = await new Response(proc.stderr).text();
+				const exitCode = await proc.exited;
+
+				if (exitCode === 1) {
+					return { content: [{ type: "text", text: "No matches found." }] };
+				}
+				if (exitCode !== 0 && exitCode !== 1) {
+					return { content: [{ type: "text", text: `grep error: ${stderr || "unknown error"}` }], isError: true };
+				}
+
+				const lines = stdout.trimEnd().split("\n");
+				const formatted: string[] = [];
+				const RG_LINE_RE = /^(.+?):(\d+):(.*)/;
+				const RG_CONTEXT_RE = /^(.+?)-(\d+)-(.*)/;
+
+				for (const line of lines) {
+					if (line === "--") {
+						formatted.push("--");
+						continue;
+					}
+					const matchLine = RG_LINE_RE.exec(line);
+					if (matchLine) {
+						const [, file, lineNumStr, content] = matchLine;
+						const lineNum = parseInt(lineNumStr, 10);
+						const hash = computeLineHash(lineNum, content);
+						formatted.push(`${file}:>>${lineNum}:${hash}|${content}`);
+						continue;
+					}
+					const contextLine = RG_CONTEXT_RE.exec(line);
+					if (contextLine) {
+						const [, file, lineNumStr, content] = contextLine;
+						const lineNum = parseInt(lineNumStr, 10);
+						const hash = computeLineHash(lineNum, content);
+						formatted.push(`${file}:  ${lineNum}:${hash}|${content}`);
+						continue;
+					}
+					formatted.push(line);
+				}
+
+				return { content: [{ type: "text", text: formatted.join("\n") }] };
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `grep error: ${message}` }], isError: true };
+			}
+		},
+	);
+
+	return server;
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared types for the hashline edit server.
+ */
+
+export interface HashMismatch {
+	line: number;
+	expected: string;
+	actual: string;
+}
+
+// Hashline edit operation types
+
+export interface SetLineEdit {
+	set_line: {
+		anchor: string;
+		new_text: string;
+	};
+}
+
+export interface ReplaceLinesEdit {
+	replace_lines: {
+		start_anchor: string;
+		end_anchor: string;
+		new_text: string;
+	};
+}
+
+export interface InsertAfterEdit {
+	insert_after: {
+		anchor: string;
+		text: string;
+	};
+}
+
+export interface ReplaceEdit {
+	replace: {
+		old_text: string;
+		new_text: string;
+		all?: boolean;
+	};
+}
+
+export type HashlineEdit = SetLineEdit | ReplaceLinesEdit | InsertAfterEdit | ReplaceEdit;