pdf-reader-mcp

Extracts text content from PDF pages using Promise.all() for concurrent processing across multiple pages, then sorts extracted content by Y-coordinate (vertical position) to preserve document layout semantics. This approach achieves 5-10x speedup over sequential extraction while maintaining structural integrity of multi-column layouts and ordered content blocks. The implementation uses pdf-parse library with custom coordinate-based sorting in src/pdf/extractor.ts.

Extracts embedded images from PDF documents and encodes them as base64-encoded PNG data URIs for direct embedding in LLM context windows. The implementation iterates through PDF page resources, identifies image objects, converts them to PNG format, and returns them as data URLs that Claude, Cursor, and other MCP clients can directly consume without additional file I/O. Handled in src/pdf/extractor.ts with image processing pipeline.

Includes extensive test suite with 94%+ code coverage using Jest or similar testing framework, covering PDF extraction, error handling, edge cases (empty PDFs, corrupted pages, large files), and MCP protocol compliance. Tests are organized by module (extractor, loader, parser, handlers) and include both unit tests and integration tests. The test suite validates correctness of parallel extraction, Y-coordinate ordering, error isolation, and response schema compliance.

Provides Docker configuration (Dockerfile, docker-compose.yml) for containerized deployment of the MCP server, enabling easy integration into orchestrated environments (Kubernetes, Docker Compose). The Docker image includes Node.js runtime, pdf-reader-mcp dependencies, and startup scripts. Deployment documentation covers image building, container configuration, and integration with MCP clients via stdio transport within containers.

Distributes pdf-reader-mcp as an npm package with automated CI/CD pipeline (GitHub Actions) that runs tests, builds the package, and publishes to npm registry on release. The package.json defines dependencies, build scripts, and entry points. CI/CD pipeline validates code quality, runs test suite, and publishes new versions automatically. This enables easy installation via 'npm install pdf-reader-mcp' and ensures consistent builds across environments.

Parses complex page range specifications (e.g., '1-5,10,15-20') into discrete page numbers, and normalizes file paths across Windows/Unix/relative/absolute formats using path resolution logic in src/pdf/parser.ts. The implementation validates range syntax, expands ranges into individual pages, and resolves paths relative to the MCP server's working directory, handling edge cases like negative indices and out-of-bounds ranges gracefully.

Implements error handling that isolates failures to individual pages using Promise.allSettled() internally, allowing extraction to continue on remaining pages even if one page fails to parse. Failed pages generate warning objects in the response (not exceptions) that include error details, page number, and fallback content (if available). This pattern is implemented in src/handlers/readPdf.ts and prevents single malformed pages from blocking the entire PDF extraction.

Implements a Model Context Protocol (MCP) server using Node.js stdio transport, communicating with MCP clients via JSON-RPC 2.0 messages over standard input/output. The server exposes a single 'read_pdf' tool with structured input schema and response format, handling client requests asynchronously and returning results as JSON. Implemented in src/index.ts with MCP SDK integration for protocol compliance and automatic schema validation.

Extracts PDF metadata including author, title, creation date, modification date, and other document properties from PDF headers without parsing page content. This is implemented in src/pdf/extractor.ts using pdf-parse's metadata API, returning structured metadata objects that provide document-level context to AI agents. Metadata extraction is fast (no page parsing required) and can be used to filter or prioritize PDFs before full content extraction.

Processes multiple PDF files concurrently with a configurable concurrency limit (default: 3 concurrent operations) to prevent resource exhaustion while maintaining parallelism. The implementation uses a queue-based approach in src/handlers/readPdf.ts that limits the number of in-flight Promise operations, allowing agents to submit multiple PDF extraction requests without overwhelming the server. Concurrency is managed via Promise.all() with a sliding window of active operations.

Counts total pages in a PDF by reading only the document structure (PDF catalog and page tree) without loading or parsing page content. Implemented in src/pdf/loader.ts using pdf-parse's page enumeration API, this operation completes in milliseconds even for large PDFs. Page count is returned as metadata and can be used by agents to validate page range requests or estimate extraction time before processing.

Formats all PDF extraction results into a standardized JSON structure with schema validation, ensuring consistent response format across all tool invocations. The response schema includes sections for extracted text, images, metadata, errors, and extraction statistics. Implemented in src/handlers/readPdf.ts with TypeScript type definitions and JSON Schema validation, this ensures MCP clients can reliably parse responses and handle errors consistently.

Entire codebase is implemented in TypeScript with strict type checking enabled, providing compile-time type safety for all PDF operations, handler functions, and MCP protocol interactions. Type definitions are exported for client-side use, enabling MCP clients to import and use the same types for request/response validation. The build system (src/build.ts or similar) compiles TypeScript to JavaScript for runtime execution.