95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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.
|