feat(pdf-server): treat uploads-root dirs as read-only by default

Dir roots whose basename is 'uploads' (e.g. Claude Desktop's attachment
drop folder) are now treated as read-only unless --writeable-uploads-root
is passed. This prevents the save button from appearing for attached PDFs
that the client doesn't expect to be overwritten.

Also gates the _debug diagnostic block on --debug and adds save/restore
of writeFlags.allowUploadsRoot in test beforeEach/afterEach.

Author: ochafik

examples/pdf-server/server.test.ts

@@ -16,6 +16,7 @@ import {
   stopFileWatch,
   cliLocalFiles,
   isWritablePath,
+  writeFlags,
   CACHE_INACTIVITY_TIMEOUT_MS,
   CACHE_MAX_LIFETIME_MS,
   CACHE_MAX_PDF_SIZE_BYTES,
@@ -459,6 +460,7 @@ describe("isWritablePath", () => {
   let savedFiles: Set<string>;
   let savedDirs: Set<string>;
   let savedCli: Set<string>;
+  let savedAllowUploadsRoot: boolean;
 
   beforeEach(() => {
     savedFiles = new Set(allowedLocalFiles);
@@ -467,6 +469,8 @@ describe("isWritablePath", () => {
     allowedLocalFiles.clear();
     allowedLocalDirs.clear();
     cliLocalFiles.clear();
+    savedAllowUploadsRoot = writeFlags.allowUploadsRoot;
+    writeFlags.allowUploadsRoot = false;
   });
 
   afterEach(() => {
@@ -476,6 +480,7 @@ describe("isWritablePath", () => {
     for (const x of savedFiles) allowedLocalFiles.add(x);
     for (const x of savedDirs) allowedLocalDirs.add(x);
     for (const x of savedCli) cliLocalFiles.add(x);
+    writeFlags.allowUploadsRoot = savedAllowUploadsRoot;
   });
 
   it("nothing is writable when no roots and no CLI files", () => {
@@ -526,6 +531,43 @@ describe("isWritablePath", () => {
     expect(isWritablePath("/home/user/other/file.pdf")).toBe(false);
     expect(isWritablePath("/home/user/docsevil/file.pdf")).toBe(false);
   });
+
+  it("dir root named 'uploads' is read-only by default", () => {
+    // Claude Desktop mounts the conversation's attachment drop folder as a
+    // directory root literally named 'uploads'. The attached PDF lives
+    // directly under it.
+    allowedLocalDirs.add("/var/folders/xy/T/claude/uploads");
+    expect(isWritablePath("/var/folders/xy/T/claude/uploads/Form.pdf")).toBe(
+      false,
+    );
+    // Deep nesting under the uploads root — still the same root, still no.
+    expect(
+      isWritablePath("/var/folders/xy/T/claude/uploads/sub/deep.pdf"),
+    ).toBe(false);
+  });
+
+  it("uploads-root guard matches basename, not substring", () => {
+    allowedLocalDirs.add("/home/user/my-uploads"); // contains 'uploads' but ≠
+    allowedLocalDirs.add("/home/user/uploads-archive");
+    expect(isWritablePath("/home/user/my-uploads/f.pdf")).toBe(true);
+    expect(isWritablePath("/home/user/uploads-archive/f.pdf")).toBe(true);
+  });
+
+  it("--writeable-uploads-root opts back in", () => {
+    allowedLocalDirs.add("/var/folders/xy/T/claude/uploads");
+    writeFlags.allowUploadsRoot = true;
+    expect(isWritablePath("/var/folders/xy/T/claude/uploads/Form.pdf")).toBe(
+      true,
+    );
+  });
+
+  it("CLI file under an uploads root is still writable", () => {
+    // Explicit CLI intent beats the uploads-basename heuristic.
+    allowedLocalDirs.add("/tmp/uploads");
+    allowedLocalFiles.add("/tmp/uploads/explicit.pdf");
+    cliLocalFiles.add("/tmp/uploads/explicit.pdf");
+    expect(isWritablePath("/tmp/uploads/explicit.pdf")).toBe(true);
+  });
 });
 
 describe("file watching", () => {

examples/pdf-server/server.ts

@@ -94,6 +94,21 @@ export const allowedLocalDirs = new Set<string>();
  */
 export const cliLocalFiles = new Set<string>();
 
+/**
+ * Write-permission flags. Object wrapper (not a bare `let`) so main.ts can
+ * mutate via the exported binding without re-import gymnastics — same
+ * pattern as the Sets above.
+ */
+export const writeFlags = {
+  /**
+   * Claude Desktop mounts its per-conversation drop folder as a directory
+   * root whose basename is literally `uploads`. Files in there are one-shot
+   * copies the client doesn't expect us to overwrite. Default: read-only.
+   * `--writeable-uploads-root` flips this for local testing.
+   */
+  allowUploadsRoot: false,
+};
+
 /**
  * Saving is allowed iff:
  *   (a) the file was passed as a CLI arg — the user explicitly named it
@@ -105,13 +120,24 @@ export const cliLocalFiles = new Set<string>();
  *       treat that signal as authoritative even when the path happens
  *       to fall inside a mounted directory.
  *
+ *   EXCEPTION to (b): a dir root whose basename is `uploads` is treated
+ *   as read-only unless `writeFlags.allowUploadsRoot` is set. This is how
+ *   Claude Desktop surfaces attached files — writing back to them
+ *   surprises the user (the attachment doesn't update).
+ *
  * With no directory roots and no CLI files, nothing is writable.
  */
 export function isWritablePath(resolved: string): boolean {
   if (cliLocalFiles.has(resolved)) return true;
   // MCP file root → always read-only, regardless of ancestry
   if (allowedLocalFiles.has(resolved)) return false;
-  return [...allowedLocalDirs].some((dir) => isAncestorDir(dir, resolved));
+  return [...allowedLocalDirs].some((dir) => {
+    if (!isAncestorDir(dir, resolved)) return false;
+    if (!writeFlags.allowUploadsRoot && path.basename(dir) === "uploads") {
+      return false;
+    }
+    return true;
+  });
 }
 
 // Works both from source (server.ts) and compiled (dist/server.js)
@@ -1158,10 +1184,17 @@ export interface CreateServerOptions {
    * @default false
    */
   useClientRoots?: boolean;
+
+  /**
+   * Emit debug metadata to the viewer (currently: allowed roots shown
+   * in a floating bubble). Toggled by the `--debug` CLI flag.
+   */
+  debug?: boolean;
 }
 
 export function createServer(options: CreateServerOptions = {}): McpServer {
   const { enableInteract = false, useClientRoots = false } = options;
+  const debug = options.debug ?? false;
   const disableInteract = !enableInteract;
   const server = new McpServer({ name: "PDF Server", version: "2.0.0" });
 
@@ -1432,11 +1465,13 @@ Set \`elicit_form_inputs\` to true to prompt the user to fill form fields before
       // Check writability (governs save button; see isWritablePath doc).
       // Also requires OS-level W_OK so we don't lie on read-only mounts.
       let writable = false;
+      let debugResolved: string | undefined; // only used when --debug
       if (isFileUrl(normalized) || isLocalPath(normalized)) {
         const localPath = isFileUrl(normalized)
           ? fileUrlToPath(normalized)
           : decodeURIComponent(normalized);
         const resolved = path.resolve(localPath);
+        debugResolved = resolved;
         if (isWritablePath(resolved)) {
           try {
             await fs.promises.access(resolved, fs.constants.W_OK);
@@ -1595,6 +1630,21 @@ Set \`elicit_form_inputs\` to true to prompt the user to fill form fields before
           viewUUID: uuid,
           interactEnabled: !disableInteract,
           writable,
+          // Debug: viewer renders this in a floating bubble (--debug flag).
+          ...(debug
+            ? {
+                _debug: {
+                  resolved: debugResolved,
+                  writable,
+                  isWritablePath: debugResolved
+                    ? isWritablePath(debugResolved)
+                    : undefined,
+                  cliLocalFiles: [...cliLocalFiles],
+                  allowedLocalFiles: [...allowedLocalFiles],
+                  allowedLocalDirs: [...allowedLocalDirs],
+                },
+              }
+            : {}),
         },
       };
     },