@mcpcn/mcp-pdf-reader

v1.1.6

Published

6 months ago

一个基于MCP协议的PDF阅读服务器，为AI代理提供安全的PDF文件读取和信息提取功能

0High
0Medium
0Low

mcp pdf reader text-extraction pdf-parsing ai-agent model-context-protocol llm-tool

PDF Reader MCP Server (@mcpcn/mcp-pdf-reader)

一个基于 Model Context Protocol (MCP) 的高性能 PDF 阅读服务器，专门为 AI 代理（如 Cline、Claude Desktop）提供安全可靠的 PDF 读取和提取信息（文本、元数据、页数）。

✨ 功能特点

📖 安全PDF阅读 - 严格限制访问项目根目录下的文件，确保安全性
🌐 多源支持 - 支持本地文件和在线URL两种PDF源
📄 灵活文本提取 - 支持全文提取或特定页面文本提取
📊 完整元数据获取 - 提取PDF文档信息和结构化元数据
📈 高效批量处理 - 并行处理多个PDF文件，显著提升性能
🚀 可靠PDF解析 - 基于 pdfjs-dist 库的企业级PDF解析
🔧 标准MCP集成 - 完全兼容MCP协议，无缝集成到AI工作流
🛡️ 输入验证 - 使用Zod进行严格的输入参数验证
⚡ 性能优化 - 智能字体加载优化和并行处理
🤖 智能依赖管理 - 自动检测和安装缺失的依赖，用户无需手动配置

🚀 快速开始

一键安装（推荐）

cd typescript/PDF阅读
npm run setup

这个命令会自动：

✅ 检查Node.js版本（需要>=18）
📦 安装所有必要依赖
🔨 编译TypeScript代码
🎉 准备服务运行环境

手动安装

如果一键安装失败，可以手动执行：

cd typescript/PDF阅读
npm install
npm run build

MCP 配置

Claude Desktop 配置 (macOS)

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": [
        "/path/to/your/skills/typescript/PDF阅读/dist/index.js"
      ]
    }
  }
}

Cline/Cursor 配置

在 Cursor 设置中的 MCP 服务器配置中添加：

{
  "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文件的完整内容

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./documents/report.pdf"
      }
    ],
    "include_metadata": true,
    "include_page_count": true,
    "include_full_text": true
  }
}

2. 提取特定页面内容

{
  "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

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "https://example.com/document.pdf"
      }
    ]
  }
}

4. 批量处理多个PDF

{
  "tool_name": "read_pdf",
  "arguments": {
    "sources": [
      {
        "path": "./docs/file1.pdf",
        "pages": [1, 2]
      },
      {
        "path": "./docs/file2.pdf"
      },
      {
        "path": "https://example.com/remote.pdf"
      }
    ]
  }
}

响应格式

成功响应示例：

{
  "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..."
      }
    }
  ]
}

特定页面响应示例：

{
  "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，实现了以下关键特性：

✅ Zod输入验证 - 严格的类型检查和参数验证，确保数据安全
✅ 并行处理 - 多文件并行处理，显著提升批量操作性能
✅ 错误隔离 - 单个文件错误不影响其他文件处理
✅ 内存优化 - 智能字体加载策略，减少内存占用
✅ 结构化输出 - 标准化的JSON响应格式，便于AI解析
✅ 安全沙箱 - 严格的路径验证，防止目录遍历攻击

性能优势

并行处理: 多PDF文件同时处理，而非顺序执行
智能缓存: PDF库延迟加载和复用
内存优化: 禁用不必要的标准字体加载
错误恢复: 健壮的错误处理不会中断整体流程

💻 对话示例

用户：请帮我读取桌面上的年度报告.pdf文件

助手：我来帮你读取PDF文件...

📖 PDF阅读完成！

📁 文件：年度报告.pdf
📊 页数：45页
📄 标题：2023年度财务报告
👤 作者：财务部

📝 内容摘要：
本报告包含公司2023年的完整财务状况...

用户：只需要第1页和第5页的内容

助手：我来提取特定页面的内容...

📖 已提取指定页面：

📄 第1页：
标题页内容...

📄 第5页：
财务数据概览...

⚠️ 注意事项

文件路径: 使用相对路径，确保文件在项目根目录下
文件格式: 支持标准PDF格式文件
网络访问: URL方式需要网络连接，可能需要较长加载时间
内存使用: 大文件处理时可能需要更多内存
编码支持: 支持UTF-8编码的文本提取

🔧 故障排除

常见问题

pdfjs-dist 加载失败错误
```
错误：无法加载 pdfjs-dist，请执行 npm install 并确保 Node 版本>=18
```
原因: pdfjs-dist 库加载失败或Node.js版本不兼容 解决方案:
- 自动解决: 服务会自动尝试多种加载策略和依赖安装
- 手动解决:
```
cd typescript/PDF阅读
rm -rf node_modules package-lock.json
npm install
npm run build
```
- 检查Node版本: 确保 Node.js >= 18.0.0
空页面数组错误
```
错误：输入参数验证失败: sources.0.pages: 如果指定pages数组，不能为空
```
原因: 传入了空的pages数组 "pages": [] 解决方案:
- 不指定pages参数（将提取全文）
- 或者指定具体页面 "pages": [1, 2, 3]
绝对路径访问错误
```
错误：绝对路径不安全或不是PDF文件: /Users/xxx/file.pdf
```
原因: 绝对路径安全检查失败 解决方案:
- 确保文件是PDF格式（.pdf扩展名）
- 确保路径不包含危险字符（如 .., ~/, $ 等）
- 如果可能，使用相对路径
文件不存在错误
```
错误：文件不存在: ./documents/report.pdf
```
解决方案: 检查文件路径是否正确，确保文件存在
路径安全错误
```
错误：文件路径不安全，只能访问项目根目录下的文件
```
解决方案: 使用相对路径，确保文件在项目根目录下
PDF解析错误
```
错误：无法解析PDF文件
```
解决方案: 确认PDF文件格式正确且未损坏
网络错误
```
错误：HTTP error! status: 404
```
解决方案: 检查URL是否正确且可访问
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 项目启发开发，实现了同等水平的功能特性。