npm package: @mcpcn/mcp-pdf-reader
Description: 一个基于MCP协议的PDF阅读服务器，为AI代理提供安全的PDF文件读取和信息提取功能
Latest version: 1.1.6

# PDF Reader MCP Server (@mcpcn/mcp-pdf-reader)

一个基于 Model Context Protocol (MCP) 的高性能 PDF 阅读服务器，专门为 AI 代理（如 Cline、Claude Desktop）提供安全可靠的 PDF 读取和提取信息（文本、元数据、页数）。

![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-43853D?style=flat&logo=node.js&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-Compatible-blue)
![Zod](https://img.shields.io/badge/Zod-Validation-green)

## ✨ 功能特点

- 📖 **安全PDF阅读** - 严格限制访问项目根目录下的文件，确保安全性
- 🌐 **多源支持** - 支持本地文件和在线URL两种PDF源
- 📄 **灵活文本提取** - 支持全文提取或特定页面文本提取
- 📊 **完整元数据获取** - 提取PDF文档信息和结构化元数据
- 📈 **高效批量处理** - 并行处理多个PDF文件，显著提升性能
- 🚀 **可靠PDF解析** - 基于 pdfjs-dist 库的企业级PDF解析
- 🔧 **标准MCP集成** - 完全兼容MCP协议，无缝集成到AI工作流
- 🛡️ **输入验证** - 使用Zod进行严格的输入参数验证
- ⚡ **性能优化** - 智能字体加载优化和并行处理
- 🤖 **智能依赖管理** - 自动检测和安装缺失的依赖，用户无需手动配置

## 🚀 快速开始

### 一键安装（推荐）

```bash
cd typescript/PDF阅读
npm run setup
```

这个命令会自动：
- ✅ 检查Node.js版本（需要>=18）
- 📦 安装所有必要依赖
- 🔨 编译TypeScript代码
- 🎉 准备服务运行环境

### 手动安装

如果一键安装失败，可以手动执行：

```bash
cd typescript/PDF阅读
npm install
npm run build
```

### MCP 配置

#### Claude Desktop 配置 (macOS)

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": [
        "/path/to/your/skills/typescript/PDF阅读/dist/index.js"
      ]
    }
  }
}
```

#### Cline/Cursor 配置

在 Cursor 设置中的 MCP 服务器配置中添加：

```json
{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": [
        "path/to/your/skills/typescript/PDF阅读/dist/index.js"
      ],
      "autoApprove":["read_pdf"]
    }
  }
}
```

## 🔧 使用说明

### read_pdf 工具

**功能：** 读取PDF文件内容，提取文本、元数据和页数信息

**参数：**

- `sources` (必需): PDF源文件数组
  - `path` (必需): PDF文件路径（本地路径或URL）
  - `pages` (可选): 要提取的特定页面数组，如 [1, 2, 3]
- `include_metadata` (可选): 是否包含PDF元数据，默认 true
- `include_page_count` (可选): 是否包含页数统计，默认 true
- `include_full_text` (可选): 是否包含完整文本内容，默认 true

### 使用示例

#### 1. 读取本地PDF文件的完整内容

```json
{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./documents/report.pdf"
      }
    ],
    "include_metadata": true,
    "include_page_count": true,
    "include_full_text": true
  }
}
```

#### 2. 提取特定页面内容

```json
{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./documents/manual.pdf",
        "pages": [1, 3, 5]
      }
    ],
    "include_metadata": false,
    "include_page_count": false,
    "include_full_text": false
  }
}
```

#### 3. 从URL读取PDF

```json
{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "https://example.com/document.pdf"
      }
    ]
  }
}
```

#### 4. 批量处理多个PDF

```json
{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./docs/file1.pdf",
        "pages": [1, 2]
      },
      {
        "path": "./docs/file2.pdf"
      },
      {
        "path": "https://example.com/remote.pdf"
      }
    ]
  }
}
```

### 响应格式

成功响应示例：

```json
{
  "results": [
    {
      "source": "./documents/report.pdf",
      "success": true,
      "data": {
        "num_pages": 25,
        "info": {
          "Title": "Annual Report 2023",
          "Author": "Company Name",
          "CreationDate": "D:20231215120000Z"
        },
        "metadata": {
          "dc:title": "Annual Report 2023"
        },
        "full_text": "This is the extracted text content from the PDF..."
      }
    }
  ]
}
```

特定页面响应示例：

```json
{
  "results": [
    {
      "source": "./documents/manual.pdf",
      "success": true,
      "data": {
        "num_pages": 100,
        "page_texts": [
          {
            "page": 1,
            "text": "Page 1 content..."
          },
          {
            "page": 3,
            "text": "Page 3 content..."
          }
        ]
      }
    }
  ]
}
```

## 🔒 安全特性

- **路径限制**: 只能访问项目根目录及其子目录下的文件
- **协议限制**: URL仅支持HTTP/HTTPS协议
- **文件验证**: 自动验证文件存在性和可读性
- **错误处理**: 完善的错误捕获和友好的错误信息

## 🎯 技术亮点

### 与 sylphxltd/pdf-reader-mcp 同等水平

本项目参考了开源项目 [sylphxltd/pdf-reader-mcp](https://github.com/sylphxltd/pdf-reader-mcp)，实现了以下关键特性：

- ✅ **Zod输入验证** - 严格的类型检查和参数验证，确保数据安全
- ✅ **并行处理** - 多文件并行处理，显著提升批量操作性能
- ✅ **错误隔离** - 单个文件错误不影响其他文件处理
- ✅ **内存优化** - 智能字体加载策略，减少内存占用
- ✅ **结构化输出** - 标准化的JSON响应格式，便于AI解析
- ✅ **安全沙箱** - 严格的路径验证，防止目录遍历攻击

### 性能优势

- **并行处理**: 多PDF文件同时处理，而非顺序执行
- **智能缓存**: PDF库延迟加载和复用
- **内存优化**: 禁用不必要的标准字体加载
- **错误恢复**: 健壮的错误处理不会中断整体流程

## 💻 对话示例

```
用户：请帮我读取桌面上的年度报告.pdf文件

助手：我来帮你读取PDF文件...

📖 PDF阅读完成！

📁 文件：年度报告.pdf
📊 页数：45页
📄 标题：2023年度财务报告
👤 作者：财务部

📝 内容摘要：
本报告包含公司2023年的完整财务状况...

用户：只需要第1页和第5页的内容

助手：我来提取特定页面的内容...

📖 已提取指定页面：

📄 第1页：
标题页内容...

📄 第5页：
财务数据概览...
```

## ⚠️ 注意事项

1. **文件路径**: 使用相对路径，确保文件在项目根目录下
2. **文件格式**: 支持标准PDF格式文件
3. **网络访问**: URL方式需要网络连接，可能需要较长加载时间
4. **内存使用**: 大文件处理时可能需要更多内存
5. **编码支持**: 支持UTF-8编码的文本提取

## 🔧 故障排除

### 常见问题

1. **pdfjs-dist 加载失败错误**
   ```
   错误：无法加载 pdfjs-dist，请执行 npm install 并确保 Node 版本>=18
   ```
   **原因**: pdfjs-dist 库加载失败或Node.js版本不兼容
   **解决方案**: 
   - **自动解决**: 服务会自动尝试多种加载策略和依赖安装
   - **手动解决**: 
     ```bash
     cd typescript/PDF阅读
     rm -rf node_modules package-lock.json
     npm install
     npm run build
     ```
   - **检查Node版本**: 确保 Node.js >= 18.0.0
   
2. **空页面数组错误**
   ```
   错误：输入参数验证失败: sources.0.pages: 如果指定pages数组，不能为空
   ```
   **原因**: 传入了空的pages数组 `"pages": []`
   **解决方案**: 
   - 不指定pages参数（将提取全文）
   - 或者指定具体页面 `"pages": [1, 2, 3]`

3. **绝对路径访问错误**
   ```
   错误：绝对路径不安全或不是PDF文件: /Users/xxx/file.pdf
   ```
   **原因**: 绝对路径安全检查失败
   **解决方案**: 
   - 确保文件是PDF格式（.pdf扩展名）
   - 确保路径不包含危险字符（如 `..`, `~/`, `$` 等）
   - 如果可能，使用相对路径

4. **文件不存在错误**
   ```
   错误：文件不存在: ./documents/report.pdf
   ```
   **解决方案**: 检查文件路径是否正确，确保文件存在

5. **路径安全错误**
   ```
   错误：文件路径不安全，只能访问项目根目录下的文件
   ```
   **解决方案**: 使用相对路径，确保文件在项目根目录下

6. **PDF解析错误**
   ```
   错误：无法解析PDF文件
   ```
   **解决方案**: 确认PDF文件格式正确且未损坏

7. **网络错误**
   ```
   错误：HTTP error! status: 404
   ```
   **解决方案**: 检查URL是否正确且可访问

8. **Node.js版本问题**
   ```
   错误：需要 Node.js 版本 >= 18
   ```
   **解决方案**: 升级Node.js到18或更高版本

## 📝 开发信息

- **框架**: Model Context Protocol (MCP) SDK
- **PDF解析**: pdfjs-dist
- **文件操作**: fs-extra
- **输入验证**: Zod
- **Node.js版本**: >= 18.0.0
- **TypeScript版本**: >= 5.6.0

## 🔄 更新日志

### v1.1.1 (最新版本) - 错误修复版本
- 🔧 **修复 pdfjs-dist 加载失败** - 改进加载策略，支持多种导入方式
- 🔧 **支持绝对路径访问** - 允许安全的绝对路径PDF文件访问
- 🔧 **修复空页面数组处理** - 使用Zod验证拒绝空pages数组
- 🔧 **增强错误诊断** - 详细的错误信息和调试输出
- 🔧 **改进Node.js版本检查** - 更准确的版本兼容性检测
- 🔧 **优化依赖管理** - 更智能的自动安装和错误恢复

### v1.1.0
- ✅ 添加 Zod 输入验证，提高参数安全性
- ✅ 实现并行处理，显著提升批量PDF处理性能  
- ✅ 优化错误处理和响应格式
- ✅ 增强安全性检查和路径验证
- ✅ 改进内存使用和性能优化
- ✅ 更新依赖到最新版本
- ✅ 与 sylphxltd/pdf-reader-mcp 项目功能对标

### v1.0.1
- 基础PDF阅读功能实现
- 自动依赖管理
- 本地文件和URL支持

## 📄 许可证

本项目采用 MIT 许可证。

---

基于 [sylphxltd/pdf-reader-mcp](https://github.com/sylphxltd/pdf-reader-mcp) 项目启发开发，实现了同等水平的功能特性。