@sylphx/pdf-reader-mcp 1.1.0 → 1.3.0

package/dist/handlers/readPdf.js

@@ -1,7 +1,7 @@
 // PDF reading handler - orchestrates PDF processing workflow
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { buildWarnings, extractImages, extractMetadataAndPageCount, extractPageTexts, } from '../pdf/extractor.js';
+import { buildWarnings, extractMetadataAndPageCount, extractPageContent, } from '../pdf/extractor.js';
 import { loadPdfDocument } from '../pdf/loader.js';
 import { determinePagesToProcess, getTargetPages } from '../pdf/parser.js';
 import { readPdfArgsSchema } from '../schemas/readPdf.js';
@@ -28,9 +28,23 @@ const processSingleSource = async (source, options) => {
         if (warnings.length > 0) {
             output.warnings = warnings;
         }
-        // Extract text if needed
+        // Extract content with ordering preserved
         if (pagesToProcess.length > 0) {
-            const extractedPageTexts = await extractPageTexts(pdfDocument, pagesToProcess, sourceDescription);
+            // Use new extractPageContent to preserve Y-coordinate ordering
+            const pageContents = await Promise.all(pagesToProcess.map((pageNum) => extractPageContent(pdfDocument, pageNum, options.includeImages, sourceDescription)));
+            // Store page contents for ordered retrieval
+            output.page_contents = pageContents.map((items, idx) => ({
+                page: pagesToProcess[idx],
+                items,
+            }));
+            // For backward compatibility, also provide text-only outputs
+            const extractedPageTexts = pageContents.map((items, idx) => ({
+                page: pagesToProcess[idx],
+                text: items
+                    .filter((item) => item.type === 'text')
+                    .map((item) => item.textContent)
+                    .join(''),
+            }));
             if (targetPages) {
                 // Specific pages requested
                 output.page_texts = extractedPageTexts;
@@ -39,12 +53,15 @@ const processSingleSource = async (source, options) => {
                 // Full text requested
                 output.full_text = extractedPageTexts.map((p) => p.text).join('\n\n');
             }
-        }
-        // Extract images if needed
-        if (options.includeImages && pagesToProcess.length > 0) {
-            const extractedImages = await extractImages(pdfDocument, pagesToProcess);
-            if (extractedImages.length > 0) {
-                output.images = extractedImages;
+            // Extract image metadata for JSON response
+            if (options.includeImages) {
+                const extractedImages = pageContents
+                    .flatMap((items) => items.filter((item) => item.type === 'image' && item.imageData))
+                    .map((item) => item.imageData)
+                    .filter((img) => img !== undefined);
+                if (extractedImages.length > 0) {
+                    output.images = extractedImages;
+                }
             }
         }
         individualResult = { ...individualResult, data: output, success: true };
@@ -53,7 +70,7 @@ const processSingleSource = async (source, options) => {
         let errorMessage = `Failed to process PDF from ${sourceDescription}.`;
         if (error instanceof McpError) {
             errorMessage = error.message;
-        }
+        } /* c8 ignore next */
         else if (error instanceof Error) {
             errorMessage += ` Reason: ${error.message}`;
         }
@@ -76,9 +93,11 @@ export const handleReadPdfFunc = async (args) => {
     }
     catch (error) {
         if (error instanceof z.ZodError) {
-            throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.errors.map((e) => `${e.path.join('.')} (${e.message})`).join(', ')}`);
+            throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.issues.map((e) => `${e.path.join('.')} (${e.message})`).join(', ')}`);
         }
+        /* c8 ignore next */
         const message = error instanceof Error ? error.message : String(error);
+        /* c8 ignore next */
         throw new McpError(ErrorCode.InvalidParams, `Argument validation failed: ${message}`);
     }
     const { sources, include_full_text, include_metadata, include_page_count, include_images } = parsedArgs;
@@ -91,19 +110,22 @@ export const handleReadPdfFunc = async (args) => {
     })));
     // Build content parts - start with structured JSON for backward compatibility
     const content = [];
-    // Strip image data from JSON to keep it manageable
+    // Strip image data and page_contents from JSON to keep it manageable
     const resultsForJson = results.map((result) => {
-        if (result.data?.images) {
-            const { images, ...dataWithoutImages } = result.data;
+        if (result.data) {
+            const { images, page_contents, ...dataWithoutBinaryContent } = result.data;
             // Include image count and metadata in JSON, but not the base64 data
-            const imageInfo = images.map((img) => ({
-                page: img.page,
-                index: img.index,
-                width: img.width,
-                height: img.height,
-                format: img.format,
-            }));
-            return { ...result, data: { ...dataWithoutImages, image_info: imageInfo } };
+            if (images) {
+                const imageInfo = images.map((img) => ({
+                    page: img.page,
+                    index: img.index,
+                    width: img.width,
+                    height: img.height,
+                    format: img.format,
+                }));
+                return { ...result, data: { ...dataWithoutBinaryContent, image_info: imageInfo } };
+            }
+            return { ...result, data: dataWithoutBinaryContent };
         }
         return result;
     });
@@ -112,40 +134,27 @@ export const handleReadPdfFunc = async (args) => {
         type: 'text',
         text: JSON.stringify({ results: resultsForJson }, null, 2),
     });
-    // Add page content in order: text then images for each page
-    if (include_images) {
-        for (const result of results) {
-            if (!result.success || !result.data)
-                continue;
-            // Handle page_texts (specific pages requested)
-            if (result.data.page_texts) {
-                for (const pageText of result.data.page_texts) {
-                    // Add images for this page (if any) right after page text
-                    if (result.data.images) {
-                        const pageImages = result.data.images.filter((img) => img.page === pageText.page);
-                        for (const image of pageImages) {
-                            content.push({
-                                type: 'image',
-                                data: image.data,
-                                mimeType: image.format === 'rgba' ? 'image/png' : 'image/jpeg',
-                            });
-                        }
-                    }
+    // Add page content in exact Y-coordinate order
+    for (const result of results) {
+        if (!result.success || !result.data?.page_contents)
+            continue;
+        // Process each page's content items in order
+        for (const pageContent of result.data.page_contents) {
+            for (const item of pageContent.items) {
+                if (item.type === 'text' && item.textContent) {
+                    // Add text content part
+                    content.push({
+                        type: 'text',
+                        text: item.textContent,
+                    });
                 }
-            }
-            // Handle full_text mode - add all images by page order
-            if (result.data.full_text && result.data.images) {
-                // Group images by page and add in order
-                const pageNumbers = [...new Set(result.data.images.map((img) => img.page))].sort((a, b) => a - b);
-                for (const pageNum of pageNumbers) {
-                    const pageImages = result.data.images.filter((img) => img.page === pageNum);
-                    for (const image of pageImages) {
-                        content.push({
-                            type: 'image',
-                            data: image.data,
-                            mimeType: image.format === 'rgba' ? 'image/png' : 'image/jpeg',
-                        });
-                    }
+                else if (item.type === 'image' && item.imageData) {
+                    // Add image content part (all images are now encoded as PNG)
+                    content.push({
+                        type: 'image',
+                        data: item.imageData.data,
+                        mimeType: 'image/png',
+                    });
                 }
             }
         }

package/dist/index.js

@@ -11,7 +11,7 @@ import { allToolDefinitions } from './handlers/index.js';
 // --- Server Setup ---
 const server = new Server({
     name: 'pdf-reader-mcp',
-    version: '1.1.0',
+    version: '1.3.0',
     description: 'MCP Server for reading PDF files and extracting text, metadata, images, and page information.',
 }, {
     capabilities: { tools: {} },

package/dist/pdf/extractor.js

@@ -1,5 +1,42 @@
 // PDF text and metadata extraction utilities
 import { OPS } from 'pdfjs-dist/legacy/build/pdf.mjs';
+import { PNG } from 'pngjs';
+/**
+ * Encode raw pixel data to PNG format
+ */
+const encodePixelsToPNG = (pixelData, width, height, channels) => {
+    const png = new PNG({ width, height });
+    // Convert pixel data to RGBA format expected by pngjs
+    if (channels === 4) {
+        // Already RGBA
+        png.data = Buffer.from(pixelData);
+    }
+    else if (channels === 3) {
+        // RGB -> RGBA (add alpha channel)
+        for (let i = 0; i < width * height; i++) {
+            const srcIdx = i * 3;
+            const dstIdx = i * 4;
+            png.data[dstIdx] = pixelData[srcIdx] ?? 0; // R
+            png.data[dstIdx + 1] = pixelData[srcIdx + 1] ?? 0; // G
+            png.data[dstIdx + 2] = pixelData[srcIdx + 2] ?? 0; // B
+            png.data[dstIdx + 3] = 255; // A (fully opaque)
+        }
+    }
+    else if (channels === 1) {
+        // Grayscale -> RGBA
+        for (let i = 0; i < width * height; i++) {
+            const gray = pixelData[i] ?? 0;
+            const dstIdx = i * 4;
+            png.data[dstIdx] = gray; // R
+            png.data[dstIdx + 1] = gray; // G
+            png.data[dstIdx + 2] = gray; // B
+            png.data[dstIdx + 3] = 255; // A
+        }
+    }
+    // Encode to PNG and convert to base64
+    const pngBuffer = PNG.sync.write(png);
+    return pngBuffer.toString('base64');
+};
 /**
  * Extract metadata and page count from a PDF document
  */
@@ -68,6 +105,7 @@ export const extractPageTexts = async (pdfDocument, pagesToProcess, sourceDescri
  */
 const extractImagesFromPage = async (page, pageNum) => {
     const images = [];
+    /* c8 ignore next */
     try {
         const operatorList = await page.getOperatorList();
         // Find all image painting operations
@@ -78,7 +116,7 @@ const extractImagesFromPage = async (page, pageNum) => {
                 imageIndices.push(i);
             }
         }
-        // Extract each image using Promise-based approach
+        // Extract each image - try sync first, then async if needed
         const imagePromises = imageIndices.map((imgIndex, arrayIndex) => new Promise((resolve) => {
             const argsArray = operatorList.argsArray[imgIndex];
             if (!argsArray || argsArray.length === 0) {
@@ -86,30 +124,75 @@ const extractImagesFromPage = async (page, pageNum) => {
                 return;
             }
             const imageName = argsArray[0];
-            // Use callback-based get() as images may not be resolved yet
-            page.objs.get(imageName, (imageData) => {
+            // Helper to process image data
+            const processImageData = (imageData) => {
                 if (!imageData || typeof imageData !== 'object') {
-                    resolve(null);
-                    return;
+                    return null;
                 }
                 const img = imageData;
                 if (!img.data || !img.width || !img.height) {
-                    resolve(null);
-                    return;
+                    return null;
                 }
-                // Determine image format based on kind
-                // kind === 1 = grayscale, 2 = RGB, 3 = RGBA
+                // Determine number of channels based on kind
+                // kind === 1 = grayscale (1 channel), 2 = RGB (3 channels), 3 = RGBA (4 channels)
+                const channels = img.kind === 1 ? 1 : img.kind === 3 ? 4 : 3;
                 const format = img.kind === 1 ? 'grayscale' : img.kind === 3 ? 'rgba' : 'rgb';
-                // Convert Uint8Array to base64
-                const base64 = Buffer.from(img.data).toString('base64');
-                resolve({
+                // Encode raw pixel data to PNG format
+                const pngBase64 = encodePixelsToPNG(img.data, img.width, img.height, channels);
+                return {
                     page: pageNum,
                     index: arrayIndex,
                     width: img.width,
                     height: img.height,
                     format,
-                    data: base64,
-                });
+                    data: pngBase64,
+                };
+            };
+            // Try to get from commonObjs first if it starts with 'g_'
+            if (imageName.startsWith('g_')) {
+                try {
+                    const imageData = page.commonObjs.get(imageName);
+                    if (imageData) {
+                        const result = processImageData(imageData);
+                        resolve(result);
+                        return;
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.warn(`[PDF Reader MCP] Error getting image from commonObjs ${imageName}: ${message}`);
+                }
+            }
+            // Try synchronous get first - if image is already loaded
+            try {
+                const imageData = page.objs.get(imageName);
+                if (imageData !== undefined) {
+                    const result = processImageData(imageData);
+                    resolve(result);
+                    return;
+                }
+            }
+            catch (error) {
+                // Synchronous get failed or not supported, fall through to async
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[PDF Reader MCP] Sync image get failed for ${imageName}, trying async: ${message}`);
+            }
+            // Fallback to async callback-based get with timeout
+            let resolved = false;
+            const timeout = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    console.warn(`[PDF Reader MCP] Image extraction timeout for ${imageName} on page ${String(pageNum)}`);
+                    resolve(null);
+                }
+            }, 10000); // 10 second timeout as a safety net
+            page.objs.get(imageName, (imageData) => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    const result = processImageData(imageData);
+                    resolve(result);
+                }
             });
         }));
         const resolvedImages = await Promise.all(imagePromises);
@@ -151,3 +234,161 @@ export const buildWarnings = (invalidPages, totalPages) => {
         `Requested page numbers ${invalidPages.join(', ')} exceed total pages (${String(totalPages)}).`,
     ];
 };
+/**
+ * Extract all content (text and images) from a single page with Y-coordinate ordering
+ */
+export const extractPageContent = async (pdfDocument, pageNum, includeImages, sourceDescription) => {
+    const contentItems = [];
+    try {
+        const page = await pdfDocument.getPage(pageNum);
+        // Extract text content with Y-coordinates
+        const textContent = await page.getTextContent();
+        // Group text items by Y-coordinate (items on same line have similar Y values)
+        const textByY = new Map();
+        for (const item of textContent.items) {
+            const textItem = item;
+            // transform[5] is the Y coordinate
+            const yCoord = textItem.transform[5];
+            if (yCoord === undefined)
+                continue;
+            const y = Math.round(yCoord);
+            if (!textByY.has(y)) {
+                textByY.set(y, []);
+            }
+            textByY.get(y)?.push(textItem.str);
+        }
+        // Convert grouped text to content items
+        for (const [y, textParts] of textByY.entries()) {
+            const textContent = textParts.join('');
+            if (textContent.trim()) {
+                contentItems.push({
+                    type: 'text',
+                    yPosition: y,
+                    textContent,
+                });
+            }
+        }
+        // Extract images with Y-coordinates if requested
+        if (includeImages) {
+            const operatorList = await page.getOperatorList();
+            // Find all image painting operations
+            const imageIndices = [];
+            for (let i = 0; i < operatorList.fnArray.length; i++) {
+                const op = operatorList.fnArray[i];
+                if (op === OPS.paintImageXObject || op === OPS.paintXObject) {
+                    imageIndices.push(i);
+                }
+            }
+            // Extract each image with its Y-coordinate - try sync first, then async if needed
+            const imagePromises = imageIndices.map((imgIndex, arrayIndex) => new Promise((resolve) => {
+                const argsArray = operatorList.argsArray[imgIndex];
+                if (!argsArray || argsArray.length === 0) {
+                    resolve(null);
+                    return;
+                }
+                const imageName = argsArray[0];
+                // Get transform matrix from the args (if available)
+                let yPosition = 0;
+                if (argsArray.length > 1 && Array.isArray(argsArray[1])) {
+                    const transform = argsArray[1];
+                    const yCoord = transform[5];
+                    if (yCoord !== undefined) {
+                        yPosition = Math.round(yCoord);
+                    }
+                }
+                // Helper to process image data
+                const processImageData = (imageData) => {
+                    if (!imageData || typeof imageData !== 'object') {
+                        return null;
+                    }
+                    const img = imageData;
+                    if (!img.data || !img.width || !img.height) {
+                        return null;
+                    }
+                    // Determine number of channels based on kind
+                    const channels = img.kind === 1 ? 1 : img.kind === 3 ? 4 : 3;
+                    const format = img.kind === 1 ? 'grayscale' : img.kind === 3 ? 'rgba' : 'rgb';
+                    // Encode raw pixel data to PNG format
+                    const pngBase64 = encodePixelsToPNG(img.data, img.width, img.height, channels);
+                    return {
+                        type: 'image',
+                        yPosition,
+                        imageData: {
+                            page: pageNum,
+                            index: arrayIndex,
+                            width: img.width,
+                            height: img.height,
+                            format,
+                            data: pngBase64,
+                        },
+                    };
+                };
+                // Try to get from commonObjs first if it starts with 'g_'
+                if (imageName.startsWith('g_')) {
+                    try {
+                        const imageData = page.commonObjs.get(imageName);
+                        if (imageData) {
+                            const result = processImageData(imageData);
+                            resolve(result);
+                            return;
+                        }
+                        /* c8 ignore next */
+                    }
+                    catch (error) {
+                        /* c8 ignore next */ const message = error instanceof Error ? error.message : String(error);
+                        /* c8 ignore next */ console.warn(
+                        /* c8 ignore next */ `[PDF Reader MCP] Error getting image from commonObjs ${imageName}: ${message}`
+                        /* c8 ignore next */
+                        );
+                    }
+                }
+                // Try synchronous get first - if image is already loaded
+                try {
+                    const imageData = page.objs.get(imageName);
+                    if (imageData !== undefined) {
+                        const result = processImageData(imageData);
+                        resolve(result);
+                        return;
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    console.warn(`[PDF Reader MCP] Sync image get failed for ${imageName}, trying async: ${message}`);
+                }
+                // Fallback to async callback-based get with timeout
+                let resolved = false;
+                const timeout = setTimeout(() => {
+                    if (!resolved) {
+                        resolved = true;
+                        console.warn(`[PDF Reader MCP] Image extraction timeout for ${imageName} on page ${String(pageNum)}`);
+                        resolve(null);
+                    }
+                }, 10000); // 10 second timeout as a safety net
+                page.objs.get(imageName, (imageData) => {
+                    if (!resolved) {
+                        resolved = true;
+                        clearTimeout(timeout);
+                        const result = processImageData(imageData);
+                        resolve(result);
+                    }
+                });
+            }));
+            const resolvedImages = await Promise.all(imagePromises);
+            contentItems.push(...resolvedImages.filter((item) => item !== null));
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[PDF Reader MCP] Error extracting page content for page ${String(pageNum)} in ${sourceDescription}: ${message}`);
+        // Return error message as text content
+        return [
+            {
+                type: 'text',
+                yPosition: 0,
+                textContent: `Error processing page: ${message}`,
+            },
+        ];
+    }
+    // Sort by Y-position (descending = top to bottom in PDF coordinates)
+    return contentItems.sort((a, b) => b.yPosition - a.yPosition);
+};

package/dist/pdf/parser.js

@@ -7,10 +7,9 @@ const MAX_RANGE_SIZE = 10000; // Prevent infinite loops for open ranges
 const parseRangePart = (part, pages) => {
     const trimmedPart = part.trim();
     if (trimmedPart.includes('-')) {
-        const [startStr, endStr] = trimmedPart.split('-');
-        if (startStr === undefined) {
-            throw new Error(`Invalid page range format: ${trimmedPart}`);
-        }
+        const splitResult = trimmedPart.split('-');
+        const startStr = splitResult[0] || '';
+        const endStr = splitResult[1];
         const start = parseInt(startStr, 10);
         const end = endStr === '' || endStr === undefined ? Infinity : parseInt(endStr, 10);
         if (Number.isNaN(start) || Number.isNaN(end) || start <= 0 || start > end) {
@@ -43,6 +42,9 @@ export const parsePageRanges = (ranges) => {
     for (const part of parts) {
         parseRangePart(part, pages);
     }
+    // This should never happen as parseRangePart would have thrown an error
+    // if no valid pages were found, but we keep this as a safety check
+    /* c8 ignore next */
     if (pages.size === 0) {
         throw new Error('Page range string resulted in zero valid pages.');
     }

package/dist/schemas/readPdf.js

@@ -14,7 +14,11 @@ export const pageSpecifierSchema = z.union([
 // Schema for a single PDF source (path or URL)
 export const pdfSourceSchema = z
     .object({
-    path: z.string().min(1).optional().describe('Relative path to the local PDF file.'),
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Path to the local PDF file (absolute or relative to cwd).'),
     url: z.string().url().optional().describe('URL of the PDF file.'),
     pages: pageSpecifierSchema
         .optional()

package/dist/utils/pathUtils.js

@@ -6,10 +6,9 @@ import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 export const PROJECT_ROOT = process.cwd();
 console.info(`[Filesystem MCP - pathUtils] Project Root determined from CWD: ${PROJECT_ROOT}`); // Use info instead of log
 /**
- * Resolves a user-provided relative path against the project root,
- * ensuring it stays within the project boundaries.
- * Throws McpError on invalid input, absolute paths, or path traversal.
- * @param userPath The relative path provided by the user.
+ * Resolves a user-provided path, accepting both absolute and relative paths.
+ * Relative paths are resolved against the current working directory (PROJECT_ROOT).
+ * @param userPath The path provided by the user (absolute or relative).
  * @returns The resolved absolute path.
  */
 export const resolvePath = (userPath) => {
@@ -17,14 +16,10 @@ export const resolvePath = (userPath) => {
         throw new McpError(ErrorCode.InvalidParams, 'Path must be a string.');
     }
     const normalizedUserPath = path.normalize(userPath);
+    // If absolute path, return it normalized
     if (path.isAbsolute(normalizedUserPath)) {
-        throw new McpError(ErrorCode.InvalidParams, 'Absolute paths are not allowed.');
+        return normalizedUserPath;
     }
-    // Resolve against the calculated PROJECT_ROOT
-    const resolved = path.resolve(PROJECT_ROOT, normalizedUserPath);
-    // Security check: Ensure the resolved path is still within the project root
-    if (!resolved.startsWith(PROJECT_ROOT)) {
-        throw new McpError(ErrorCode.InvalidRequest, 'Path traversal detected. Access denied.');
-    }
-    return resolved;
+    // If relative path, resolve against the PROJECT_ROOT (cwd)
+    return path.resolve(PROJECT_ROOT, normalizedUserPath);
 };