@sylphx/pdf-reader-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SylphLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,390 @@
+# PDF Reader MCP Server
+
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/sylphxltd-pdf-reader-mcp-badge.png)](https://mseep.ai/app/sylphxltd-pdf-reader-mcp)
+[![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)
+
+<a href="https://glama.ai/mcp/servers/@sylphlab/pdf-reader-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@sylphlab/pdf-reader-mcp/badge" alt="PDF Reader Server MCP server" />
+</a>
+
+**Empower your AI agents** with the ability to securely read and extract information from PDF files using the Model Context Protocol (MCP).
+
+## ✨ Features
+
+- 📄 **Extract text content** from PDF files (full document or specific pages)
+- 📊 **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
+- 🔄 **Batch processing** - Handle multiple PDFs in a single request
+- 📦 **Multiple deployment options** - npm, Docker, or Smithery
+
+## 🆕 Recent Updates (October 2025)
+
+- ✅ **Fixed critical bugs**: Buffer/Uint8Array compatibility for PDF.js v5.x
+- ✅ **Fixed schema validation**: Resolved `exclusiveMinimum` issue affecting Windsurf, Mistral API, and other tools
+- ✅ **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
+
+## 📦 Installation
+
+### Option 1: Using Smithery (Easiest)
+
+Install automatically for Claude Desktop:
+
+```bash
+npx -y @smithery/cli install @sylphxltd/pdf-reader-mcp --client claude
+```
+
+### Option 2: Using npm/pnpm (Recommended)
+
+Install the package:
+
+```bash
+pnpm add @sylphx/pdf-reader-mcp
+# or
+npm install @sylphx/pdf-reader-mcp
+```
+
+Configure your MCP client (e.g., Claude Desktop, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "pdf-reader-mcp": {
+      "command": "npx",
+      "args": ["@sylphx/pdf-reader-mcp"]
+    }
+  }
+}
+```
+
+**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
+
+```bash
+git clone https://github.com/sylphlab/pdf-reader-mcp.git
+cd pdf-reader-mcp
+pnpm install
+pnpm run build
+```
+
+Then configure your MCP client to use `node dist/index.js`.
+
+## 🚀 Quick Start
+
+Once configured, your AI agent can read PDFs using the `read_pdf` tool:
+
+### Example 1: Extract text from specific pages
+
+```json
+{
+  "sources": [
+    {
+      "path": "documents/report.pdf",
+      "pages": [1, 2, 3]
+    }
+  ],
+  "include_metadata": true
+}
+```
+
+### Example 2: Get metadata and page count only
+
+```json
+{
+  "sources": [{ "path": "documents/report.pdf" }],
+  "include_metadata": true,
+  "include_page_count": true,
+  "include_full_text": false
+}
+```
+
+### Example 3: Read from URL
+
+```json
+{
+  "sources": [
+    {
+      "url": "https://example.com/document.pdf"
+    }
+  ],
+  "include_full_text": true
+}
+```
+
+### Example 4: Process multiple PDFs
+
+```json
+{
+  "sources": [
+    { "path": "doc1.pdf", "pages": "1-5" },
+    { "path": "doc2.pdf" },
+    { "url": "https://example.com/doc3.pdf" }
+  ],
+  "include_full_text": true
+}
+```
+
+## 📖 Usage Guide
+
+### Page Specification
+
+You can specify pages in multiple ways:
+
+- **Array of page numbers**: `[1, 3, 5]` (1-based indexing)
+- **Range string**: `"1-10"` (extracts pages 1 through 10)
+- **Multiple ranges**: `"1-5,10-15,20"` (commas separate ranges and individual pages)
+- **Omit for all pages**: Don't include the `pages` field to extract all pages
+
+### Working with Large PDFs
+
+For large PDF files (>20 MB), extract specific pages instead of the full document:
+
+```json
+{
+  "sources": [
+    {
+      "path": "large-document.pdf",
+      "pages": "1-10"
+    }
+  ]
+}
+```
+
+This prevents hitting AI model context limits and improves performance.
+
+### Security: Relative Paths Only
+
+**Important:** The server only accepts **relative paths** for security reasons. Absolute paths are blocked to prevent unauthorized file system access.
+
+✅ **Good**: `"path": "documents/report.pdf"`
+❌ **Bad**: `"path": "/Users/john/documents/report.pdf"`
+
+**Solution**: Configure the `cwd` (current working directory) in your MCP client settings.
+
+## 🔧 Troubleshooting
+
+### Issue: "No tools" showing up
+
+**Solution**: Clear npm cache and reinstall:
+
+```bash
+npm cache clean --force
+npx @sylphx/pdf-reader-mcp@latest
+```
+
+Restart your MCP client completely after updating.
+
+### Issue: "File not found" errors
+
+**Causes**:
+
+1. Using absolute paths (not allowed for security)
+2. Incorrect working directory
+
+**Solution**: Use relative paths and configure `cwd` in your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "pdf-reader-mcp": {
+      "command": "npx",
+      "args": ["@sylphx/pdf-reader-mcp"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### Issue: Cursor/Claude Code compatibility
+
+**Solution**: Update to the latest version (all recent compatibility issues have been fixed):
+
+```bash
+npm update @sylphx/pdf-reader-mcp@latest
+```
+
+Then restart your editor completely.
+
+## ⚡ Performance
+
+Benchmarks on a standard PDF file:
+
+| Operation                        | Ops/sec   | Speed      |
+| :------------------------------- | :-------- | :--------- |
+| Handle Non-Existent File         | ~12,933   | Fastest    |
+| Get Full Text                    | ~5,575    |            |
+| Get Specific Page                | ~5,329    |            |
+| Get Multiple Pages               | ~5,242    |            |
+| Get Metadata & Page Count        | ~4,912    | Slowest    |
+
+_Performance varies based on PDF complexity and system resources._
+
+See [Performance Documentation](./docs/performance/index.md) for details.
+
+## 🏗️ Architecture
+
+### Tech Stack
+
+- **Runtime**: Node.js 22+
+- **PDF Processing**: PDF.js (pdfjs-dist)
+- **Validation**: Zod with JSON Schema generation
+- **Protocol**: Model Context Protocol (MCP) SDK
+- **Build**: TypeScript
+- **Testing**: Vitest with 100% coverage goal
+- **Code Quality**: Biome (linting + formatting)
+- **CI/CD**: GitHub Actions
+
+### Design Principles
+
+1. **Security First**: Strict path validation and sandboxing
+2. **Simple Interface**: Single tool handles all PDF operations
+3. **Structured Output**: Predictable JSON format for AI parsing
+4. **Performance**: Efficient caching and lazy loading
+5. **Reliability**: Comprehensive error handling and validation
+
+See [Design Philosophy](./docs/design/index.md) for more details.
+
+## 🧪 Development
+
+### Prerequisites
+
+- Node.js >= 22.0.0
+- pnpm (recommended) or npm
+
+### Setup
+
+```bash
+git clone https://github.com/sylphlab/pdf-reader-mcp.git
+cd pdf-reader-mcp
+pnpm install
+```
+
+### Available Scripts
+
+```bash
+pnpm run build        # Build TypeScript to dist/
+pnpm run watch        # Build in watch mode
+pnpm run test         # Run tests
+pnpm run test:watch   # Run tests in watch mode
+pnpm run test:cov     # Run tests with coverage
+pnpm run check        # Run Biome (lint + format check)
+pnpm run check:fix    # Fix Biome issues automatically
+pnpm run lint         # Lint with Biome
+pnpm run format       # Format with Biome
+pnpm run typecheck    # TypeScript type checking
+pnpm run benchmark    # Run performance benchmarks
+pnpm run validate     # Full validation (check + test)
+```
+
+### Testing
+
+We maintain high test coverage using Vitest:
+
+```bash
+pnpm run test         # Run all tests
+pnpm run test:cov     # Run with coverage report
+```
+
+All tests must pass before merging. Current: **31/31 tests passing** ✅
+
+### Code Quality
+
+The project uses [Biome](https://biomejs.dev/) for fast, unified linting and formatting:
+
+```bash
+pnpm run check        # Check code quality
+pnpm run check:fix    # Auto-fix issues
+```
+
+### Contributing
+
+We welcome contributions! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and ensure tests pass
+4. Run `pnpm run check:fix` to format code
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/)
+6. Open a Pull Request
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
+
+## 📚 Documentation
+
+- **[Full Documentation](https://sylphlab.github.io/pdf-reader-mcp/)** - Complete guides and API reference
+- **[Getting Started Guide](./docs/guide/getting-started.md)** - Quick start guide
+- **[API Reference](./docs/api/README.md)** - Detailed API documentation
+- **[Design Philosophy](./docs/design/index.md)** - Architecture and design decisions
+- **[Performance](./docs/performance/index.md)** - Benchmarks and optimization
+- **[Comparison](./docs/comparison/index.md)** - How it compares to alternatives
+
+## 🗺️ Roadmap
+
+- [ ] Image extraction from PDFs
+- [ ] Annotation extraction support
+- [ ] OCR integration for scanned PDFs
+- [ ] Streaming support for very large files
+- [ ] Enhanced caching mechanisms
+- [ ] Performance optimizations for large batches
+
+## 🤝 Support & Community
+
+- **Issues**: [GitHub Issues](https://github.com/sylphlab/pdf-reader-mcp/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/sylphlab/pdf-reader-mcp/discussions)
+- **Contributing**: [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+If you find this project useful, please:
+
+- ⭐ Star the repository
+- 👀 Watch for updates
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🔀 Contribute code
+
+## 📄 License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+---
+
+**Made with ❤️ by [Sylphx](https://sylphx.com)**

package/dist/handlers/index.js

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

@@ -0,0 +1,342 @@
+import fs from 'node:fs/promises';
+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) => {
+    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)
+        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
+        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)
+        if (pagesToProcess.length > 0) {
+            const extractedPageTexts = await extractPageTexts(pdfDocument, pagesToProcess, sourceDescription);
+            if (targetPages) {
+                // If specific pages were requested for *this source*
+                output.page_texts = extractedPageTexts;
+            }
+            else {
+                // Only assign full_text if pages were NOT specified for this source
+                output.full_text = extractedPageTexts.map((p) => p.text).join('\n\n');
+            }
+        }
+        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
+        }
+        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; // Ensure no data on error
+    }
+    return individualResult;
+};
+// --- Main Handler Function ---
+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(', ')}`);
+        }
+        // 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;
+    // 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),
+            },
+        ],
+    };
+};
+// Export the consolidated ToolDefinition
+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,
+    handler: handleReadPdfFunc,
+};

package/dist/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+// Import the aggregated tool definitions
+import { allToolDefinitions } from './handlers/index.js';
+// Removed incorrect import left over from partial diff
+// --- Tool Names (Constants) ---
+// 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.',
+}, {
+    capabilities: { tools: {} },
+});
+// Helper function to convert Zod schema to JSON schema for MCP
+// Use 'unknown' instead of 'any' for better type safety, although casting is still needed for the SDK
+const generateInputSchema = (schema) => {
+    // Need to cast as 'unknown' then 'object' because zodToJsonSchema might return slightly incompatible types for MCP SDK
+    return zodToJsonSchema(schema, { target: 'openApi3' });
+};
+server.setRequestHandler(ListToolsRequestSchema, () => {
+    // Removed unnecessary async
+    // Removed log
+    // Map the aggregated definitions to the format expected by the SDK
+    const availableTools = allToolDefinitions.map((def) => ({
+        name: def.name,
+        description: def.description,
+        inputSchema: generateInputSchema(def.schema), // Generate JSON schema from Zod schema
+    }));
+    return { tools: availableTools };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    // Use imported handlers
+    // Find the tool definition by name and call its handler
+    const toolDefinition = allToolDefinitions.find((def) => def.name === request.params.name);
+    if (!toolDefinition) {
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
+    }
+    // Call the handler associated with the found definition
+    // The handler itself will perform Zod validation on the arguments
+    return toolDefinition.handler(request.params.arguments);
+});
+// --- Server Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[Filesystem MCP] Server running on stdio');
+}
+main().catch((error) => {
+    // Specify 'unknown' type for catch variable
+    console.error('[Filesystem MCP] Server error:', error);
+    process.exit(1);
+});

package/dist/utils/pathUtils.js

@@ -0,0 +1,30 @@
+// Removed unused import: import { fileURLToPath } from 'url';
+import path from 'node:path';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+// Use the server's current working directory as the project root.
+// This relies on the process launching the server to set the CWD correctly.
+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.
+ * @returns The resolved absolute path.
+ */
+export const resolvePath = (userPath) => {
+    if (typeof userPath !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'Path must be a string.');
+    }
+    const normalizedUserPath = path.normalize(userPath);
+    if (path.isAbsolute(normalizedUserPath)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Absolute paths are not allowed.');
+    }
+    // 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;
+};

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@sylphx/pdf-reader-mcp",
+  "version": "1.0.0",
+  "description": "An MCP server providing tools to read PDF files.",
+  "type": "module",
+  "bin": {
+    "pdf-reader-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sylphlab/pdf-reader-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sylphlab/pdf-reader-mcp/issues"
+  },
+  "homepage": "https://github.com/sylphlab/pdf-reader-mcp#readme",
+  "author": "Sylphx <contact@sylphx.com> (https://sylphx.com)",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pdf",
+    "reader",
+    "parser",
+    "typescript",
+    "node",
+    "ai",
+    "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",
+    "pdfjs-dist": "^5.4.296",
+    "zod": "^3.24.2",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.2",
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "@types/glob": "^8.1.0",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.1.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.6",
+    "standard-version": "^9.5.0",
+    "typedoc": "^0.28.2",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript": "^5.8.3",
+    "vitepress": "^1.6.3",
+    "vitest": "^3.1.1",
+    "vue": "^3.5.13"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,cjs,json}": [
+      "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
+    ]
+  }
+}