JoyD/pdf-reader-mcp/memory-bank/systemPatterns.md

System Patterns: PDF Reader MCP Server

1. Architecture Overview

The PDF Reader MCP server is a standalone Node.js application based on the original Filesystem MCP. It's designed to run as a child process, communicating with its parent (the AI agent host) via standard input/output (stdio) using the Model Context Protocol (MCP) to provide PDF reading capabilities.

graph LR
    A[Agent Host Environment] -- MCP over Stdio --> B(PDF Reader MCP Server);
    B -- Node.js fs/path/pdfjs-dist --> C[User Filesystem (Project Root)];
    C -- Results/Data --> B;
    B -- MCP over Stdio --> A;

2. Key Technical Decisions & Patterns

• MCP SDK Usage: Leverages the @modelcontextprotocol/sdk for handling MCP communication (request parsing, response formatting, error handling). This standardizes interaction and reduces boilerplate code.
• Stdio Transport: Uses StdioServerTransport from the SDK for communication, suitable for running as a managed child process.
• Asynchronous Operations: All filesystem interactions and request handling are implemented using async/await and Node.js's promise-based fs module (fs.promises) for non-blocking I/O.
• Strict Path Resolution: A dedicated resolvePath function is used for every path received from the agent.
  • It normalizes the path.
  • It resolves the path relative to the server process's current working directory (process.cwd()), which is treated as the PROJECT_ROOT. Crucially, this requires the process launching the server (e.g., the agent host) to set the correct cwd for the target project.
  • It explicitly checks if the resolved absolute path still starts with the PROJECT_ROOT absolute path to prevent path traversal vulnerabilities (e.g., ../../sensitive-file).
  • It rejects absolute paths provided by the agent.
• Zod for Schemas & Validation: Uses zod library to define input schemas for tools and perform robust validation within each handler. JSON schemas for MCP listing are generated from Zod schemas.
• Tool Definition Aggregation: Tool definitions (name, description, Zod schema, handler function) are defined in their respective handler files and aggregated in src/handlers/index.ts for registration in src/index.ts.
• edit_file Logic:
  • Processes multiple changes per file, applying them sequentially from bottom-to-top to minimize line number conflicts.
  • Handles insertion, text replacement, and deletion.
  • Implements basic indentation detection (detect-indent) and preservation for insertions/replacements.
  • Uses diff library to generate unified diff output.
• Error Handling:
  • Uses try...catch blocks within each tool handler.
  • Catches specific Node.js filesystem errors (like ENOENT, EPERM, EACCES) and maps them to appropriate MCP error codes (InvalidRequest).
  • Uses custom McpError objects for standardized error reporting back to the agent.
  • Logs unexpected errors to the server's console (stderr) for debugging.
• Glob for Listing/Searching: Uses the glob library for flexible and powerful file listing and searching based on glob patterns, including recursive operations and stat retrieval. Careful handling of glob's different output types based on options (string[], Path[], Path[] with stats) is implemented.
• TypeScript: Provides static typing for better code maintainability, early error detection, and improved developer experience. Uses ES module syntax (import/export).
• PDF Parsing: Uses Mozilla's pdfjs-dist library to load PDF documents and extract text content, metadata, and page information. The read_pdf handler uses its API.

3. Component Relationships

• index.ts: Main entry point. Sets up the MCP server instance, defines tool schemas, registers request handlers, and starts the server connection.
• Server (from SDK): Core MCP server class handling protocol logic.
• StdioServerTransport (from SDK): Handles reading/writing MCP messages via stdio.
• Tool Handler Function (handleReadPdfFunc): Contains the logic for the consolidated read_pdf tool, including Zod argument validation, path resolution, PDF loading/parsing via pdfjs-dist, and result formatting based on input parameters.
• resolvePath Helper: Centralized security function for path validation.
• formatStats Helper: Utility to create a consistent stats object structure.
• Node.js Modules (fs, path): Used for actual filesystem operations and path manipulation.
• glob Library: Used for pattern-based file searching and listing.
• zod Library: Used for defining and validating tool input schemas.
• diff Library: (Inherited, but not used by PDF tools) Used by edit_file.
• detect-indent Library: (Inherited, but not used by PDF tools) Used by edit_file.
• pdfjs-dist Library: Used by the read_pdf handler to load and process PDF documents.