@modelcontextprotocol/server-pdf 1.0.1 → 1.1.0

package/dist/server.d.ts

@@ -13,10 +13,18 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare const DEFAULT_PDF = "https://arxiv.org/pdf/1706.03762";
 export declare const MAX_CHUNK_BYTES: number;
 export declare const RESOURCE_URI = "ui://pdf-viewer/mcp-app.html";
+/** Inactivity timeout: clear cache entry if not accessed for this long */
+export declare const CACHE_INACTIVITY_TIMEOUT_MS = 10000;
+/** Max lifetime: clear cache entry after this time regardless of access */
+export declare const CACHE_MAX_LIFETIME_MS = 60000;
+/** Max size for cached PDFs (defensive limit to prevent memory exhaustion) */
+export declare const CACHE_MAX_PDF_SIZE_BYTES: number;
 /** Allowed remote origins (security allowlist) */
 export declare const allowedRemoteOrigins: Set<string>;
 /** Allowed local file paths (populated from CLI args) */
 export declare const allowedLocalFiles: Set<string>;
+/** Allowed local directories (populated from MCP roots) */
+export declare const allowedLocalDirs: Set<string>;
 export declare function isFileUrl(url: string): boolean;
 export declare function isArxivUrl(url: string): boolean;
 export declare function normalizeArxivUrl(url: string): string;
@@ -26,8 +34,30 @@ export declare function validateUrl(url: string): {
     valid: boolean;
     error?: string;
 };
-export declare function readPdfRange(url: string, offset: number, byteCount: number): Promise<{
-    data: Uint8Array;
-    totalBytes: number;
-}>;
+/**
+ * Session-local PDF cache utilities.
+ * Each call to createPdfCache() creates an independent cache instance.
+ */
+export interface PdfCache {
+    /** Read a range of bytes from a PDF, using cache for servers without Range support */
+    readPdfRange(url: string, offset: number, byteCount: number): Promise<{
+        data: Uint8Array;
+        totalBytes: number;
+    }>;
+    /** Get current number of cached entries */
+    getCacheSize(): number;
+    /** Clear all cached entries and their timers */
+    clearCache(): void;
+}
+/**
+ * Creates a session-local PDF cache with automatic timeout-based cleanup.
+ *
+ * When a remote server returns HTTP 200 (full body) instead of 206 (partial),
+ * the full response is cached so subsequent chunk requests don't re-download.
+ *
+ * Entries are automatically cleared after:
+ * - CACHE_INACTIVITY_TIMEOUT_MS of no access (resets on each access)
+ * - CACHE_MAX_LIFETIME_MS from creation (absolute timeout)
+ */
+export declare function createPdfCache(): PdfCache;
 export declare function createServer(): McpServer;

package/dist/server.js

@@ -35764,6 +35764,9 @@ function ak(r, i, o, t, n) {
 var DEFAULT_PDF = "https://arxiv.org/pdf/1706.03762";
 var MAX_CHUNK_BYTES = 512 * 1024;
 var RESOURCE_URI = "ui://pdf-viewer/mcp-app.html";
+var CACHE_INACTIVITY_TIMEOUT_MS = 1e4;
+var CACHE_MAX_LIFETIME_MS = 60000;
+var CACHE_MAX_PDF_SIZE_BYTES = 50 * 1024 * 1024;
 var allowedRemoteOrigins = new Set([
   "https://agrirxiv.org",
   "https://arxiv.org",
@@ -35783,6 +35786,7 @@ var allowedRemoteOrigins = new Set([
   "https://zenodo.org"
 ]);
 var allowedLocalFiles = new Set;
+var allowedLocalDirs = new Set;
 var DIST_DIR = import.meta.filename.endsWith(".ts") ? path.join(import.meta.dirname, "dist") : import.meta.dirname;
 function isFileUrl(url2) {
   return url2.startsWith("file://");
@@ -35808,7 +35812,10 @@ function pathToFileUrl(filePath) {
 function validateUrl(url2) {
   if (isFileUrl(url2)) {
     const filePath = fileUrlToPath(url2);
-    if (!allowedLocalFiles.has(filePath)) {
+    const resolved = path.resolve(filePath);
+    const exactMatch = allowedLocalFiles.has(filePath);
+    const dirMatch = [...allowedLocalDirs].some((dir) => resolved === dir || resolved.startsWith(dir + path.sep));
+    if (!exactMatch && !dirMatch) {
       return {
         valid: false,
         error: `Local file not in allowed list: ${filePath}`
@@ -35830,62 +35837,174 @@ function validateUrl(url2) {
     return { valid: false, error: `Invalid URL: ${url2}` };
   }
 }
-async function readPdfRange(url2, offset, byteCount) {
-  const normalized = isArxivUrl(url2) ? normalizeArxivUrl(url2) : url2;
-  const clampedByteCount = Math.min(byteCount, MAX_CHUNK_BYTES);
-  if (isFileUrl(normalized)) {
-    const filePath = fileUrlToPath(normalized);
-    const stats = await fs.promises.stat(filePath);
-    const totalBytes2 = stats.size;
-    const start = Math.min(offset, totalBytes2);
-    const end = Math.min(start + clampedByteCount, totalBytes2);
-    if (start >= totalBytes2) {
-      return { data: new Uint8Array(0), totalBytes: totalBytes2 };
-    }
-    const buffer = Buffer.alloc(end - start);
-    const fd = await fs.promises.open(filePath, "r");
-    try {
-      await fd.read(buffer, 0, end - start, start);
-    } finally {
-      await fd.close();
+function createPdfCache() {
+  const cache = new Map;
+  function deleteCacheEntry(url2) {
+    const entry = cache.get(url2);
+    if (entry) {
+      clearTimeout(entry.inactivityTimer);
+      clearTimeout(entry.maxLifetimeTimer);
+      cache.delete(url2);
     }
-    return { data: new Uint8Array(buffer), totalBytes: totalBytes2 };
   }
-  const response = await fetch(normalized, {
-    headers: {
-      Range: `bytes=${offset}-${offset + clampedByteCount - 1}`
+  function getCacheEntry(url2) {
+    const entry = cache.get(url2);
+    if (!entry)
+      return;
+    clearTimeout(entry.inactivityTimer);
+    entry.inactivityTimer = setTimeout(() => {
+      deleteCacheEntry(url2);
+    }, CACHE_INACTIVITY_TIMEOUT_MS);
+    return entry.data;
+  }
+  function setCacheEntry(url2, data) {
+    deleteCacheEntry(url2);
+    const entry = {
+      data,
+      createdAt: Date.now(),
+      inactivityTimer: setTimeout(() => {
+        deleteCacheEntry(url2);
+      }, CACHE_INACTIVITY_TIMEOUT_MS),
+      maxLifetimeTimer: setTimeout(() => {
+        deleteCacheEntry(url2);
+      }, CACHE_MAX_LIFETIME_MS)
+    };
+    cache.set(url2, entry);
+  }
+  function sliceToChunk(fullData, offset, clampedByteCount) {
+    const totalBytes = fullData.length;
+    const start = Math.min(offset, totalBytes);
+    const end = Math.min(start + clampedByteCount, totalBytes);
+    return { data: fullData.slice(start, end), totalBytes };
+  }
+  async function readPdfRange(url2, offset, byteCount) {
+    const normalized = isArxivUrl(url2) ? normalizeArxivUrl(url2) : url2;
+    const clampedByteCount = Math.min(byteCount, MAX_CHUNK_BYTES);
+    if (isFileUrl(normalized)) {
+      const filePath = fileUrlToPath(normalized);
+      const stats = await fs.promises.stat(filePath);
+      const totalBytes2 = stats.size;
+      const start = Math.min(offset, totalBytes2);
+      const end = Math.min(start + clampedByteCount, totalBytes2);
+      if (start >= totalBytes2) {
+        return { data: new Uint8Array(0), totalBytes: totalBytes2 };
+      }
+      const buffer = Buffer.alloc(end - start);
+      const fd = await fs.promises.open(filePath, "r");
+      try {
+        await fd.read(buffer, 0, end - start, start);
+      } finally {
+        await fd.close();
+      }
+      return { data: new Uint8Array(buffer), totalBytes: totalBytes2 };
     }
-  });
-  if (!response.ok && response.status !== 206) {
-    throw new Error(`Range request failed: ${response.status} ${response.statusText}`);
+    const cached2 = getCacheEntry(normalized);
+    if (cached2) {
+      return sliceToChunk(cached2, offset, clampedByteCount);
+    }
+    let response = await fetch(normalized, {
+      headers: {
+        Range: `bytes=${offset}-${offset + clampedByteCount - 1}`
+      }
+    });
+    if (!response.ok && response.status !== 206) {
+      response = await fetch(normalized);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch PDF: ${response.status} ${response.statusText}`);
+      }
+    }
+    if (response.status === 200) {
+      const contentLength = response.headers.get("content-length");
+      if (contentLength) {
+        const declaredSize = parseInt(contentLength, 10);
+        if (declaredSize > CACHE_MAX_PDF_SIZE_BYTES) {
+          throw new Error(`PDF too large to cache: ${declaredSize} bytes exceeds ${CACHE_MAX_PDF_SIZE_BYTES} byte limit`);
+        }
+      }
+      const fullData = new Uint8Array(await response.arrayBuffer());
+      if (fullData.length > CACHE_MAX_PDF_SIZE_BYTES) {
+        throw new Error(`PDF too large to cache: ${fullData.length} bytes exceeds ${CACHE_MAX_PDF_SIZE_BYTES} byte limit`);
+      }
+      setCacheEntry(normalized, fullData);
+      return sliceToChunk(fullData, offset, clampedByteCount);
+    }
+    const contentRange = response.headers.get("content-range");
+    let totalBytes = 0;
+    if (contentRange) {
+      const match = contentRange.match(/bytes \d+-\d+\/(\d+)/);
+      if (match) {
+        totalBytes = parseInt(match[1], 10);
+      }
+    }
+    const data = new Uint8Array(await response.arrayBuffer());
+    return { data, totalBytes };
   }
-  const contentRange = response.headers.get("content-range");
-  let totalBytes = 0;
-  if (contentRange) {
-    const match = contentRange.match(/bytes \d+-\d+\/(\d+)/);
-    if (match) {
-      totalBytes = parseInt(match[1], 10);
+  return {
+    readPdfRange,
+    getCacheSize: () => cache.size,
+    clearCache: () => {
+      for (const url2 of [...cache.keys()]) {
+        deleteCacheEntry(url2);
+      }
     }
+  };
+}
+async function refreshRoots(server) {
+  if (!server.getClientCapabilities()?.roots)
+    return;
+  try {
+    const { roots } = await server.listRoots();
+    allowedLocalDirs.clear();
+    for (const root of roots) {
+      if (root.uri.startsWith("file://")) {
+        const dir = fileUrlToPath(root.uri);
+        const resolved = path.resolve(dir);
+        try {
+          if (fs.statSync(resolved).isDirectory()) {
+            allowedLocalDirs.add(resolved);
+            console.error(`[pdf-server] Root directory allowed: ${resolved}`);
+          }
+        } catch {}
+      }
+    }
+  } catch (err) {
+    console.error(`[pdf-server] Failed to list roots: ${err instanceof Error ? err.message : err}`);
   }
-  const data = new Uint8Array(await response.arrayBuffer());
-  return { data, totalBytes };
 }
 function createServer() {
   const server = new McpServer({ name: "PDF Server", version: "2.0.0" });
+  server.server.oninitialized = () => {
+    refreshRoots(server.server);
+  };
+  server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+    await refreshRoots(server.server);
+  });
+  const { readPdfRange } = createPdfCache();
   server.tool("list_pdfs", "List available PDFs that can be displayed", {}, async () => {
     const pdfs = [];
     for (const filePath of allowedLocalFiles) {
       pdfs.push({ url: pathToFileUrl(filePath), type: "local" });
     }
-    const text = pdfs.length > 0 ? `Available PDFs:
+    const parts = [];
+    if (pdfs.length > 0) {
+      parts.push(`Available PDFs:
 ${pdfs.map((p2) => `- ${p2.url} (${p2.type})`).join(`
+`)}`);
+    }
+    if (allowedLocalDirs.size > 0) {
+      parts.push(`Allowed local directories (from client roots):
+${[...allowedLocalDirs].map((d2) => `- ${d2}`).join(`
 `)}
-
-Remote PDFs from ${[...allowedRemoteOrigins].join(", ")} can also be loaded dynamically.` : `No local PDFs configured. Remote PDFs from ${[...allowedRemoteOrigins].join(", ")} can be loaded dynamically.`;
+Any PDF file under these directories can be displayed.`);
+    }
+    parts.push(`Remote PDFs from ${[...allowedRemoteOrigins].join(", ")} can also be loaded dynamically.`);
     return {
-      content: [{ type: "text", text }],
+      content: [{ type: "text", text: parts.join(`
+
+`) }],
       structuredContent: {
         localFiles: pdfs.filter((p2) => p2.type === "local").map((p2) => p2.url),
+        allowedDirectories: [...allowedLocalDirs],
         allowedOrigins: [...allowedRemoteOrigins]
       }
     };
@@ -35955,6 +36074,7 @@ Remote PDFs from ${[...allowedRemoteOrigins].join(", ")} can also be loaded dyna
 
 Accepts:
 - Local files explicitly added to the server (use list_pdfs to see available files)
+- Local files under directories provided by the client as MCP roots
 - Remote PDFs from: ${allowedDomains}`,
     inputSchema: {
       url: exports_external.string().default(DEFAULT_PDF).describe("PDF URL"),
@@ -35962,7 +36082,8 @@ Accepts:
     },
     outputSchema: exports_external.object({
       url: exports_external.string(),
-      initialPage: exports_external.number()
+      initialPage: exports_external.number(),
+      totalBytes: exports_external.number()
     }),
     _meta: { ui: { resourceUri: RESOURCE_URI } }
   }, async ({ url: url2, page }) => {
@@ -35974,11 +36095,13 @@ Accepts:
         isError: true
       };
     }
+    const { totalBytes } = await readPdfRange(normalized, 0, 1);
     return {
       content: [{ type: "text", text: `Displaying PDF: ${normalized}` }],
       structuredContent: {
         url: normalized,
-        initialPage: page
+        initialPage: page,
+        totalBytes
       },
       _meta: {
         viewUUID: randomUUID()
@@ -35997,16 +36120,20 @@ Accepts:
 }
 export {
   validateUrl,
-  readPdfRange,
   pathToFileUrl,
   normalizeArxivUrl,
   isFileUrl,
   isArxivUrl,
   fileUrlToPath,
   createServer,
+  createPdfCache,
   allowedRemoteOrigins,
   allowedLocalFiles,
+  allowedLocalDirs,
   RESOURCE_URI,
   MAX_CHUNK_BYTES,
-  DEFAULT_PDF
+  DEFAULT_PDF,
+  CACHE_MAX_PDF_SIZE_BYTES,
+  CACHE_MAX_LIFETIME_MS,
+  CACHE_INACTIVITY_TIMEOUT_MS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelcontextprotocol/server-pdf",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "MCP server for loading and extracting text from PDF files with chunked pagination and interactive viewer",
   "repository": {
@@ -18,7 +18,7 @@
     "watch": "cross-env INPUT=mcp-app.html vite build --watch",
     "serve": "bun --watch main.ts",
     "start": "cross-env NODE_ENV=development npm run build && npm run serve",
-    "dev": "cross-env NODE_ENV=development concurrently 'npm run watch' 'npm run serve'",
+    "dev": "cross-env NODE_ENV=development concurrently \"npm run watch\" \"npm run serve\"",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {