ignore client roots by default in pdf-server (#510)

* 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>

examples/pdf-server/server.ts

@@ -443,19 +443,49 @@ async function refreshRoots(server: Server): Promise<void> {
 // MCP Server Factory
 // =============================================================================
 
-export function createServer(): McpServer {
+export interface CreateServerOptions {
+  /**
+   * Whether to honour MCP roots sent by the client.
+   *
+   * When a server is exposed over HTTP, the connecting client is
+   * typically remote and 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.
+   *
+   * For stdio the client is typically local (e.g. Claude Desktop on the
+   * same machine), so roots are safe and enabled by default.
+   *
+   * Set this to `true` for HTTP only when you trust the client, or
+   * pass the `--use-client-roots` CLI flag.
+   *
+   * @default false
+   */
+  useClientRoots?: boolean;
+}
+
+export function createServer(options: CreateServerOptions = {}): McpServer {
+  const { useClientRoots = false } = options;
   const server = new McpServer({ name: "PDF Server", version: "2.0.0" });
 
-  // Fetch roots on initialization and subscribe to changes
-  server.server.oninitialized = () => {
-    refreshRoots(server.server);
-  };
-  server.server.setNotificationHandler(
-    RootsListChangedNotificationSchema,
-    async () => {
-      await refreshRoots(server.server);
-    },
-  );
+  if (useClientRoots) {
+    // Fetch roots on initialization and subscribe to changes
+    server.server.oninitialized = () => {
+      refreshRoots(server.server);
+    };
+    server.server.setNotificationHandler(
+      RootsListChangedNotificationSchema,
+      async () => {
+        await refreshRoots(server.server);
+      },
+    );
+  } else {
+    console.error(
+      "[pdf-server] Client roots are ignored (default for remote transports). " +
+        "Pass --use-client-roots to allow the client to expose local directories.",
+    );
+  }
 
   // Create session-local cache (isolated per server instance)
   const { readPdfRange } = createPdfCache();