ashlr-plugin 1.36.4

package/servers/ls-server-handlers.ts

@@ -0,0 +1,166 @@
+/**
+ * ls-server-handlers — side-effect module.
+ *
+ * Importing this file registers the ashlr__ls tool into the shared registry
+ * (_tool-base.ts). Used by both the standalone entry point (ls-server.ts)
+ * and the router (_router.ts via _router-handlers.ts).
+ */
+
+import { registerTool, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { existsSync, readdirSync, statSync } from "fs";
+import { resolve } from "path";
+import { spawnSync } from "child_process";
+import { recordSaving as recordSavingCore } from "./_stats";
+import { clampToCwd } from "./_cwd-clamp";
+
+// ---------------------------------------------------------------------------
+// Types + constants
+// ---------------------------------------------------------------------------
+
+interface LsOptions {
+  path?: string;
+  maxEntries?: number;
+  sizes?: boolean;
+  bypassSummary?: boolean;
+}
+
+interface Entry {
+  name: string;
+  dir: boolean;
+  size: number;
+}
+
+const DEFAULT_MAX = 80;
+
+// ---------------------------------------------------------------------------
+// Core logic (exported for tests)
+// ---------------------------------------------------------------------------
+
+function listDir(rootAbs: string): Entry[] | { error: string } {
+  let names: string[];
+  if (!existsSync(rootAbs)) return { error: `No such path: ${rootAbs}` };
+  try {
+    const st = statSync(rootAbs);
+    if (!st.isDirectory()) return { error: `Not a directory: ${rootAbs}` };
+  } catch (err) {
+    return { error: `Cannot stat ${rootAbs}: ${String(err)}` };
+  }
+
+  const git = spawnSync("git", ["-C", rootAbs, "rev-parse", "--is-inside-work-tree"], {
+    encoding: "utf-8",
+  });
+  if (git.status === 0 && git.stdout.trim() === "true") {
+    const set = new Set<string>();
+    const collectTopLevel = (args: string[]): void => {
+      const result = spawnSync("git", ["-C", rootAbs, ...args], { encoding: "utf-8" });
+      if (result.status !== 0) return;
+      for (const line of result.stdout.split("\n")) {
+        const first = line.split("/")[0];
+        if (first) set.add(first);
+      }
+    };
+    collectTopLevel(["ls-files"]);
+    collectTopLevel(["ls-files", "--others", "--exclude-standard"]);
+    if (set.size > 0) {
+      names = Array.from(set);
+    } else {
+      try { names = readdirSync(rootAbs); } catch (err) {
+        return { error: `readdir failed: ${String(err)}` };
+      }
+    }
+  } else {
+    try { names = readdirSync(rootAbs); } catch (err) {
+      return { error: `readdir failed: ${String(err)}` };
+    }
+  }
+
+  const entries: Entry[] = [];
+  for (const name of names) {
+    if (name === ".DS_Store") continue;
+    try {
+      const st = statSync(resolve(rootAbs, name));
+      entries.push({ name, dir: st.isDirectory(), size: st.size });
+    } catch {
+      // Broken symlink / permission denied — skip.
+    }
+  }
+  entries.sort((a, b) => {
+    if (a.dir !== b.dir) return a.dir ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  return entries;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)}M`;
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(1)}G`;
+}
+
+function renderEntries(entries: Entry[], sizes: boolean, maxEntries: number, elided = 0): string {
+  const shown = entries.slice(0, maxEntries);
+  const lines: string[] = [];
+  for (const e of shown) {
+    const name = e.dir ? `${e.name}/` : e.name;
+    if (sizes && !e.dir) {
+      lines.push(`${formatSize(e.size).padStart(7)}  ${name}`);
+    } else if (sizes) {
+      lines.push(`${"—".padStart(7)}  ${name}`);
+    } else {
+      lines.push(name);
+    }
+  }
+  if (elided > 0) {
+    lines.push(`[… ${elided} entries elided — pass bypassSummary:true to see the full list]`);
+  }
+  return lines.join("\n");
+}
+
+export async function handleLs(args: LsOptions): Promise<string> {
+  const maxEntries = Math.max(1, Math.min(1000, args.maxEntries ?? DEFAULT_MAX));
+  const sizes = args.sizes === true;
+  const bypass = args.bypassSummary === true;
+
+  const clamp = clampToCwd(args.path, "ashlr__ls");
+  if (!clamp.ok) return clamp.message;
+  const rootAbs = clamp.abs;
+
+  const result = listDir(rootAbs);
+  if ("error" in result) return result.error;
+
+  const total = result.length;
+  const max = bypass ? total : maxEntries;
+  const elided = Math.max(0, total - max);
+  const rendered = renderEntries(result, sizes, max, elided);
+
+  const baseline = result.reduce((acc, e) => acc + e.name.length + 12, 0);
+  await recordSavingCore(baseline, rendered.length, "ashlr__ls");
+
+  const header = `${rootAbs}  ·  ${total} entries${elided ? ` (${max} shown)` : ""}`;
+  return `${header}\n${rendered}`;
+}
+
+// ---------------------------------------------------------------------------
+// Registration (side-effect on import)
+// ---------------------------------------------------------------------------
+
+registerTool({
+  name: "ashlr__ls",
+  description:
+    "Gitignore-aware directory listing. Compact columnar output with elision past maxEntries (default 80). Set bypassSummary:true to see all entries.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path:          { type: "string",  description: "Directory to list (absolute or cwd-relative). Default '.'" },
+      maxEntries:    { type: "number",  description: "Cap on entries shown (default 80, max 1000)" },
+      sizes:         { type: "boolean", description: "Include human-readable file sizes" },
+      bypassSummary: { type: "boolean", description: "Return every entry without elision" },
+    },
+    additionalProperties: false,
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    const text = await handleLs(args as unknown as LsOptions);
+    return { content: [{ type: "text", text }] };
+  },
+});

package/servers/ls-server.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+/**
+ * ashlr-ls MCP server — standalone entry point.
+ *
+ * Imports ls-server-handlers (registers ashlr__ls into the shared
+ * registry) then runs as a standalone stdio MCP server. Existing plugin.json
+ * entries continue to work unchanged through the v1.12 migration window.
+ *
+ * For in-process router use, import ls-server-handlers directly.
+ */
+
+import "./ls-server-handlers";
+import { runStandalone } from "./_tool-base";
+
+// Re-export core logic so existing tests that import from this module keep working.
+export { handleLs } from "./ls-server-handlers";
+
+if (import.meta.main) {
+  await runStandalone("ashlr-ls", "0.1.0");
+}

package/servers/multi-edit-server-handlers.ts

@@ -0,0 +1,51 @@
+/**
+ * multi-edit-server-handlers — registers ashlr__multi_edit on the shared registry.
+ */
+
+import { registerTool, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { ashlrMultiEdit, type MultiEditArgs } from "./multi-edit-server";
+
+registerTool({
+  name: "ashlr__multi_edit",
+  description:
+    "Many edits across multiple files in one atomic call. Use instead of N separate " +
+    "Edit or ashlr__edit calls when touching more than one file — N round-trips collapse " +
+    "to 1, with full rollback on any failure. Compresses by returning one consolidated " +
+    "diff summary; typical savings (N−1) × per-call overhead. For a single file use " +
+    "ashlr__edit instead. For symbol renames use ashlr__edit_structural instead.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      edits: {
+        type: "array",
+        description: "Ordered list of edits to apply atomically.",
+        items: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "Absolute or cwd-relative file path. File must exist." },
+            search: { type: "string", description: "Exact string to find in the file." },
+            replace: { type: "string", description: "String to replace it with." },
+            strict: {
+              type: "boolean",
+              description: "Default true: require exactly one match (error if 0 or 2+). Pass false to replace all occurrences.",
+            },
+          },
+          required: ["path", "search", "replace"],
+        },
+      },
+    },
+    required: ["edits"],
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    try {
+      const text = await ashlrMultiEdit((args ?? {}) as unknown as MultiEditArgs);
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // multi-edit returns the raw message (no prefix) so callers see the
+      // underlying tool's diagnostic verbatim — distinct from the tool-prefixed
+      // shape of other handlers.
+      return { content: [{ type: "text", text: message }], isError: true };
+    }
+  },
+});

package/servers/multi-edit-server.ts

@@ -0,0 +1,422 @@
+#!/usr/bin/env bun
+/**
+ * ashlr-multi-edit MCP server.
+ *
+ * Exposes ashlr__multi_edit — atomic batched edits across N files in one
+ * roundtrip. Each edit is like ashlr__edit (path + search + replace + strict),
+ * but all N edits are applied atomically: if any fails, every prior edit is
+ * rolled back using the cached original content. Files are read once per path
+ * and written once per path at the end, after all edits succeed.
+ *
+ * Savings: baseline = sum(original.length + updated.length) across all files,
+ * which is what N naive Edit calls would have shipped. We record savings via
+ * the shared recordSaving from _stats.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFile, rename, unlink, writeFile } from "fs/promises";
+import { basename, dirname, join } from "path";
+import { recordSaving } from "./_stats";
+import { refreshGenomeAfterEdit } from "./_genome-live";
+import { clampToCwd } from "./_cwd-clamp";
+import { findFuzzyMatch } from "./_edit-match";
+import { validateEdit } from "./_edit-validate";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface SingleEdit {
+  path: string;
+  search: string;
+  replace: string;
+  /** Default true: require exactly one match. Pass false to replace all. */
+  strict?: boolean;
+}
+
+export interface MultiEditArgs {
+  edits: SingleEdit[];
+}
+
+// ---------------------------------------------------------------------------
+// Token estimation (same formula as efficiency-server)
+// ---------------------------------------------------------------------------
+
+function estimateTokens(s: string): number {
+  return Math.ceil(s.length / 4);
+}
+
+function firstLine(s: string): string {
+  return (s.split("\n")[0] ?? "").slice(0, 72);
+}
+
+async function removeTemp(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch {
+    // Best effort only. A failed edit should report the original write error,
+    // not a cleanup miss for a temp file that may already be gone.
+  }
+}
+
+async function atomicWriteFile(path: string, content: string): Promise<void> {
+  const tempPath = join(
+    dirname(path),
+    `.${basename(path)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+  );
+
+  try {
+    await writeFile(tempPath, content, "utf-8");
+    await rename(tempPath, path);
+  } catch (err) {
+    await removeTemp(tempPath);
+    throw err;
+  }
+}
+
+async function writeChangedFilesAtomically(
+  changes: Array<{ path: string; original: string; updated: string }>,
+): Promise<void> {
+  const staged: Array<{ path: string; tempPath: string; original: string }> = [];
+  const committed: Array<{ path: string; original: string }> = [];
+
+  try {
+    // Stage every new file image before replacing any original file. If a
+    // later file cannot be written, no earlier original has changed.
+    for (const change of changes) {
+      const tempPath = join(
+        dirname(change.path),
+        `.${basename(change.path)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+      );
+      await writeFile(tempPath, change.updated, "utf-8");
+      staged.push({ path: change.path, tempPath, original: change.original });
+    }
+
+    for (const item of staged) {
+      await rename(item.tempPath, item.path);
+      committed.push({ path: item.path, original: item.original });
+    }
+  } catch (err) {
+    for (const item of staged) {
+      await removeTemp(item.tempPath);
+    }
+
+    const rollbackErrors: string[] = [];
+    for (const item of committed.reverse()) {
+      try {
+        await atomicWriteFile(item.path, item.original);
+      } catch (rollbackErr) {
+        const msg = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+        rollbackErrors.push(`${item.path}: ${msg}`);
+      }
+    }
+
+    const msg = err instanceof Error ? err.message : String(err);
+    const rollbackNote =
+      rollbackErrors.length > 0
+        ? `; rollback failed for ${rollbackErrors.join("; ")}`
+        : "";
+    throw new Error(`ashlr__multi_edit: failed to write changes: ${msg}${rollbackNote}`);
+  }
+}
+
+const FUZZY_SIZE_LIMIT = 2 * 1024 * 1024; // 2 MB
+
+// ---------------------------------------------------------------------------
+// Core logic
+// ---------------------------------------------------------------------------
+
+export async function ashlrMultiEdit(input: MultiEditArgs): Promise<string> {
+  const { edits } = input;
+  if (!Array.isArray(edits) || edits.length === 0) {
+    throw new Error("ashlr__multi_edit: 'edits' must be a non-empty array");
+  }
+
+  // Validate fields + clamp each path to cwd before any FS I/O. Fail-fast so
+  // we never partially apply a batch on an out-of-cwd path.
+  const clampedPaths: string[] = [];
+  for (let i = 0; i < edits.length; i++) {
+    const e = edits[i]!;
+    if (!e.path) throw new Error(`ashlr__multi_edit: edit[${i}] missing 'path'`);
+    if (!e.search) throw new Error(`ashlr__multi_edit: edit[${i}] missing 'search'`);
+    const clamp = clampToCwd(e.path, "ashlr__multi_edit");
+    if (!clamp.ok) throw new Error(clamp.message);
+    clampedPaths.push(clamp.abs);
+  }
+
+  // --- Phase 1: read each file once, coalescing by resolved path ---
+  const pathToOriginal = new Map<string, string>();
+  for (let i = 0; i < edits.length; i++) {
+    const e = edits[i]!;
+    const abs = clampedPaths[i]!;
+    if (pathToOriginal.has(abs)) continue;
+    let content: string;
+    try {
+      content = await readFile(abs, "utf-8");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`ashlr__multi_edit: cannot read ${e.path}: ${msg}`);
+    }
+    pathToOriginal.set(abs, content);
+  }
+
+  // --- Phase 2: apply edits in-memory, atomically ---
+  // Working copies — rolled back on any failure.
+  const working = new Map<string, string>(pathToOriginal);
+
+  // Per-path edit list for the summary (path → list of hunk summaries).
+  const perPathHunks = new Map<string, Array<{ search: string; replace: string; count: number; strict: boolean; fuzzy?: boolean }>>();
+
+  // Track per-path fuzzy notes for the summary.
+  const fuzzyNotes: string[] = [];
+
+  for (let i = 0; i < edits.length; i++) {
+    const e = edits[i]!;
+    const abs = clampedPaths[i]!;
+    const strict = e.strict !== false; // default true
+    const current = working.get(abs)!;
+
+    // Count occurrences.
+    let count = 0;
+    let idx = 0;
+    while ((idx = current.indexOf(e.search, idx)) !== -1) {
+      count++;
+      idx += e.search.length;
+    }
+
+    if (count === 0) {
+      // Try fuzzy fallback when in strict mode, file <= 2MB, fuzzy not disabled.
+      const fuzzyEnabled =
+        strict &&
+        current.length <= FUZZY_SIZE_LIMIT &&
+        process.env.ASHLR_EDIT_FUZZY !== "off";
+
+      if (fuzzyEnabled) {
+        const fuzzyMatch = findFuzzyMatch(current, e.search);
+        if (fuzzyMatch !== null) {
+          const updated =
+            current.slice(0, fuzzyMatch.start) +
+            e.replace +
+            current.slice(fuzzyMatch.end);
+          working.set(abs, updated);
+
+          const hunks = perPathHunks.get(abs) ?? [];
+          hunks.push({ search: e.search, replace: e.replace, count: 1, strict, fuzzy: true });
+          perPathHunks.set(abs, hunks);
+          fuzzyNotes.push(`edit[${i}] applied via fuzzy match (sim=${fuzzyMatch.score.toFixed(2)})`);
+          continue;
+        }
+      }
+
+      // Rollback: working map is already in-memory only, nothing written yet.
+      throw new Error(
+        `ashlr__multi_edit: edit[${i}] search string not found in ${e.path}`,
+      );
+    }
+    if (strict && count > 1) {
+      throw new Error(
+        `ashlr__multi_edit: edit[${i}] search matched ${count} times in ${e.path}; pass strict:false to replace all, or widen context to a unique span`,
+      );
+    }
+
+    // Use slice/concat (strict) or split/join (non-strict) to treat `e.replace`
+    // as a literal string. String.prototype.replace(string, string) would
+    // interpret `$&`, `$1`, `$'`, `$` in the replacement — silently
+    // corrupting any edit whose replacement contains a `$` followed by a
+    // digit, ampersand, backtick, or apostrophe.
+    let updated: string;
+    if (strict) {
+      const idx = current.indexOf(e.search);
+      updated = current.slice(0, idx) + e.replace + current.slice(idx + e.search.length);
+    } else {
+      updated = current.split(e.search).join(e.replace);
+    }
+
+    working.set(abs, updated);
+
+    const hunks = perPathHunks.get(abs) ?? [];
+    hunks.push({ search: e.search, replace: e.replace, count, strict });
+    perPathHunks.set(abs, hunks);
+  }
+
+  // --- Phase 2.5: validate each changed file before writing (Feature 3) ---
+  const validationWarnings: string[] = [];
+
+  for (const [abs, updatedContent] of working) {
+    const original = pathToOriginal.get(abs)!;
+    if (updatedContent === original) continue; // unchanged
+
+    const validation = await validateEdit(abs, original, updatedContent).catch(() => ({
+      introducedError: false,
+      detail: "",
+    }));
+
+    if (!validation.introducedError) continue;
+
+    if (process.env.ASHLR_EDIT_VALIDATE === "block") {
+      // Atomic block: throw before ANY file is written. Nothing is persisted.
+      let displayPath = abs;
+      try {
+        const rel = abs.startsWith(process.cwd()) ? abs.slice(process.cwd().length + 1) : abs;
+        displayPath = rel || abs;
+      } catch { /* use abs */ }
+      throw new Error(
+        `ashlr__multi_edit: refused — edit introduces a syntax error in ${displayPath} ` +
+          `(${validation.detail}); set ASHLR_EDIT_VALIDATE=warn to override`,
+      );
+    }
+
+    // Warn mode: collect for summary but still write.
+    let displayPath = abs;
+    try {
+      const rel = abs.startsWith(process.cwd()) ? abs.slice(process.cwd().length + 1) : abs;
+      displayPath = rel || abs;
+    } catch { /* use abs */ }
+    validationWarnings.push(`${displayPath}: ⚠ syntax — ${validation.detail}`);
+  }
+
+  // --- Phase 3: write each file once ---
+  const changedFiles: Array<{ path: string; original: string; updated: string }> = [];
+  for (const [abs, content] of working) {
+    // Only write files that changed.
+    const original = pathToOriginal.get(abs)!;
+    if (content !== original) {
+      changedFiles.push({ path: abs, original, updated: content });
+    }
+  }
+
+  await writeChangedFilesAtomically(changedFiles);
+
+  for (const file of changedFiles) {
+    // best-effort: refreshGenomeAfterEdit already swallows internally and never rejects; this outer catch is belt-and-braces against a pre-try sync throw (e.g. import init failure) so edits never fail because of observability.
+    refreshGenomeAfterEdit(file.path, file.original, file.updated).catch(() => {});
+  }
+
+  // --- Phase 4: build summary and record savings ---
+  // v1.22 Trust Pass: baseline is what N naive Edits would have SHIPPED — the
+  // sum of each hunk's (search + replace) bytes, NOT the full file contents
+  // twice. Aligns multi_edit accounting with the v1.18 single-edit fix
+  // (edit-server.ts uses `search.length + replace.length`). Previously this
+  // counted full file before+after for each touched file, which inflated the
+  // recorded savings 5-10× on small-hunk-into-large-file mass refactors.
+  let baseline = 0;
+  for (const [, hunks] of perPathHunks) {
+    for (const h of hunks) {
+      baseline += h.search.length + h.replace.length;
+    }
+  }
+
+  const fileCount = perPathHunks.size;
+  const totalEdits = edits.length;
+
+  const lines: string[] = [
+    `[ashlr__multi_edit] applied ${totalEdits} edit${totalEdits === 1 ? "" : "s"} across ${fileCount} file${fileCount === 1 ? "" : "s"}:`,
+  ];
+
+  for (const [abs, hunks] of perPathHunks) {
+    // Find a display path: relative to cwd if possible.
+    let displayPath = abs;
+    try {
+      const rel = abs.startsWith(process.cwd()) ? abs.slice(process.cwd().length + 1) : abs;
+      displayPath = rel || abs;
+    } catch { /* use abs */ }
+
+    lines.push(`  ${displayPath} (${hunks.length} edit${hunks.length === 1 ? "" : "s"})`);
+    for (const h of hunks) {
+      lines.push(`    - removed (${estimateTokens(h.search)} tok): ${firstLine(h.search)}${h.search.length > 72 ? "…" : ""}`);
+      lines.push(`    + added   (${estimateTokens(h.replace)} tok): ${firstLine(h.replace)}${h.replace.length > 72 ? "…" : ""}`);
+    }
+  }
+
+  const rawKB = Math.round(baseline / 1024);
+  const summaryLength = lines.join("\n").length;
+  const compactKB = Math.max(1, Math.round(summaryLength / 1024));
+  const savedTok = Math.max(0, Math.ceil((baseline - summaryLength) / 4));
+
+  lines.push(
+    `· total: ${totalEdits} hunk${totalEdits === 1 ? "" : "s"} · raw would have been ${rawKB} KB · compressed to ${compactKB} KB · saved ~${savedTok.toLocaleString()} tok`,
+  );
+
+  // Append fuzzy match notes.
+  for (const note of fuzzyNotes) {
+    lines.push(`[ashlr__multi_edit: ${note}]`);
+  }
+
+  // Append validation warnings.
+  for (const warn of validationWarnings) {
+    lines.push(`[ashlr__multi_edit: ⚠ syntax — ${warn}; review or fix in your next edit]`);
+  }
+
+  const summary = lines.join("\n");
+  await recordSaving(baseline, summary.length, "ashlr__multi_edit");
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+// MCP wiring
+// ---------------------------------------------------------------------------
+
+const server = new Server(
+  { name: "ashlr-multi-edit", version: "0.1.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "ashlr__multi_edit",
+      description:
+        "Atomic refactors across files — apply N edits in ONE roundtrip instead of N. " +
+        "Either ALL edits succeed or NONE are written (full rollback on any failure). " +
+        "Reads each target file once and writes it once regardless of how many edits target it. " +
+        "Use this instead of calling ashlr__edit N times for multi-file refactors; saves (N−1) × tool-call overhead and returns one consolidated diff summary.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          edits: {
+            type: "array",
+            description: "Ordered list of edits to apply atomically.",
+            items: {
+              type: "object",
+              properties: {
+                path: { type: "string", description: "Absolute or cwd-relative file path. File must exist." },
+                search: { type: "string", description: "Exact string to find in the file." },
+                replace: { type: "string", description: "String to replace it with." },
+                strict: {
+                  type: "boolean",
+                  description: "Default true: require exactly one match (error if 0 or 2+). Pass false to replace all occurrences.",
+                },
+              },
+              required: ["path", "search", "replace"],
+            },
+          },
+        },
+        required: ["edits"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+  try {
+    if (name === "ashlr__multi_edit") {
+      const text = await ashlrMultiEdit((args ?? {}) as unknown as MultiEditArgs);
+      return { content: [{ type: "text", text }] };
+    }
+    return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: message }], isError: true };
+  }
+});
+
+if (import.meta.main) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/servers/notebook-edit-server-handlers.ts

@@ -0,0 +1,34 @@
+/**
+ * notebook-edit-server-handlers — registers ashlr__notebook_edit into the shared tool registry.
+ */
+
+import { registerTool, type ToolCallContext, type ToolResult } from "./_tool-base";
+import { ashlrNotebookEdit, formatNotebookEditResult, type NotebookEditArgs } from "./notebook-edit-server";
+
+registerTool({
+  name: "ashlr__notebook_edit",
+  description:
+    "Edit a single cell in a Jupyter notebook (.ipynb). Use instead of native NotebookEdit " +
+    "when the notebook is >5KB or has many unrelated cells — only the edited cell and its " +
+    "immediate neighbors are returned, with `[N cells unchanged]` for the rest. The full " +
+    "notebook is never echoed. Typical savings: 65-75% on multi-cell notebooks. " +
+    "Args: notebookPath, cellIndex, newSource, cellType (optional: code|markdown).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      notebookPath: { type: "string", description: "Absolute or cwd-relative path to the .ipynb notebook" },
+      cellIndex: { type: "number", description: "Zero-based index of the cell to edit" },
+      newSource: { type: "string", description: "New source content for the cell" },
+      cellType: {
+        type: "string",
+        enum: ["code", "markdown"],
+        description: "Optional: change the cell type (code or markdown)",
+      },
+    },
+    required: ["notebookPath", "cellIndex", "newSource"],
+  },
+  handler: async (args: Record<string, unknown>, _ctx: ToolCallContext): Promise<ToolResult> => {
+    const result = await ashlrNotebookEdit(args as unknown as NotebookEditArgs);
+    return { content: [{ type: "text", text: formatNotebookEditResult(result) }] };
+  },
+});