@sylphx/pdf-reader-mcp 1.0.0 → 1.2.0

package/README.md

@@ -4,7 +4,6 @@
 [![CI/CD Pipeline](https://github.com/sylphlab/pdf-reader-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sylphlab/pdf-reader-mcp/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/sylphlab/pdf-reader-mcp/graph/badge.svg?token=VYRQFB40UN)](https://codecov.io/gh/sylphlab/pdf-reader-mcp)
 [![npm version](https://badge.fury.io/js/%40sylphlab%2Fpdf-reader-mcp.svg)](https://badge.fury.io/js/%40sylphlab%2Fpdf-reader-mcp)
-[![Docker Pulls](https://img.shields.io/docker/pulls/sylphlab/pdf-reader-mcp.svg)](https://hub.docker.com/r/sylphlab/pdf-reader-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![smithery badge](https://smithery.ai/badge/@sylphxltd/pdf-reader-mcp)](https://smithery.ai/server/@sylphxltd/pdf-reader-mcp)
 
@@ -17,13 +16,14 @@
 ## ✨ Features
 
 - 📄 **Extract text content** from PDF files (full document or specific pages)
+- 🖼️ **Extract embedded images** from PDF pages as base64-encoded data
 - 📊 **Get metadata** (author, title, creation date, etc.)
 - 🔢 **Count pages** in PDF documents
 - 🌐 **Support for both local files and URLs**
 - 🛡️ **Secure** - Confines file access to project root directory
-- ⚡ **Fast** - Powered by PDF.js with optimized performance
+- ⚡ **Fast** - Parallel processing for maximum performance
 - 🔄 **Batch processing** - Handle multiple PDFs in a single request
-- 📦 **Multiple deployment options** - npm, Docker, or Smithery
+- 📦 **Multiple deployment options** - npm or Smithery
 
 ## 🆕 Recent Updates (October 2025)
 
@@ -32,8 +32,9 @@
 - ✅ **Improved metadata extraction**: Robust fallback handling for PDF.js compatibility
 - ✅ **Updated dependencies**: All packages updated to latest versions
 - ✅ **Migrated to Biome**: 50x faster linting and formatting with unified tooling
-- ✅ **Added Docker support**: Easy deployment with containerization
-- ✅ **All tests passing**: 31/31 tests with comprehensive coverage
+- ✅ **Added image extraction**: Extract embedded images from PDF pages
+- ✅ **Performance optimization**: Parallel page processing for 5-10x speedup
+- ✅ **Deep refactoring**: Modular architecture with 98.9% test coverage (90 tests)
 
 ## 📦 Installation
 
@@ -70,35 +71,7 @@ Configure your MCP client (e.g., Claude Desktop, Cursor):
 
 **Important:** Make sure your MCP client sets the correct working directory (`cwd`) to your project root.
 
-### Option 3: Using Docker
-
-Pull the image:
-
-```bash
-docker pull sylphx/pdf-reader-mcp:latest
-```
-
-Configure your MCP client:
-
-```json
-{
-  "mcpServers": {
-    "pdf-reader-mcp": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "-v",
-        "/path/to/your/project:/app",
-        "sylphx/pdf-reader-mcp:latest"
-      ]
-    }
-  }
-}
-```
-
-### Option 4: Local Development Build
+### Option 3: Local Development Build
 
 ```bash
 git clone https://github.com/sylphlab/pdf-reader-mcp.git
@@ -164,6 +137,28 @@ Once configured, your AI agent can read PDFs using the `read_pdf` tool:
 }
 ```
 
+### Example 5: Extract images from PDF
+
+```json
+{
+  "sources": [
+    {
+      "path": "presentation.pdf",
+      "pages": [1, 2, 3]
+    }
+  ],
+  "include_images": true,
+  "include_full_text": true
+}
+```
+
+**Response includes**:
+- Text content from each page
+- Embedded images as base64-encoded data with metadata (width, height, format)
+- Each image includes page number and index
+
+**Note**: Image extraction works best with JPEG and PNG images. Large PDFs with many images may produce large responses.
+
 ## 📖 Usage Guide
 
 ### Page Specification
@@ -192,6 +187,45 @@ For large PDF files (>20 MB), extract specific pages instead of the full documen
 
 This prevents hitting AI model context limits and improves performance.
 
+### Image Extraction
+
+Extract embedded images from PDF pages as base64-encoded data:
+
+```json
+{
+  "sources": [{ "path": "document.pdf" }],
+  "include_images": true
+}
+```
+
+**Image data format**:
+```json
+{
+  "images": [
+    {
+      "page": 1,
+      "index": 0,
+      "width": 800,
+      "height": 600,
+      "format": "rgb",
+      "data": "base64-encoded-image-data..."
+    }
+  ]
+}
+```
+
+**Supported formats**:
+- ✅ **RGB** - Standard color images (most common)
+- ✅ **RGBA** - Images with transparency
+- ✅ **Grayscale** - Black and white images
+- ✅ Works with JPEG, PNG, and other embedded formats
+
+**Important considerations**:
+- 🔸 Image extraction increases response size significantly
+- 🔸 Useful for AI models with vision capabilities
+- 🔸 Set `include_images: false` (default) to extract text only
+- 🔸 Combine with `pages` parameter to limit extraction scope
+
 ### Security: Relative Paths Only
 
 **Important:** The server only accepts **relative paths** for security reasons. Absolute paths are blocked to prevent unauthorized file system access.
@@ -360,12 +394,13 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 
 ## 🗺️ Roadmap
 
-- [ ] Image extraction from PDFs
+- [x] ~~Image extraction from PDFs~~ ✅ Completed (v1.0.0)
+- [x] ~~Performance optimizations for parallel processing~~ ✅ Completed (v1.0.0)
 - [ ] Annotation extraction support
 - [ ] OCR integration for scanned PDFs
 - [ ] Streaming support for very large files
 - [ ] Enhanced caching mechanisms
-- [ ] Performance optimizations for large batches
+- [ ] PDF form field extraction
 
 ## 🤝 Support & Community
 

package/dist/handlers/readPdf.js

@@ -1,299 +1,75 @@
-import fs from 'node:fs/promises';
+// PDF reading handler - orchestrates PDF processing workflow
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import * as pdfjsLib from 'pdfjs-dist/legacy/build/pdf.mjs';
 import { z } from 'zod';
-import { resolvePath } from '../utils/pathUtils.js';
-// Helper to parse page range strings (e.g., "1-3,5,7-")
-// Helper to parse a single range part (e.g., "1-3", "5", "7-")
-const parseRangePart = (part, pages) => {
-    const trimmedPart = part.trim();
-    if (trimmedPart.includes('-')) {
-        const [startStr, endStr] = trimmedPart.split('-');
-        if (startStr === undefined) {
-            // Basic check
-            throw new Error(`Invalid page range format: ${trimmedPart}`);
-        }
-        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) {
-            throw new Error(`Invalid page range values: ${trimmedPart}`);
-        }
-        // Add a reasonable upper limit to prevent infinite loops for open ranges
-        const practicalEnd = Math.min(end, start + 10000); // Limit range parsing depth
-        for (let i = start; i <= practicalEnd; i++) {
-            pages.add(i);
-        }
-        if (end === Infinity && practicalEnd === start + 10000) {
-            console.warn(`[PDF Reader MCP] Open-ended range starting at ${String(start)} was truncated at page ${String(practicalEnd)} during parsing.`);
-        }
-    }
-    else {
-        const page = parseInt(trimmedPart, 10);
-        if (Number.isNaN(page) || page <= 0) {
-            throw new Error(`Invalid page number: ${trimmedPart}`);
-        }
-        pages.add(page);
-    }
-};
-// Parses the complete page range string (e.g., "1-3,5,7-")
-const parsePageRanges = (ranges) => {
-    const pages = new Set();
-    const parts = ranges.split(',');
-    for (const part of parts) {
-        parseRangePart(part, pages); // Delegate parsing of each part
-    }
-    if (pages.size === 0) {
-        throw new Error('Page range string resulted in zero valid pages.');
-    }
-    return Array.from(pages).sort((a, b) => a - b);
-};
-// --- Zod Schemas ---
-const pageSpecifierSchema = z.union([
-    z
-        .array(z.number().int().min(1))
-        .min(1), // Array of integers with minimum value 1 (pages are 1-based)
-    z
-        .string()
-        .min(1)
-        .refine((val) => /^[0-9,-]+$/.test(val.replace(/\s/g, '')), {
-        // Allow spaces but test without them
-        message: 'Page string must contain only numbers, commas, and hyphens.',
-    }),
-]);
-const PdfSourceSchema = z
-    .object({
-    path: z.string().min(1).optional().describe('Relative path to the local PDF file.'),
-    url: z.string().url().optional().describe('URL of the PDF file.'),
-    pages: pageSpecifierSchema
-        .optional()
-        .describe("Extract text only from specific pages (1-based) or ranges for *this specific source*. If provided, 'include_full_text' for the entire request is ignored for this source."),
-})
-    .strict()
-    .refine((data) => !!(data.path && !data.url) || !!(!data.path && data.url), {
-    // Use boolean coercion instead of || for truthiness check if needed, though refine expects boolean
-    message: "Each source must have either 'path' or 'url', but not both.",
-});
-const ReadPdfArgsSchema = z
-    .object({
-    sources: z
-        .array(PdfSourceSchema)
-        .min(1)
-        .describe('An array of PDF sources to process, each can optionally specify pages.'),
-    include_full_text: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe("Include the full text content of each PDF (only if 'pages' is not specified for that source)."),
-    include_metadata: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe('Include metadata and info objects for each PDF.'),
-    include_page_count: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe('Include the total number of pages for each PDF.'),
-})
-    .strict();
-// --- Helper Functions ---
-// Parses the page specification for a single source
-const getTargetPages = (sourcePages, sourceDescription) => {
-    if (!sourcePages) {
-        return undefined;
-    }
-    try {
-        let targetPages;
-        if (typeof sourcePages === 'string') {
-            targetPages = parsePageRanges(sourcePages);
-        }
-        else {
-            // Ensure array elements are positive integers
-            if (sourcePages.some((p) => !Number.isInteger(p) || p <= 0)) {
-                throw new Error('Page numbers in array must be positive integers.');
-            }
-            targetPages = [...new Set(sourcePages)].sort((a, b) => a - b);
-        }
-        if (targetPages.length === 0) {
-            // Check after potential Set deduplication
-            throw new Error('Page specification resulted in an empty set of pages.');
-        }
-        return targetPages;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        // Throw McpError for invalid page specs caught during parsing
-        throw new McpError(ErrorCode.InvalidParams, `Invalid page specification for source ${sourceDescription}: ${message}`);
-    }
-};
-// Loads the PDF document from path or URL
-const loadPdfDocument = async (source, // Explicitly allow undefined
-sourceDescription) => {
-    let pdfDataSource;
-    try {
-        if (source.path) {
-            const safePath = resolvePath(source.path); // resolvePath handles security checks
-            const buffer = await fs.readFile(safePath);
-            pdfDataSource = new Uint8Array(buffer); // Convert Buffer to Uint8Array
-        }
-        else if (source.url) {
-            pdfDataSource = { url: source.url };
-        }
-        else {
-            // This case should be caught by Zod, but added for robustness
-            throw new McpError(ErrorCode.InvalidParams, `Source ${sourceDescription} missing 'path' or 'url'.`);
-        }
-    }
-    catch (err) {
-        // Handle errors during path resolution or file reading
-        let errorMessage; // Declare errorMessage here
-        const message = err instanceof Error ? err.message : String(err);
-        const errorCode = ErrorCode.InvalidRequest; // Default error code
-        if (typeof err === 'object' &&
-            err !== null &&
-            'code' in err &&
-            err.code === 'ENOENT' &&
-            source.path) {
-            // Specific handling for file not found
-            errorMessage = `File not found at '${source.path}'.`;
-            // Optionally keep errorCode as InvalidRequest or change if needed
-        }
-        else {
-            // Generic error for other file prep issues or resolvePath errors
-            errorMessage = `Failed to prepare PDF source ${sourceDescription}. Reason: ${message}`;
-        }
-        throw new McpError(errorCode, errorMessage, { cause: err instanceof Error ? err : undefined });
-    }
-    const loadingTask = pdfjsLib.getDocument(pdfDataSource);
-    try {
-        return await loadingTask.promise;
-    }
-    catch (err) {
-        console.error(`[PDF Reader MCP] PDF.js loading error for ${sourceDescription}:`, err);
-        const message = err instanceof Error ? err.message : String(err);
-        // Use ?? for default message
-        throw new McpError(ErrorCode.InvalidRequest, `Failed to load PDF document from ${sourceDescription}. Reason: ${message || 'Unknown loading error'}`, // Revert to || as message is likely always string here
-        { cause: err instanceof Error ? err : undefined });
-    }
-};
-// Extracts metadata and page count
-const extractMetadataAndPageCount = async (pdfDocument, includeMetadata, includePageCount) => {
-    const output = {};
-    if (includePageCount) {
-        output.num_pages = pdfDocument.numPages;
-    }
-    if (includeMetadata) {
-        try {
-            const pdfMetadata = await pdfDocument.getMetadata();
-            const infoData = pdfMetadata.info;
-            if (infoData !== undefined) {
-                output.info = infoData;
-            }
-            const metadataObj = pdfMetadata.metadata;
-            // Convert the metadata object to a plain object by extracting all properties
-            // Check if it has a getAll method (as used in tests)
-            if (typeof metadataObj.getAll === 'function') {
-                output.metadata = metadataObj.getAll();
-            }
-            else {
-                // For real PDF.js metadata, convert to plain object
-                const metadataRecord = {};
-                // Extract enumerable properties
-                for (const key in metadataObj) {
-                    if (Object.hasOwn(metadataObj, key)) {
-                        metadataRecord[key] = metadataObj[key];
-                    }
-                }
-                output.metadata = metadataRecord;
-            }
-        }
-        catch (metaError) {
-            console.warn(`[PDF Reader MCP] Error extracting metadata: ${metaError instanceof Error ? metaError.message : String(metaError)}`);
-            // Optionally add a warning to the result if metadata extraction fails partially
-        }
-    }
-    return output;
-};
-// Extracts text from specified pages
-const extractPageTexts = async (pdfDocument, pagesToProcess, sourceDescription) => {
-    const extractedPageTexts = [];
-    for (const pageNum of pagesToProcess) {
-        let pageText = '';
-        try {
-            const page = await pdfDocument.getPage(pageNum);
-            const textContent = await page.getTextContent();
-            pageText = textContent.items
-                .map((item) => item.str) // Type assertion
-                .join('');
-        }
-        catch (pageError) {
-            const message = pageError instanceof Error ? pageError.message : String(pageError);
-            console.warn(`[PDF Reader MCP] Error getting text content for page ${String(pageNum)} in ${sourceDescription}: ${message}` // Explicit string conversion
-            );
-            pageText = `Error processing page: ${message}`; // Include error in text
-        }
-        extractedPageTexts.push({ page: pageNum, text: pageText });
-    }
-    // Sorting is likely unnecessary if pagesToProcess was sorted, but keep for safety
-    extractedPageTexts.sort((a, b) => a.page - b.page);
-    return extractedPageTexts;
-};
-// Determines the actual list of pages to process based on target pages and total pages
-const determinePagesToProcess = (targetPages, totalPages, includeFullText) => {
-    let pagesToProcess = [];
-    let invalidPages = [];
-    if (targetPages) {
-        // Filter target pages based on actual total pages
-        pagesToProcess = targetPages.filter((p) => p <= totalPages);
-        invalidPages = targetPages.filter((p) => p > totalPages);
-    }
-    else if (includeFullText) {
-        // If no specific pages requested for this source, use global flag
-        pagesToProcess = Array.from({ length: totalPages }, (_, i) => i + 1);
-    }
-    return { pagesToProcess, invalidPages };
-};
-// Processes a single PDF source
-const processSingleSource = async (source, globalIncludeFullText, globalIncludeMetadata, globalIncludePageCount) => {
+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';
+/**
+ * Process a single PDF source
+ */
+const processSingleSource = async (source, options) => {
     const sourceDescription = source.path ?? source.url ?? 'unknown source';
     let individualResult = { source: sourceDescription, success: false };
     try {
-        // 1. Parse target pages for this source (throws McpError on invalid spec)
+        // Parse target pages
         const targetPages = getTargetPages(source.pages, sourceDescription);
-        // 2. Load PDF Document (throws McpError on loading failure)
-        // Destructure to remove 'pages' before passing to loadPdfDocument due to exactOptionalPropertyTypes
+        // Load PDF document
         const { pages: _pages, ...loadArgs } = source;
         const pdfDocument = await loadPdfDocument(loadArgs, sourceDescription);
         const totalPages = pdfDocument.numPages;
-        // 3. Extract Metadata & Page Count
-        const metadataOutput = await extractMetadataAndPageCount(pdfDocument, globalIncludeMetadata, globalIncludePageCount);
-        const output = { ...metadataOutput }; // Start building output
-        // 4. Determine actual pages to process
-        const { pagesToProcess, invalidPages } = determinePagesToProcess(targetPages, totalPages, globalIncludeFullText // Pass the global flag
-        );
-        // Add warnings for invalid requested pages
-        if (invalidPages.length > 0) {
-            output.warnings = output.warnings ?? [];
-            output.warnings.push(`Requested page numbers ${invalidPages.join(', ')} exceed total pages (${String(totalPages)}).`);
-        }
-        // 5. Extract Text (if needed)
+        // Extract metadata and page count
+        const metadataOutput = await extractMetadataAndPageCount(pdfDocument, options.includeMetadata, options.includePageCount);
+        const output = { ...metadataOutput };
+        // Determine pages to process
+        const { pagesToProcess, invalidPages } = determinePagesToProcess(targetPages, totalPages, options.includeFullText);
+        // Add warnings for invalid pages
+        const warnings = buildWarnings(invalidPages, totalPages);
+        if (warnings.length > 0) {
+            output.warnings = warnings;
+        }
+        // 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) {
-                // If specific pages were requested for *this source*
+                // Specific pages requested
                 output.page_texts = extractedPageTexts;
             }
             else {
-                // Only assign full_text if pages were NOT specified for this source
+                // Full text requested
                 output.full_text = extractedPageTexts.map((p) => p.text).join('\n\n');
             }
+            // 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 };
     }
     catch (error) {
         let errorMessage = `Failed to process PDF from ${sourceDescription}.`;
         if (error instanceof McpError) {
-            errorMessage = error.message; // Use message from McpError directly
+            errorMessage = error.message;
         }
         else if (error instanceof Error) {
             errorMessage += ` Reason: ${error.message}`;
@@ -303,40 +79,90 @@ const processSingleSource = async (source, globalIncludeFullText, globalIncludeM
         }
         individualResult.error = errorMessage;
         individualResult.success = false;
-        individualResult.data = undefined; // Ensure no data on error
+        individualResult.data = undefined;
     }
     return individualResult;
 };
-// --- Main Handler Function ---
+/**
+ * Main handler function for read_pdf tool
+ */
 export const handleReadPdfFunc = async (args) => {
     let parsedArgs;
     try {
-        parsedArgs = ReadPdfArgsSchema.parse(args);
+        parsedArgs = readPdfArgsSchema.parse(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(', ')}`);
         }
-        // Added fallback for non-Zod errors during parsing
         const message = error instanceof Error ? error.message : String(error);
         throw new McpError(ErrorCode.InvalidParams, `Argument validation failed: ${message}`);
     }
-    const { sources, include_full_text, include_metadata, include_page_count } = parsedArgs;
+    const { sources, include_full_text, include_metadata, include_page_count, include_images } = parsedArgs;
     // Process all sources concurrently
-    const results = await Promise.all(sources.map((source) => processSingleSource(source, include_full_text, include_metadata, include_page_count)));
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({ results }, null, 2),
-            },
-        ],
-    };
+    const results = await Promise.all(sources.map((source) => processSingleSource(source, {
+        includeFullText: include_full_text,
+        includeMetadata: include_metadata,
+        includePageCount: include_page_count,
+        includeImages: include_images,
+    })));
+    // Build content parts - start with structured JSON for backward compatibility
+    const content = [];
+    // Strip image data and page_contents from JSON to keep it manageable
+    const resultsForJson = results.map((result) => {
+        if (result.data) {
+            const { images, page_contents, ...dataWithoutBinaryContent } = result.data;
+            // Include image count and metadata in JSON, but not the base64 data
+            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;
+    });
+    // First content part: Structured JSON results
+    content.push({
+        type: 'text',
+        text: JSON.stringify({ results: resultsForJson }, null, 2),
+    });
+    // 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,
+                    });
+                }
+                else if (item.type === 'image' && item.imageData) {
+                    // Add image content part
+                    content.push({
+                        type: 'image',
+                        data: item.imageData.data,
+                        mimeType: item.imageData.format === 'rgba' ? 'image/png' : 'image/jpeg',
+                    });
+                }
+            }
+        }
+    }
+    return { content };
 };
-// Export the consolidated ToolDefinition
+// Export the tool definition
 export const readPdfToolDefinition = {
     name: 'read_pdf',
-    description: 'Reads content/metadata from one or more PDFs (local/URL). Each source can specify pages to extract.',
-    schema: ReadPdfArgsSchema,
+    description: 'Reads content/metadata/images from one or more PDFs (local/URL). Each source can specify pages to extract.',
+    schema: readPdfArgsSchema,
     handler: handleReadPdfFunc,
 };

package/dist/index.js

@@ -10,9 +10,9 @@ import { allToolDefinitions } from './handlers/index.js';
 // Removed tool name constants, names are now in the definitions
 // --- Server Setup ---
 const server = new Server({
-    name: 'filesystem-mcp',
-    version: '0.4.0', // Increment version for definition refactor
-    description: 'MCP Server for filesystem operations relative to the project root.',
+    name: 'pdf-reader-mcp',
+    version: '1.2.0',
+    description: 'MCP Server for reading PDF files and extracting text, metadata, images, and page information.',
 }, {
     capabilities: { tools: {} },
 });
@@ -48,10 +48,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('[Filesystem MCP] Server running on stdio');
+    console.error('[PDF Reader MCP] Server running on stdio');
 }
 main().catch((error) => {
     // Specify 'unknown' type for catch variable
-    console.error('[Filesystem MCP] Server error:', error);
+    console.error('[PDF Reader MCP] Server error:', error);
     process.exit(1);
 });

package/dist/pdf/extractor.js

@@ -0,0 +1,265 @@
+// PDF text and metadata extraction utilities
+import { OPS } from 'pdfjs-dist/legacy/build/pdf.mjs';
+/**
+ * Extract metadata and page count from a PDF document
+ */
+export const extractMetadataAndPageCount = async (pdfDocument, includeMetadata, includePageCount) => {
+    const output = {};
+    if (includePageCount) {
+        output.num_pages = pdfDocument.numPages;
+    }
+    if (includeMetadata) {
+        try {
+            const pdfMetadata = await pdfDocument.getMetadata();
+            const infoData = pdfMetadata.info;
+            if (infoData !== undefined) {
+                output.info = infoData;
+            }
+            const metadataObj = pdfMetadata.metadata;
+            // Check if it has a getAll method (as used in tests)
+            if (typeof metadataObj.getAll === 'function') {
+                output.metadata = metadataObj.getAll();
+            }
+            else {
+                // For real PDF.js metadata, convert to plain object
+                const metadataRecord = {};
+                for (const key in metadataObj) {
+                    if (Object.hasOwn(metadataObj, key)) {
+                        metadataRecord[key] = metadataObj[key];
+                    }
+                }
+                output.metadata = metadataRecord;
+            }
+        }
+        catch (metaError) {
+            console.warn(`[PDF Reader MCP] Error extracting metadata: ${metaError instanceof Error ? metaError.message : String(metaError)}`);
+        }
+    }
+    return output;
+};
+/**
+ * Extract text from a single page
+ */
+const extractSinglePageText = async (pdfDocument, pageNum, sourceDescription) => {
+    try {
+        const page = await pdfDocument.getPage(pageNum);
+        const textContent = await page.getTextContent();
+        const pageText = textContent.items
+            .map((item) => item.str)
+            .join('');
+        return { page: pageNum, text: pageText };
+    }
+    catch (pageError) {
+        const message = pageError instanceof Error ? pageError.message : String(pageError);
+        console.warn(`[PDF Reader MCP] Error getting text content for page ${String(pageNum)} in ${sourceDescription}: ${message}`);
+        return { page: pageNum, text: `Error processing page: ${message}` };
+    }
+};
+/**
+ * Extract text from specified pages (parallel processing for performance)
+ */
+export const extractPageTexts = async (pdfDocument, pagesToProcess, sourceDescription) => {
+    // Process all pages in parallel for better performance
+    const extractedPageTexts = await Promise.all(pagesToProcess.map((pageNum) => extractSinglePageText(pdfDocument, pageNum, sourceDescription)));
+    return extractedPageTexts.sort((a, b) => a.page - b.page);
+};
+/**
+ * Extract images from a single page
+ */
+const extractImagesFromPage = async (page, pageNum) => {
+    const images = [];
+    try {
+        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 using Promise-based approach
+        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];
+            // Use callback-based get() as images may not be resolved yet
+            page.objs.get(imageName, (imageData) => {
+                if (!imageData || typeof imageData !== 'object') {
+                    resolve(null);
+                    return;
+                }
+                const img = imageData;
+                if (!img.data || !img.width || !img.height) {
+                    resolve(null);
+                    return;
+                }
+                // Determine image format based on kind
+                // kind === 1 = grayscale, 2 = RGB, 3 = RGBA
+                const format = img.kind === 1 ? 'grayscale' : img.kind === 3 ? 'rgba' : 'rgb';
+                // Convert Uint8Array to base64
+                const base64 = Buffer.from(img.data).toString('base64');
+                resolve({
+                    page: pageNum,
+                    index: arrayIndex,
+                    width: img.width,
+                    height: img.height,
+                    format,
+                    data: base64,
+                });
+            });
+        }));
+        const resolvedImages = await Promise.all(imagePromises);
+        images.push(...resolvedImages.filter((img) => img !== null));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[PDF Reader MCP] Error extracting images from page ${String(pageNum)}: ${message}`);
+    }
+    return images;
+};
+/**
+ * Extract images from specified pages
+ */
+export const extractImages = async (pdfDocument, pagesToProcess) => {
+    const allImages = [];
+    // Process pages sequentially to avoid overwhelming PDF.js
+    for (const pageNum of pagesToProcess) {
+        try {
+            const page = await pdfDocument.getPage(pageNum);
+            const pageImages = await extractImagesFromPage(page, pageNum);
+            allImages.push(...pageImages);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[PDF Reader MCP] Error getting page ${String(pageNum)} for image extraction: ${message}`);
+        }
+    }
+    return allImages;
+};
+/**
+ * Build warnings array for invalid page numbers
+ */
+export const buildWarnings = (invalidPages, totalPages) => {
+    if (invalidPages.length === 0) {
+        return [];
+    }
+    return [
+        `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
+            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)
+                // The transform is typically in argsArray[1] for some ops
+                let yPosition = 0;
+                if (argsArray.length > 1 && Array.isArray(argsArray[1])) {
+                    const transform = argsArray[1];
+                    // transform[5] is the Y coordinate
+                    const yCoord = transform[5];
+                    if (yCoord !== undefined) {
+                        yPosition = Math.round(yCoord);
+                    }
+                }
+                // Use callback-based get() as images may not be resolved yet
+                page.objs.get(imageName, (imageData) => {
+                    if (!imageData || typeof imageData !== 'object') {
+                        resolve(null);
+                        return;
+                    }
+                    const img = imageData;
+                    if (!img.data || !img.width || !img.height) {
+                        resolve(null);
+                        return;
+                    }
+                    // Determine image format based on kind
+                    const format = img.kind === 1 ? 'grayscale' : img.kind === 3 ? 'rgba' : 'rgb';
+                    // Convert Uint8Array to base64
+                    const base64 = Buffer.from(img.data).toString('base64');
+                    resolve({
+                        type: 'image',
+                        yPosition,
+                        imageData: {
+                            page: pageNum,
+                            index: arrayIndex,
+                            width: img.width,
+                            height: img.height,
+                            format,
+                            data: base64,
+                        },
+                    });
+                });
+            }));
+            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/loader.js

@@ -0,0 +1,53 @@
+// PDF document loading utilities
+import fs from 'node:fs/promises';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs';
+import { resolvePath } from '../utils/pathUtils.js';
+/**
+ * Load a PDF document from a local file path or URL
+ * @param source - Object containing either path or url
+ * @param sourceDescription - Description for error messages
+ * @returns PDF document proxy
+ */
+export const loadPdfDocument = async (source, sourceDescription) => {
+    let pdfDataSource;
+    try {
+        if (source.path) {
+            const safePath = resolvePath(source.path);
+            const buffer = await fs.readFile(safePath);
+            pdfDataSource = new Uint8Array(buffer);
+        }
+        else if (source.url) {
+            pdfDataSource = { url: source.url };
+        }
+        else {
+            throw new McpError(ErrorCode.InvalidParams, `Source ${sourceDescription} missing 'path' or 'url'.`);
+        }
+    }
+    catch (err) {
+        if (err instanceof McpError) {
+            throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        const errorCode = ErrorCode.InvalidRequest;
+        if (typeof err === 'object' &&
+            err !== null &&
+            'code' in err &&
+            err.code === 'ENOENT' &&
+            source.path) {
+            throw new McpError(errorCode, `File not found at '${source.path}'.`, {
+                cause: err instanceof Error ? err : undefined,
+            });
+        }
+        throw new McpError(errorCode, `Failed to prepare PDF source ${sourceDescription}. Reason: ${message}`, { cause: err instanceof Error ? err : undefined });
+    }
+    const loadingTask = getDocument(pdfDataSource);
+    try {
+        return await loadingTask.promise;
+    }
+    catch (err) {
+        console.error(`[PDF Reader MCP] PDF.js loading error for ${sourceDescription}:`, err);
+        const message = err instanceof Error ? err.message : String(err);
+        throw new McpError(ErrorCode.InvalidRequest, `Failed to load PDF document from ${sourceDescription}. Reason: ${message || 'Unknown loading error'}`, { cause: err instanceof Error ? err : undefined });
+    }
+};

package/dist/pdf/parser.js

@@ -0,0 +1,94 @@
+// Page range parsing utilities
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+const MAX_RANGE_SIZE = 10000; // Prevent infinite loops for open ranges
+/**
+ * Parse a single range part (e.g., "1-3", "5", "7-")
+ */
+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 start = parseInt(startStr, 10);
+        const end = endStr === '' || endStr === undefined ? Infinity : parseInt(endStr, 10);
+        if (Number.isNaN(start) || Number.isNaN(end) || start <= 0 || start > end) {
+            throw new Error(`Invalid page range values: ${trimmedPart}`);
+        }
+        const practicalEnd = Math.min(end, start + MAX_RANGE_SIZE);
+        for (let i = start; i <= practicalEnd; i++) {
+            pages.add(i);
+        }
+        if (end === Infinity && practicalEnd === start + MAX_RANGE_SIZE) {
+            console.warn(`[PDF Reader MCP] Open-ended range starting at ${String(start)} was truncated at page ${String(practicalEnd)}.`);
+        }
+    }
+    else {
+        const page = parseInt(trimmedPart, 10);
+        if (Number.isNaN(page) || page <= 0) {
+            throw new Error(`Invalid page number: ${trimmedPart}`);
+        }
+        pages.add(page);
+    }
+};
+/**
+ * Parse page range string into array of page numbers
+ * @param ranges - Range string (e.g., "1-3,5,7-10")
+ * @returns Sorted array of unique page numbers
+ */
+export const parsePageRanges = (ranges) => {
+    const pages = new Set();
+    const parts = ranges.split(',');
+    for (const part of parts) {
+        parseRangePart(part, pages);
+    }
+    if (pages.size === 0) {
+        throw new Error('Page range string resulted in zero valid pages.');
+    }
+    return Array.from(pages).sort((a, b) => a - b);
+};
+/**
+ * Get target pages from page specification
+ * @param sourcePages - Page specification (string or array)
+ * @param sourceDescription - Description for error messages
+ * @returns Array of page numbers or undefined
+ */
+export const getTargetPages = (sourcePages, sourceDescription) => {
+    if (!sourcePages) {
+        return undefined;
+    }
+    try {
+        if (typeof sourcePages === 'string') {
+            return parsePageRanges(sourcePages);
+        }
+        // Array of page numbers
+        if (sourcePages.some((p) => !Number.isInteger(p) || p <= 0)) {
+            throw new Error('Page numbers in array must be positive integers.');
+        }
+        const uniquePages = [...new Set(sourcePages)].sort((a, b) => a - b);
+        if (uniquePages.length === 0) {
+            throw new Error('Page specification resulted in an empty set of pages.');
+        }
+        return uniquePages;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new McpError(ErrorCode.InvalidParams, `Invalid page specification for source ${sourceDescription}: ${message}`);
+    }
+};
+/**
+ * Determine which pages to process based on target pages and document size
+ */
+export const determinePagesToProcess = (targetPages, totalPages, includeFullText) => {
+    if (targetPages) {
+        const pagesToProcess = targetPages.filter((p) => p <= totalPages);
+        const invalidPages = targetPages.filter((p) => p > totalPages);
+        return { pagesToProcess, invalidPages };
+    }
+    if (includeFullText) {
+        const pagesToProcess = Array.from({ length: totalPages }, (_, i) => i + 1);
+        return { pagesToProcess, invalidPages: [] };
+    }
+    return { pagesToProcess: [], invalidPages: [] };
+};

package/dist/schemas/readPdf.js

@@ -0,0 +1,55 @@
+// Zod validation schemas for PDF reading
+import { z } from 'zod';
+// Schema for page specification (array of numbers or range string)
+export const pageSpecifierSchema = z.union([
+    z.array(z.number().int().min(1)).min(1).describe('Array of page numbers (1-based)'),
+    z
+        .string()
+        .min(1)
+        .refine((val) => /^[0-9,-]+$/.test(val.replace(/\s/g, '')), {
+        message: 'Page string must contain only numbers, commas, and hyphens.',
+    })
+        .describe('Page range string (e.g., "1-5,10,15-20")'),
+]);
+// 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.'),
+    url: z.string().url().optional().describe('URL of the PDF file.'),
+    pages: pageSpecifierSchema
+        .optional()
+        .describe("Extract text only from specific pages (1-based) or ranges for this source. If provided, 'include_full_text' is ignored for this source."),
+})
+    .strict()
+    .refine((data) => !!(data.path && !data.url) || !!(!data.path && data.url), {
+    message: "Each source must have either 'path' or 'url', but not both.",
+});
+// Schema for the read_pdf tool arguments
+export const readPdfArgsSchema = z
+    .object({
+    sources: z
+        .array(pdfSourceSchema)
+        .min(1)
+        .describe('An array of PDF sources to process, each can optionally specify pages.'),
+    include_full_text: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Include the full text content of each PDF (only if 'pages' is not specified for that source)."),
+    include_metadata: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include metadata and info objects for each PDF.'),
+    include_page_count: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Include the total number of pages for each PDF.'),
+    include_images: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Extract and include embedded images from the PDF pages as base64-encoded data.'),
+})
+    .strict();

package/dist/types/pdf.js

@@ -0,0 +1,2 @@
+// PDF-related TypeScript type definitions
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylphx/pdf-reader-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "An MCP server providing tools to read PDF files.",
   "type": "module",
   "bin": {
@@ -39,32 +39,6 @@
     "agent",
     "tool"
   ],
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch",
-    "inspector": "npx @modelcontextprotocol/inspector dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest watch",
-    "test:cov": "vitest run --coverage --reporter=junit --outputFile=test-report.junit.xml",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --write .",
-    "format": "biome format --write .",
-    "check-format": "biome format .",
-    "check": "biome check .",
-    "check:fix": "biome check --write .",
-    "validate": "npm run check && npm run test",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs",
-    "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "benchmark": "vitest bench",
-    "clean": "rm -rf dist coverage",
-    "docs:api": "typedoc --entryPoints src/index.ts --tsconfig tsconfig.json --plugin typedoc-plugin-markdown --out docs/api --readme none",
-    "prepublishOnly": "pnpm run clean && pnpm run build",
-    "release": "standard-version",
-    "prepare": "husky"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.20.2",
     "glob": "^11.0.1",
@@ -98,5 +72,29 @@
     "*.{ts,tsx,js,cjs,json}": [
       "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
     ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:cov": "vitest run --coverage --reporter=junit --outputFile=test-report.junit.xml",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "biome format --write .",
+    "check-format": "biome format .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "validate": "npm run check && npm run test",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "benchmark": "vitest bench",
+    "clean": "rm -rf dist coverage",
+    "docs:api": "typedoc --entryPoints src/index.ts --tsconfig tsconfig.json --plugin typedoc-plugin-markdown --out docs/api --readme none",
+    "release": "standard-version"
   }
-}
+}