* security: ignore client roots by default in pdf-server
When the pdf-server is started with --stdio, MCP clients may advertise
roots that refer to directories on the *client's* file system. Because
the server resolves those paths locally, accepting them by default would
give the remote client access to arbitrary directories on the server's
machine.
This commit makes client roots opt-in via the --use-client-roots flag.
Without the flag, the server logs a notice and skips roots setup
entirely. The createServer() function now accepts a CreateServerOptions
object with a `useClientRoots` boolean (defaults to false).
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* Enable client roots by default for HTTP, keep off for stdio
HTTP mode serves a local client so roots are safe. Stdio mode may
have a remote client whose roots would resolve against the server's
filesystem, so roots stay off unless --use-client-roots is passed.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* fix: correct transport-aware defaults for useClientRoots
stdio = local client (e.g. Claude Desktop) → auto-enable roots
HTTP = remote client → ignore roots unless --use-client-roots passed
The previous commit had the logic inverted.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* refactor: inline useClientRoots per transport branch
Remove the intermediate effectiveUseClientRoots variable — just pass
`true` in the stdio branch and the flag value in the HTTP branch.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
* docs: update README to match transport-aware client roots defaults
Stdio always enables roots (client is local); HTTP ignores them by
default. The previous README text had these reversed.
https://claude.ai/code/session_014ohk5NMEPe8TBKpqp4ZRSw
---------
Co-authored-by: Claude <noreply@anthropic.com>
* 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
* lazy PDF loading w/ PDFDataRangeTransport
* lint
* feat: lazy PDF loading via range transport + eager background preloading
Replace full-file download with PDFDataRangeTransport so PDF.js fetches
byte ranges on demand. First page renders immediately; remaining pages
load in background for search.
**Range transport (server + client)**
- server.ts: add read_pdf_bytes tool returning base64 chunks with offset
- mcp-app.ts: AppRangeTransport feeds PDF.js via fetchRange/fetchChunk
with parallel sub-requests for large ranges, Promise-based dedup of
concurrent requests, and a persistent range cache
**Background preloader**
- Sequential page 1→N text extraction, pauses during interactive
navigation (preloadPaused flag set in goToPage, cleared in renderPage)
- Debounced live search refresh (500ms) as pages load
- Search UI shows '(loading…)' suffix until all pages processed
**Loading indicators**
- SVG pie in toolbar: fills as pages load, fades on completion,
turns red on errors with tooltip listing failed pages
- Debounced page-loading overlay (150ms) for uncached page navigation
**Cleanup**
- Remove old full-file chunked download and progress bar
- Remove extractAllPageText (replaced by preloader)
- Remove verbose debug logs (Coverage, RangeReq, cache hit)
When the client advertises roots capability, the server queries roots/list
on initialization and subscribes to roots/list_changed notifications.
Any file:// roots pointing to existing directories are added to an
allowedLocalDirs set, enabling access to all PDFs under those directories
without needing to enumerate them via CLI args.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
fix: revert unrelated changes from bad rebase
Restores files that were accidentally modified alongside the MCP roots
feature: README, pdf-server UI (search feature), threejs example,
SDK guards (app.ts, app-bridge.ts), typedoc theme, media assets,
and e2e snapshots.
* fix(pdf-server): handle HTTP 200 fallback in remote range requests
When a remote server ignores the Range header and returns HTTP 200
with the full body, readPdfRange previously passed the entire file
(potentially 10MB+) through as a single chunk. This bypassed the
512KB limit because:
1. The error check `!response.ok && status !== 206` short-circuits
on 200 (ok is true), so the full body is read via arrayBuffer()
2. No Content-Range header on a 200 response leaves totalBytes at 0
3. hasMore becomes `offset + fullSize < 0` = false, so the client
stops after one oversized message
Fix: detect HTTP 200, cache the full body in memory (to avoid
re-downloading on every subsequent chunk request), then slice to the
requested range. The 512KB per-message limit is now enforced for all
remote URLs regardless of Range request support.
* Add session-based PDF caching with timeout cleanup and size limits
- Add dual timeout strategy for cache cleanup:
- 10s inactivity timeout (resets on each access)
- 60s max lifetime (absolute timeout from creation)
- Add 50MB max size limit with both Content-Length and actual size checks
- Add unit tests for caching behavior including:
- Cache on HTTP 200 response (no range support)
- No cache on HTTP 206 response (range supported)
- Slice cached data for subsequent range requests
- Reject PDFs exceeding size limits
- Export getCacheSize() and clearCache() for testing
* refactor(pdf-server): make PDF cache session-local via factory pattern
- Replace module-level global cache with createPdfCache() factory
- Each server instance now gets its own isolated cache
- Export PdfCache interface for type-safe usage
- Update tests to use per-test cache instances
- Add test verifying cache isolation between sessions
---------
Co-authored-by: Claude <noreply@anthropic.com>
