@sylphx/pdf-reader-mcp 1.2.0 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylphx/pdf-reader-mcp",
-  "version": "1.2.0",
+  "version": "1.3.2",
   "description": "An MCP server providing tools to read PDF files.",
   "type": "module",
   "bin": {
@@ -19,12 +19,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sylphlab/pdf-reader-mcp.git"
+    "url": "git+https://github.com/SylphxAI/pdf-reader-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/sylphlab/pdf-reader-mcp/issues"
+    "url": "https://github.com/SylphxAI/pdf-reader-mcp/issues"
   },
-  "homepage": "https://github.com/sylphlab/pdf-reader-mcp#readme",
+  "homepage": "https://github.com/SylphxAI/pdf-reader-mcp#readme",
   "author": "Sylphx <contact@sylphx.com> (https://sylphx.com)",
   "license": "MIT",
   "keywords": [
@@ -39,20 +39,53 @@
     "agent",
     "tool"
   ],
+  "scripts": {
+    "build": "bunup",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:cov": "vitest run --coverage",
+    "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": "bun run check && bun 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": "bun run clean && bun run build",
+    "release": "standard-version",
+    "prepare": "husky",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release:new": "bun run build && changeset publish"
+  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.20.2",
+    "@modelcontextprotocol/sdk": "^1.21.0",
     "glob": "^11.0.1",
     "pdfjs-dist": "^5.4.296",
-    "zod": "^3.24.2",
-    "zod-to-json-schema": "^3.24.5"
+    "pngjs": "^7.0.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.2",
-    "@commitlint/cli": "^19.8.0",
-    "@commitlint/config-conventional": "^19.8.0",
+    "@changesets/cli": "^2.29.7",
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
     "@types/glob": "^8.1.0",
     "@types/node": "^24.0.7",
-    "@vitest/coverage-v8": "^3.1.1",
+    "@types/pngjs": "^6.0.5",
+    "@vitest/coverage-v8": "^4.0.8",
+    "bunup": "^0.16.10",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.6",
     "standard-version": "^9.5.0",
@@ -60,7 +93,7 @@
     "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.8.3",
     "vitepress": "^1.6.3",
-    "vitest": "^3.1.1",
+    "vitest": "^4.0.7",
     "vue": "^3.5.13"
   },
   "commitlint": {
@@ -73,28 +106,5 @@
       "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"
-  }
-}
+  "packageManager": "bun@1.3.1"
+}

package/dist/handlers/index.js

@@ -1,4 +0,0 @@
-// Import only the consolidated PDF tool definition
-import { readPdfToolDefinition } from './readPdf.js';
-// Aggregate only the consolidated PDF tool definition
-export const allToolDefinitions = [readPdfToolDefinition];

package/dist/handlers/readPdf.js

@@ -1,168 +0,0 @@
-// PDF reading handler - orchestrates PDF processing workflow
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
-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 {
-        // Parse target pages
-        const targetPages = getTargetPages(source.pages, sourceDescription);
-        // Load PDF document
-        const { pages: _pages, ...loadArgs } = source;
-        const pdfDocument = await loadPdfDocument(loadArgs, sourceDescription);
-        const totalPages = pdfDocument.numPages;
-        // 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) {
-            // 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;
-            }
-            else {
-                // 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;
-        }
-        else if (error instanceof Error) {
-            errorMessage += ` Reason: ${error.message}`;
-        }
-        else {
-            errorMessage += ` Unknown error: ${JSON.stringify(error)}`;
-        }
-        individualResult.error = errorMessage;
-        individualResult.success = false;
-        individualResult.data = undefined;
-    }
-    return individualResult;
-};
-/**
- * Main handler function for read_pdf tool
- */
-export const handleReadPdfFunc = async (args) => {
-    let parsedArgs;
-    try {
-        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(', ')}`);
-        }
-        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, include_images } = parsedArgs;
-    // Process all sources concurrently
-    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 tool definition
-export const readPdfToolDefinition = {
-    name: 'read_pdf',
-    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/pdf/extractor.js

@@ -1,265 +0,0 @@
-// 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

@@ -1,53 +0,0 @@
-// 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 });
-    }
-};