pdf-server: robust path validation + folder/file root support (#497)

* pdf-server: support folders in cli + files in roots

* fix(pdf-server): use path.relative for robust ancestor dir matching

- Replace string prefix matching (startsWith) with path.relative-based
  isAncestorDir() which correctly handles trailing slashes, path
  normalization, and prevents both .. traversal and prefix attacks.
- Use path.resolve consistently when adding paths to allowedLocalFiles
  and allowedLocalDirs (main.ts was missing this).
- Use resolved path for exact file match check in validateUrl.
- Improve error message formatting for easier debugging.
- Add tests for trailing slashes, grandparent dirs, and isAncestorDir.

* chore(pdf-server): remove JSONL interaction logging

Remove the withLogging transport wrapper, logInteraction helper,
InteractionLogger type, and all log parameter threading that were
added for debugging.

* fix(pdf-server): support computer:// URL scheme for local files

Some clients (e.g. Claude Code) use computer:// instead of file://
for local file references. Handle both schemes in isFileUrl and
fileUrlToPath.

* fix(pdf-server): add debug logging for rejected files, ignore .jsonl logs

* fix(pdf-server): accept bare file paths in addition to file:// URLs

Clients like Claude Desktop may pass raw absolute paths (e.g.
/Users/.../file.pdf) instead of file:// URLs. Handle these in
validateUrl and readPdfRange.

* debug(pdf-server): add hex char diagnostics for path mismatch

* fix(pdf-server): resolve symlinks to handle sandbox path remapping

Use fs.realpathSync to resolve symlinks/bind mounts when comparing
file paths against allowed directories. This fixes the path namespace
mismatch where Claude Desktop sends container paths (e.g. /sessions/...)
while MCP roots use host paths (e.g. /Users/...).

Both the file path and directory paths are resolved through symlinks
before comparison, so either side can be a symlink.

Also stores realpath of roots in allowedLocalDirs/Files so matching
works in both directions.

Removes verbose hex diagnostics (no longer needed).

* fix(pdf-server): decode percent-encoded bare paths (e.g. %20 for spaces)

Clients may send bare file paths with percent-encoded characters
(e.g., Application%20Support). Apply decodeURIComponent to bare paths
before resolving, matching the behavior already used for file:// URLs.

* fix(pdf-server): add full diagnostics to client-facing error message

Include url, resolved path, realpath, allowedFiles, and per-directory
path.relative results in the error returned to the client, so we can
diagnose why isAncestorDir fails when paths look identical.

* debug(pdf-server): add hex dump to diagnose invisible char differences

path.relative returns 10 levels of .. despite paths looking identical,
meaning they differ at the byte level. Add hex dump of first 30 chars
of both paths to catch invisible Unicode or encoding differences.

* fix(pdf-server): use inode comparison for bind-mount path matching

The cowork VM remaps paths via bind mounts: the tool input uses
VM-internal paths (/sessions/...) while MCP roots use host paths
(/Users/...). Since path.relative can't match across bind mounts,
compare directory inodes instead (dev+ino from fs.statSync).

Walks up the file's parent directories checking each against allowed
dirs by inode, which works regardless of path namespace differences.

* fix(pdf-server): resolve VM-internal paths via directory basename matching

When the MCP server runs on the host but receives unrewritten VM paths
(e.g., /sessions/name/mnt/uploads/file.pdf), the tool call url argument
isn't rewritten by the cowork VM proxy because it doesn't know which
arguments are file paths.

Fix: when path validation fails, try to match the file by finding the
directory basename (e.g., 'uploads') in the VM path and looking for
the relative path suffix under each allowed directory on the host.

Also returns the resolved host path so readPdfRange reads the correct
file on the host filesystem.

* revert(pdf-server): remove resolveVmPath hack

The VM path mismatch (VM-internal paths not rewritten in tool call
arguments) should be fixed in the cowork VM proxy layer, not worked
around in the MCP server.

Removes:
- resolveVmPath() function
- resolvedPath field from validateUrl return type
- effectiveUrl remapping in tool handlers
- VM path resolution test

* nit

Author: ochafik

examples/pdf-server/.gitignore

@@ -1 +1,2 @@
 dist/
+*.jsonl

examples/pdf-server/.mcpbignore

@@ -7,6 +7,9 @@ src/
 # Tests
 *.test.*
 
+# Debug logs
+*.jsonl
+
 # Development assets
 screenshot.png
 grid-cell.png

examples/pdf-server/main.ts

@@ -5,6 +5,7 @@
  */
 
 import fs from "node:fs";
+import path from "node:path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -20,6 +21,7 @@ import {
   fileUrlToPath,
   allowedLocalFiles,
   DEFAULT_PDF,
+  allowedLocalDirs,
 } from "./server.js";
 
 /**
@@ -120,10 +122,16 @@ async function main() {
   // Register local files in whitelist
   for (const url of urls) {
     if (isFileUrl(url)) {
-      const filePath = fileUrlToPath(url);
+      const filePath = path.resolve(fileUrlToPath(url));
       if (fs.existsSync(filePath)) {
-        allowedLocalFiles.add(filePath);
-        console.error(`[pdf-server] Registered local file: ${filePath}`);
+        const s = fs.statSync(filePath);
+        if (s.isFile()) {
+          allowedLocalFiles.add(filePath);
+          console.error(`[pdf-server] Registered local file: ${filePath}`);
+        } else if (s.isDirectory()) {
+          allowedLocalDirs.add(filePath);
+          console.error(`[pdf-server] Registered local directory: ${filePath}`);
+        }
       } else {
         console.error(`[pdf-server] Warning: File not found: ${filePath}`);
       }

examples/pdf-server/server.test.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import {
   createPdfCache,
   validateUrl,
+  isAncestorDir,
   allowedLocalFiles,
   allowedLocalDirs,
   pathToFileUrl,
@@ -271,4 +272,152 @@ describe("validateUrl with MCP roots (allowedLocalDirs)", () => {
     expect(result.valid).toBe(false);
     expect(result.error).toContain("File not found");
   });
+
+  it("should allow a file under an allowed dir with trailing slash", () => {
+    const dir = path.resolve(import.meta.dirname);
+    // Simulate a dir stored with a trailing slash (e.g. from CLI path)
+    allowedLocalDirs.add(dir + "/");
+
+    const filePath = path.join(dir, "server.ts");
+    const result = validateUrl(pathToFileUrl(filePath));
+    expect(result.valid).toBe(true);
+  });
+
+  it("should allow a file under a grandparent allowed dir", () => {
+    // Allow a directory two levels up from the file
+    const grandparent = path.resolve(path.join(import.meta.dirname, ".."));
+    allowedLocalDirs.add(grandparent);
+
+    const filePath = path.join(import.meta.dirname, "server.ts");
+    const result = validateUrl(pathToFileUrl(filePath));
+    expect(result.valid).toBe(true);
+  });
+
+  it("should accept computer:// URLs as local files", () => {
+    const dir = path.resolve(import.meta.dirname);
+    allowedLocalDirs.add(dir);
+
+    const filePath = path.join(dir, "server.ts");
+    const encoded = encodeURIComponent(filePath).replace(/%2F/g, "/");
+    const result = validateUrl(`computer://${encoded}`);
+    expect(result.valid).toBe(true);
+  });
+
+  it("should accept bare absolute paths as local files", () => {
+    const dir = path.resolve(import.meta.dirname);
+    allowedLocalDirs.add(dir);
+
+    const filePath = path.join(dir, "server.ts");
+    const result = validateUrl(filePath);
+    expect(result.valid).toBe(true);
+  });
+
+  it("should decode percent-encoded bare paths (e.g. %20 for spaces)", () => {
+    const fs = require("node:fs");
+    const os = require("node:os");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pdf test "));
+    const testFile = path.join(tmpDir, "file.txt");
+
+    try {
+      fs.writeFileSync(testFile, "hello");
+      allowedLocalDirs.add(tmpDir);
+
+      // Encode spaces as %20 in the path (as some clients do)
+      const encoded = testFile.replace(/ /g, "%20");
+      const result = validateUrl(encoded);
+      expect(result.valid).toBe(true);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  it("should allow file accessed via symlink when real dir is allowed", () => {
+    const fs = require("node:fs");
+    const os = require("node:os");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pdf-test-"));
+    const realDir = path.join(tmpDir, "real");
+    const linkDir = path.join(tmpDir, "link");
+    const testFile = path.join(realDir, "test.txt");
+
+    try {
+      fs.mkdirSync(realDir);
+      fs.writeFileSync(testFile, "hello");
+      fs.symlinkSync(realDir, linkDir);
+
+      // Allow the REAL directory
+      allowedLocalDirs.add(realDir);
+
+      // Access via the SYMLINK path — should still be allowed
+      const symlinkPath = path.join(linkDir, "test.txt");
+      const result = validateUrl(symlinkPath);
+      expect(result.valid).toBe(true);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true });
+    }
+  });
+
+  it("should allow file when allowed dir is a symlink to real parent", () => {
+    const fs = require("node:fs");
+    const os = require("node:os");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pdf-test-"));
+    const realDir = path.join(tmpDir, "real");
+    const linkDir = path.join(tmpDir, "link");
+    const testFile = path.join(realDir, "test.txt");
+
+    try {
+      fs.mkdirSync(realDir);
+      fs.writeFileSync(testFile, "hello");
+      fs.symlinkSync(realDir, linkDir);
+
+      // Allow the SYMLINK directory
+      allowedLocalDirs.add(linkDir);
+
+      // Access via the REAL path — should still be allowed
+      const result = validateUrl(testFile);
+      expect(result.valid).toBe(true);
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true });
+    }
+  });
+});
+
+describe("isAncestorDir", () => {
+  it("should return true for a direct child", () => {
+    expect(isAncestorDir("/Users/test/dir", "/Users/test/dir/file.pdf")).toBe(
+      true,
+    );
+  });
+
+  it("should return true for a nested child", () => {
+    expect(isAncestorDir("/Users/test", "/Users/test/sub/dir/file.pdf")).toBe(
+      true,
+    );
+  });
+
+  it("should return false for a file outside the dir", () => {
+    expect(isAncestorDir("/Users/test/dir", "/Users/test/other/file.pdf")).toBe(
+      false,
+    );
+  });
+
+  it("should return false for the dir itself", () => {
+    expect(isAncestorDir("/Users/test/dir", "/Users/test/dir")).toBe(false);
+  });
+
+  it("should prevent .. traversal", () => {
+    expect(
+      isAncestorDir("/Users/test/dir", "/Users/test/dir/../other/file.pdf"),
+    ).toBe(false);
+  });
+
+  it("should prevent prefix-based traversal", () => {
+    // /tmp/safe should NOT match /tmp/safevil/file.pdf
+    expect(isAncestorDir("/tmp/safe", "/tmp/safevil/file.pdf")).toBe(false);
+  });
+
+  it("should handle dirs with trailing slash", () => {
+    expect(isAncestorDir("/Users/test/dir/", "/Users/test/dir/file.pdf")).toBe(
+      true,
+    );
+  });
 });