wiki-viewer 1.6.0 → 1.7.1

package/.next/standalone/docs/agent-fs-plan.md

@@ -51,7 +51,9 @@ All routes reuse `checkAuth` + `enforceScope` + `withFileMutex` + `safeRootPath`
 | `POST`   | `/api/agent/fs/move`                            | `{from, to, ifMatch?}`. Moves sidecar for `.md`.                             |
 | `POST`   | `/api/agent/fs/search`                          | `{kind:"grep"\|"glob", query, path?, glob?, limit?}`. Server-side.           |
 
-**No PATCH. No exec. No batch. No separate grep/glob.** Add later only if profiling proves need.
+**No exec. No batch. No separate grep/glob.** Add later only if profiling proves need.
+
+> **Update (shipped):** A server-side `PATCH /api/agent/fs/file/<path>` str-replace endpoint was added after profiling proved the whole-file-PUT payload dominates latency for large docs on slow uplinks (500KB @ 0.5Mbps ≈ 7.8s/edit transfer). It is strict: exact substring (no regex), text/UTF-8 only, `If-Match` required, `expectedOccurrences` must match exactly (default 1, else 422 `MATCH_COUNT_MISMATCH`). It shares one mutation code path (`applyMutation`) with PUT, so lock / R6 `COLLAB_ACTIVE` / reconcile / audit behave identically. The MCP `edit_file` tool uses PATCH first and falls back to read+PUT on older servers.
 
 ### 2.1 Read (`GET .../file/<path>`)
 

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-viewer",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
     "better-auth": "^1.6.12",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
+    "jszip": "^3.10.1",
     "kysely": "0.28.5",
     "next": "16.2.4",
     "proper-lockfile": "^4.1.2",
@@ -103,7 +104,6 @@
     "gray-matter": "^4.0.3",
     "hast-util-to-html": "^9.0.5",
     "highlight.js": "^11.11.1",
-    "jszip": "^3.10.1",
     "lowlight": "^3.3.0",
     "lucide-react": "^0.525.0",
     "mammoth": "^1.12.0",

package/.next/standalone/packages/wiki-viewer-mcp/bench-payload.mjs

@@ -0,0 +1,45 @@
+/**
+ * Payload-size model: how much does whole-file PUT cost vs a diff/patch,
+ * across realistic .md sizes and uplink speeds? Decides whether a server-side
+ * patch endpoint is worth building.
+ *
+ * Pure arithmetic model (no network needed): upload_time = bytes / uplink_Bps.
+ * A small edit changes ~1 line; a patch payload ≈ the changed region + framing.
+ *
+ * Run: node packages/wiki-viewer-mcp/bench-payload.mjs
+ */
+const DOC_SIZES = [
+	{ label: "small note (2 KB)", bytes: 2 * 1024 },
+	{ label: "typical doc (20 KB)", bytes: 20 * 1024 },
+	{ label: "long doc (100 KB)", bytes: 100 * 1024 },
+	{ label: "big doc (500 KB)", bytes: 500 * 1024 },
+];
+// Uplink speeds (bytes/sec). Home/office uplinks are often the bottleneck.
+const UPLINKS = [
+	{ label: "fast (10 MB/s)", bps: 10 * 1024 * 1024 },
+	{ label: "typical home up (2 Mbps = 0.25 MB/s)", bps: 0.25 * 1024 * 1024 },
+	{ label: "slow / shared (0.5 Mbps)", bps: 0.0625 * 1024 * 1024 },
+];
+const PATCH_PAYLOAD = 300; // bytes: a one-line str-replace patch + JSON framing
+
+function ms(bytes, bps) { return (bytes / bps) * 1000; }
+
+console.log("\nupload-time model — whole-file PUT vs ~300B patch (transfer only)\n");
+for (const up of UPLINKS) {
+	console.log(`uplink: ${up.label}`);
+	console.log("  " + ["doc".padEnd(22), "whole-file", "patch", "speedup"].join("  "));
+	for (const d of DOC_SIZES) {
+		const whole = ms(d.bytes, up.bps);
+		const patch = ms(PATCH_PAYLOAD, up.bps);
+		const speedup = whole / patch;
+		console.log("  " + [
+			d.label.padEnd(22),
+			`${whole.toFixed(0)}ms`.padStart(10),
+			`${patch.toFixed(1)}ms`.padStart(7),
+			`${speedup.toFixed(0)}x`.padStart(7),
+		].join("  "));
+	}
+	console.log("");
+}
+console.log("Note: this is transfer time only; add RTT + handshake (now pooled) on top.");
+console.log("Whole-file PUT also re-sends unchanged bytes every edit; patch sends only the change.\n");

package/.next/standalone/packages/wiki-viewer-mcp/dist/http-client.js

@@ -33,6 +33,24 @@ export class CollabActiveError extends WikiViewerError {
         this.name = "CollabActiveError";
     }
 }
+/** PATCH endpoint absent (old server) or method not allowed — caller should fall back to read+PUT. */
+export class PatchUnsupportedError extends WikiViewerError {
+    constructor(path, status) {
+        super(status, "PATCH_UNSUPPORTED", `Server does not support PATCH for ${path}`, undefined);
+        this.name = "PatchUnsupportedError";
+    }
+}
+/** Server-side str-replace found a different number of matches than expected. */
+export class MatchCountError extends WikiViewerError {
+    found;
+    expected;
+    constructor(path, found, expected, body) {
+        super(422, "MATCH_COUNT_MISMATCH", `${path}: expected ${expected} match(es), found ${found}`, body);
+        this.found = found;
+        this.expected = expected;
+        this.name = "MatchCountError";
+    }
+}
 // ─── Client ──────────────────────────────────────────────────────────────────
 export class WikiViewerClient {
     baseUrl;
@@ -114,6 +132,8 @@ export class WikiViewerClient {
             collabRevision: collab.collabRevision,
             collabSnapshot: collab.collabSnapshot,
             fetchedAt: Date.now(),
+            // Cache the text body (bounded) so edit_file can skip a re-GET.
+            body: text !== null && bodyBuf.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
         };
         cache.set(path, state);
         return { body: bodyBuf, text, sha256, size, mtime, contentType, ...collab };
@@ -134,23 +154,110 @@ export class WikiViewerClient {
             params["mkdirs"] = "true";
         if (opts.force)
             params["force"] = "true";
-        const body = typeof content === "string"
+        const encoded = typeof content === "string"
             ? new TextEncoder().encode(content)
             : content;
-        const res = await this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
+        const body = encoded;
+        const doPut = (headers) => this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
             method: "PUT",
-            headers: this.headers({ "Content-Type": "application/octet-stream", ...extraHeaders }),
+            headers: this.headers({ "Content-Type": "application/octet-stream", ...headers }),
             body,
         });
+        let res = await doPut(extraHeaders);
+        // Auto-recover from "If-Match required" (overwrite without a known sha):
+        // the server demands a precondition for existing files. Transparently fetch
+        // the current sha and retry once, instead of bubbling a 412 to the agent
+        // (which would cost it an extra read + retry round-trip of its own).
+        if (res.status === 412 &&
+            !extraHeaders["If-Match"] &&
+            !opts.force &&
+            opts.ifMatch === undefined) {
+            let body412;
+            try {
+                body412 = await res.clone().json();
+            }
+            catch { /* ignore */ }
+            const code = body412?.error;
+            if (code === "PRECONDITION_REQUIRED") {
+                const cur = await this.readFile(path);
+                if (cur?.sha256) {
+                    res = await doPut({ ...extraHeaders, "If-Match": cur.sha256 });
+                }
+            }
+        }
+        await this.assertOk(res, path);
+        const result = await res.json();
+        // Update cache after a successful write. Preserve known collab fields from a
+        // prior read (do NOT clobber to not-markdown), refresh sha + body.
+        const prior = cache.get(path);
+        const text = typeof content === "string" ? content : null;
+        cache.set(path, {
+            sha256: result.sha256,
+            collabState: prior?.collabState ?? "not-markdown",
+            collabRevision: prior?.collabRevision ?? null,
+            collabSnapshot: prior?.collabSnapshot ?? null,
+            fetchedAt: Date.now(),
+            body: text !== null && encoded.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
+        });
+        return result;
+    }
+    // ── patch_file (server-side str-replace) ─────────────────────────────────────
+    /**
+     * Server-side exact str-replace: sends only {find, replace} instead of the
+     * whole file. Requires If-Match (auto-filled from cache if not given).
+     * Throws PatchUnsupportedError on 404/405 so callers can fall back to
+     * read+PUT against older servers, and MatchCountError on 422.
+     */
+    async patchFile(path, find, replace, opts = {}) {
+        const ifMatch = opts.ifMatch ?? cache.get(path)?.sha256;
+        const headers = { "Content-Type": "application/json" };
+        if (ifMatch)
+            headers["If-Match"] = ifMatch;
+        if (opts.ifCollabMatch !== undefined)
+            headers["If-Collab-Match"] = String(opts.ifCollabMatch);
+        const payload = { find, replace };
+        if (opts.expectedOccurrences !== undefined)
+            payload.expectedOccurrences = opts.expectedOccurrences;
+        const res = await this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`), { method: "PATCH", headers: this.headers(headers), body: JSON.stringify(payload) });
+        // 405 = method not allowed (endpoint absent). 404 is ambiguous: our handler
+        // returns 404 {error:"NOT_FOUND"} for a missing FILE, but an old server with
+        // no PATCH route returns a bare 404. Only treat 404 as "unsupported" when the
+        // body is NOT our structured NOT_FOUND (so a missing file surfaces normally).
+        if (res.status === 405) {
+            throw new PatchUnsupportedError(path, res.status);
+        }
+        if (res.status === 404) {
+            let body;
+            try {
+                body = await res.clone().json();
+            }
+            catch { /* not JSON → likely no route */ }
+            const code = body?.error;
+            if (code !== "NOT_FOUND")
+                throw new PatchUnsupportedError(path, 404);
+            // else fall through to assertOk → throws WikiViewerError(404) for missing file
+        }
+        if (res.status === 422) {
+            let body;
+            try {
+                body = await res.json();
+            }
+            catch { /* ignore */ }
+            const b = body;
+            throw new MatchCountError(path, Number(b?.found ?? -1), Number(b?.expected ?? -1), body);
+        }
         await this.assertOk(res, path);
         const result = await res.json();
-        // Update cache after successful write
+        const prior = cache.get(path);
         cache.set(path, {
             sha256: result.sha256,
-            collabState: "not-markdown",
-            collabRevision: null,
-            collabSnapshot: null,
+            collabState: prior?.collabState ?? "not-markdown",
+            collabRevision: prior?.collabRevision ?? null,
+            collabSnapshot: prior?.collabSnapshot ?? null,
             fetchedAt: Date.now(),
+            // We don't have the full new body here without reconstructing it; drop the
+            // stale cached body so the next edit re-reads rather than patching blind.
+            body: undefined,
         });
         return result;
     }

package/.next/standalone/packages/wiki-viewer-mcp/dist/index.js

@@ -22,8 +22,33 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { parseArgs } from "node:util";
-import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError } from "./http-client.js";
+import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError, PatchUnsupportedError, MatchCountError } from "./http-client.js";
 import * as stateCache from "./state-cache.js";
+/**
+ * Enable pooled HTTP keep-alive for the global fetch the client uses.
+ *
+ * Without this, every tool call opens a fresh connection and pays a full
+ * TCP + TLS handshake (~3 RTT) before the request even goes out. Over a WAN
+ * link that turns a sub-100ms write into 300ms-1s+, and multiplies across the
+ * GET+PUT an edit performs. Reusing connections removes that per-call penalty.
+ *
+ * Wrapped in try/catch + dynamic import so a missing/edge undici never breaks
+ * startup; it just falls back to default (non-pooled) fetch.
+ */
+async function enableKeepAlive() {
+    try {
+        const { Agent, setGlobalDispatcher } = await import("undici");
+        setGlobalDispatcher(new Agent({
+            keepAliveTimeout: 30_000,
+            keepAliveMaxTimeout: 60_000,
+            connections: 16,
+            pipelining: 1,
+        }));
+    }
+    catch {
+        // undici unavailable — default fetch still works, just without pooling.
+    }
+}
 import { register, RegistrationDeniedError, RegistrationExpiredError, RegistrationTimeoutError, } from "./register.js";
 // ─── Config ───────────────────────────────────────────────────────────────────
 function requireEnv(name) {
@@ -221,12 +246,41 @@ export function createServer(client) {
                     const block = checkCollabBlock(path);
                     if (block)
                         return err(block);
-                    // Read → transform → PUT with If-Match
+                    // Best path: server-side PATCH str-replace — sends only {find,replace}
+                    // (~hundreds of bytes) instead of the whole file. One small request.
+                    // Requires a known sha (If-Match); use cached sha if present, else the
+                    // server's 412-recover path handles it. Falls back to read+PUT if the
+                    // server has no PATCH route (older version).
+                    const cachedForPatch = stateCache.get(path);
+                    if (cachedForPatch?.collabState !== "active") {
+                        try {
+                            const r = await client.patchFile(path, find, replace, {
+                                ifMatch: cachedForPatch?.sha256,
+                            });
+                            return ok(`Edited: ${path}\nReplaced ${JSON.stringify(find)} → ${JSON.stringify(replace)}\nNew sha256: ${r.sha256}`);
+                        }
+                        catch (e) {
+                            if (e instanceof MatchCountError) {
+                                return err(`edit_file: expected to replace exactly 1 occurrence of ${JSON.stringify(find)} in "${path}", ` +
+                                    `but found ${e.found}. Re-read the file or make the search string unique.`);
+                            }
+                            if (e instanceof CollabActiveError) {
+                                return err(collabActiveMessage(path, e.snapshotUrl));
+                            }
+                            if (e instanceof IfMatchError) {
+                                // sha was stale — fall through to read+retry below.
+                            }
+                            else if (!(e instanceof PatchUnsupportedError)) {
+                                throw e;
+                            }
+                            // PatchUnsupportedError or stale If-Match → fall back to read+PUT.
+                        }
+                    }
+                    // Fallback path: read → transform → PUT with If-Match.
                     const readResult = await client.readFile(path);
                     if (readResult.text === null) {
                         return err(`edit_file: "${path}" appears to be binary — cannot do text replacement.`);
                     }
-                    // Check collab state from fresh read
                     if (readResult.collabState === "active") {
                         return err(collabActiveMessage(path, readResult.collabSnapshot));
                     }
@@ -338,6 +392,7 @@ function buildJsonSchema(val) {
 }
 // ─── Entrypoints ─────────────────────────────────────────────────────────────
 async function main() {
+    await enableKeepAlive();
     const client = createClient();
     const server = createServer(client);
     const transport = new StdioServerTransport();

package/.next/standalone/packages/wiki-viewer-mcp/dist/state-cache.js

@@ -2,6 +2,8 @@
  * Per-path cache for last-known file metadata from GET responses.
  * Drives If-Match and collab-state checks on subsequent writes.
  */
+/** Don't cache bodies larger than this (avoid unbounded memory). */
+export const MAX_CACHED_BODY_BYTES = 256 * 1024;
 const cache = new Map();
 export function set(path, state) {
     cache.set(normalisePath(path), state);

package/.next/standalone/packages/wiki-viewer-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-viewer-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP filesystem adapter for wiki-viewer agent API",
   "license": "MIT",
   "type": "module",

package/.next/standalone/packages/wiki-viewer-mcp/src/http-client.ts

@@ -51,6 +51,22 @@ export class CollabActiveError extends WikiViewerError {
   }
 }
 
+/** PATCH endpoint absent (old server) or method not allowed — caller should fall back to read+PUT. */
+export class PatchUnsupportedError extends WikiViewerError {
+  constructor(path: string, status: number) {
+    super(status, "PATCH_UNSUPPORTED", `Server does not support PATCH for ${path}`, undefined);
+    this.name = "PatchUnsupportedError";
+  }
+}
+
+/** Server-side str-replace found a different number of matches than expected. */
+export class MatchCountError extends WikiViewerError {
+  constructor(path: string, public readonly found: number, public readonly expected: number, body?: unknown) {
+    super(422, "MATCH_COUNT_MISMATCH", `${path}: expected ${expected} match(es), found ${found}`, body);
+    this.name = "MatchCountError";
+  }
+}
+
 // ─── Response shapes ─────────────────────────────────────────────────────────
 
 export interface ReadResult {
@@ -189,6 +205,8 @@ export class WikiViewerClient {
       collabRevision: collab.collabRevision,
       collabSnapshot: collab.collabSnapshot,
       fetchedAt: Date.now(),
+      // Cache the text body (bounded) so edit_file can skip a re-GET.
+      body: text !== null && bodyBuf.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
     };
     cache.set(path, state);
 
@@ -221,28 +239,119 @@ export class WikiViewerClient {
     if (opts.mkdirs) params["mkdirs"] = "true";
     if (opts.force) params["force"] = "true";
 
-    const body: BodyInit = typeof content === "string"
-      ? (new TextEncoder().encode(content) as unknown as Uint8Array<ArrayBuffer>)
-      : (content as unknown as Uint8Array<ArrayBuffer>);
+    const encoded: Uint8Array = typeof content === "string"
+      ? new TextEncoder().encode(content)
+      : content;
+    const body = encoded as unknown as Uint8Array<ArrayBuffer>;
 
-    const res = await this._fetch(
-      this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params),
-      {
+    const doPut = (headers: Record<string, string>) =>
+      this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
         method: "PUT",
-        headers: this.headers({ "Content-Type": "application/octet-stream", ...extraHeaders }),
+        headers: this.headers({ "Content-Type": "application/octet-stream", ...headers }),
         body,
-      },
+      });
+
+    let res = await doPut(extraHeaders);
+
+    // Auto-recover from "If-Match required" (overwrite without a known sha):
+    // the server demands a precondition for existing files. Transparently fetch
+    // the current sha and retry once, instead of bubbling a 412 to the agent
+    // (which would cost it an extra read + retry round-trip of its own).
+    if (
+      res.status === 412 &&
+      !extraHeaders["If-Match"] &&
+      !opts.force &&
+      opts.ifMatch === undefined
+    ) {
+      let body412: unknown;
+      try { body412 = await res.clone().json(); } catch { /* ignore */ }
+      const code = (body412 as Record<string, unknown> | undefined)?.error;
+      if (code === "PRECONDITION_REQUIRED") {
+        const cur = await this.readFile(path);
+        if (cur?.sha256) {
+          res = await doPut({ ...extraHeaders, "If-Match": cur.sha256 });
+        }
+      }
+    }
+
+    await this.assertOk(res, path);
+
+    const result: WriteResult = await res.json() as WriteResult;
+    // Update cache after a successful write. Preserve known collab fields from a
+    // prior read (do NOT clobber to not-markdown), refresh sha + body.
+    const prior = cache.get(path);
+    const text = typeof content === "string" ? content : null;
+    cache.set(path, {
+      sha256: result.sha256,
+      collabState: prior?.collabState ?? "not-markdown",
+      collabRevision: prior?.collabRevision ?? null,
+      collabSnapshot: prior?.collabSnapshot ?? null,
+      fetchedAt: Date.now(),
+      body: text !== null && encoded.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
+    });
+    return result;
+  }
+
+  // ── patch_file (server-side str-replace) ─────────────────────────────────────
+
+  /**
+   * Server-side exact str-replace: sends only {find, replace} instead of the
+   * whole file. Requires If-Match (auto-filled from cache if not given).
+   * Throws PatchUnsupportedError on 404/405 so callers can fall back to
+   * read+PUT against older servers, and MatchCountError on 422.
+   */
+  async patchFile(
+    path: string,
+    find: string,
+    replace: string,
+    opts: { ifMatch?: string; expectedOccurrences?: number; ifCollabMatch?: number } = {},
+  ): Promise<WriteResult> {
+    const ifMatch = opts.ifMatch ?? cache.get(path)?.sha256;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (ifMatch) headers["If-Match"] = ifMatch;
+    if (opts.ifCollabMatch !== undefined) headers["If-Collab-Match"] = String(opts.ifCollabMatch);
+
+    const payload: Record<string, unknown> = { find, replace };
+    if (opts.expectedOccurrences !== undefined) payload.expectedOccurrences = opts.expectedOccurrences;
+
+    const res = await this._fetch(
+      this.url(`/api/agent/fs/file/${encodeFilePath(path)}`),
+      { method: "PATCH", headers: this.headers(headers), body: JSON.stringify(payload) },
     );
+
+    // 405 = method not allowed (endpoint absent). 404 is ambiguous: our handler
+    // returns 404 {error:"NOT_FOUND"} for a missing FILE, but an old server with
+    // no PATCH route returns a bare 404. Only treat 404 as "unsupported" when the
+    // body is NOT our structured NOT_FOUND (so a missing file surfaces normally).
+    if (res.status === 405) {
+      throw new PatchUnsupportedError(path, res.status);
+    }
+    if (res.status === 404) {
+      let body: unknown;
+      try { body = await res.clone().json(); } catch { /* not JSON → likely no route */ }
+      const code = (body as Record<string, unknown> | undefined)?.error;
+      if (code !== "NOT_FOUND") throw new PatchUnsupportedError(path, 404);
+      // else fall through to assertOk → throws WikiViewerError(404) for missing file
+    }
+    if (res.status === 422) {
+      let body: unknown;
+      try { body = await res.json(); } catch { /* ignore */ }
+      const b = body as Record<string, unknown> | undefined;
+      throw new MatchCountError(path, Number(b?.found ?? -1), Number(b?.expected ?? -1), body);
+    }
     await this.assertOk(res, path);
 
     const result: WriteResult = await res.json() as WriteResult;
-    // Update cache after successful write
+    const prior = cache.get(path);
     cache.set(path, {
       sha256: result.sha256,
-      collabState: "not-markdown",
-      collabRevision: null,
-      collabSnapshot: null,
+      collabState: prior?.collabState ?? "not-markdown",
+      collabRevision: prior?.collabRevision ?? null,
+      collabSnapshot: prior?.collabSnapshot ?? null,
       fetchedAt: Date.now(),
+      // We don't have the full new body here without reconstructing it; drop the
+      // stale cached body so the next edit re-reads rather than patching blind.
+      body: undefined,
     });
     return result;
   }

package/.next/standalone/packages/wiki-viewer-mcp/src/index.ts

@@ -27,7 +27,7 @@ import {
 import * as z from "zod";
 
 import { parseArgs } from "node:util";
-import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError } from "./http-client.js";
+import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError, PatchUnsupportedError, MatchCountError } from "./http-client.js";
 import * as stateCache from "./state-cache.js";
 
 /**
@@ -314,17 +314,47 @@ export function createServer(client: WikiViewerClient): Server {
           const block = checkCollabBlock(path);
           if (block) return err(block);
 
-          // Read → transform → PUT with If-Match
+          // Best path: server-side PATCH str-replace — sends only {find,replace}
+          // (~hundreds of bytes) instead of the whole file. One small request.
+          // Requires a known sha (If-Match); use cached sha if present, else the
+          // server's 412-recover path handles it. Falls back to read+PUT if the
+          // server has no PATCH route (older version).
+          const cachedForPatch = stateCache.get(path);
+          if (cachedForPatch?.collabState !== "active") {
+            try {
+              const r = await client.patchFile(path, find, replace, {
+                ifMatch: cachedForPatch?.sha256,
+              });
+              return ok(
+                `Edited: ${path}\nReplaced ${JSON.stringify(find)} → ${JSON.stringify(replace)}\nNew sha256: ${r.sha256}`,
+              );
+            } catch (e) {
+              if (e instanceof MatchCountError) {
+                return err(
+                  `edit_file: expected to replace exactly 1 occurrence of ${JSON.stringify(find)} in "${path}", ` +
+                  `but found ${e.found}. Re-read the file or make the search string unique.`,
+                );
+              }
+              if (e instanceof CollabActiveError) {
+                return err(collabActiveMessage(path, e.snapshotUrl));
+              }
+              if (e instanceof IfMatchError) {
+                // sha was stale — fall through to read+retry below.
+              } else if (!(e instanceof PatchUnsupportedError)) {
+                throw e;
+              }
+              // PatchUnsupportedError or stale If-Match → fall back to read+PUT.
+            }
+          }
+
+          // Fallback path: read → transform → PUT with If-Match.
           const readResult = await client.readFile(path);
           if (readResult.text === null) {
             return err(`edit_file: "${path}" appears to be binary — cannot do text replacement.`);
           }
-
-          // Check collab state from fresh read
           if (readResult.collabState === "active") {
             return err(collabActiveMessage(path, readResult.collabSnapshot));
           }
-
           if (!readResult.text.includes(find)) {
             return err(
               `edit_file: string not found in "${path}".\n` +

package/.next/standalone/packages/wiki-viewer-mcp/src/state-cache.ts

@@ -15,8 +15,18 @@ export interface PathState {
   collabSnapshot: string | null;
   /** When this cache entry was last updated (ms) */
   fetchedAt: number;
+  /**
+   * Last-known text body, paired with `sha256`. Only set for text files from a
+   * read. Lets edit_file skip the GET round-trip: it transforms this cached
+   * text and PUTs with If-Match=sha256; if the file changed server-side the
+   * PUT 412s and the caller re-reads. Capped by MAX_CACHED_BODY_BYTES.
+   */
+  body?: string;
 }
 
+/** Don't cache bodies larger than this (avoid unbounded memory). */
+export const MAX_CACHED_BODY_BYTES = 256 * 1024;
+
 const cache = new Map<string, PathState>();
 
 export function set(path: string, state: PathState): void {

package/.next/standalone/pnpm-lock.yaml

@@ -20,6 +20,9 @@ importers:
       chokidar:
         specifier: ^5.0.0
         version: 5.0.0
+      jszip:
+        specifier: ^3.10.1
+        version: 3.10.1
       kysely:
         specifier: 0.28.5
         version: 0.28.5
@@ -204,9 +207,6 @@ importers:
       highlight.js:
         specifier: ^11.11.1
         version: 11.11.1
-      jszip:
-        specifier: ^3.10.1
-        version: 3.10.1
       lowlight:
         specifier: ^3.3.0
         version: 3.3.0