STARWARCLOUD STARWAR.AI
返回市场
pdf阅读器-mcp

pdf阅读器-mcp

作者：SylphxAI333 星标更新：2025-11-23
安装使用来源：spider==github.com

项目介绍

<div align="center">

PDF Reader MCP 📄

生产就绪的AI代理PDF处理服务器

CI/CD codecov npm version coverage Downloads License

5-10倍更快的并行处理 • 基于Y坐标的排序 • 超过94%的测试覆盖率 • 103个通过的测试

<a href="https://mseep.ai/app/SylphxAI-pdf-reader-mcp"> <img src="https://mseep.net/pr/SylphxAI-pdf-reader-mcp-badge.png" alt="安全验证" width="200"/> </a> </div>

🚀 概述

PDF Reader MCP 是一个生产就绪的模型上下文协议服务器，它赋予AI代理企业级的PDF处理能力。提取文本、图像和元数据时具有无与伦比的性能和可靠性。

问题：

// 传统的PDF处理
- 顺序页面处理（慢）
- 没有自然内容排序
- 复杂路径处理
- 错误隔离差

解决方案：

// PDF Reader MCP
- 5-10倍更快的并行处理 ⚡
- 基于Y坐标的排序 📐
- 灵活的路径支持（绝对/相对） 🎯
- 单页错误恢复 🛡️
- 超过94%的测试覆盖率 ✅

结果：可扩展的生产就绪PDF处理。

⚡ 关键特性

性能

  • 🚀 比顺序处理快5-10倍 自动并行化
  • ⚡ 每秒12,933次操作 错误处理，每秒5,575次操作文本提取
  • 💨 几秒钟内处理50页PDF 利用多核
  • 📦 轻量级 依赖少

开发者体验

  • 🎯 路径灵活性 - 绝对及相对路径，Windows/Unix支持（v1.3.0）
  • 🖼️ 智能排序 - 基于Y坐标的内容保留文档布局
  • 🛡️ 类型安全 - 完整的TypeScript，启用严格模式
  • 📚 经受考验 - 103个测试，超过94%的覆盖率，超过98%的功能覆盖率
  • 🎨 简单的API - 单一工具优雅地处理所有操作

📊 性能基准

来自生产测试的真实世界性能：

操作每秒操作数性能使用案例
错误处理12,933⚡⚡⚡⚡⚡验证与安全性
提取全文5,575⚡⚡⚡⚡文档分析
提取单页5,329⚡⚡⚡⚡单页操作
多页5,242⚡⚡⚡⚡批量处理
仅元数据4,912⚡⚡⚡快速检查

并行处理加速

文档顺序并行加速
10页PDF~2秒~0.3秒5-8倍更快
50页PDF~10秒~1秒10倍更快
100+页~20秒~2秒线性扩展 随CPU核心数量增加

基准测试根据PDF复杂性和系统资源而变化。

📦 安装

# 快速开始 - 零安装
npx @sylphx/pdf-reader-mcp

# 使用pnpm（推荐）
pnpm add @sylphx/pdf-reader-mcp

# 使用npm
npm install @sylphx/pdf-reader-mcp

# 使用yarn
yarn add @sylphx/pdf-reader-mcp

# 对于Claude Desktop（最简单）
npx -y @smithery/cli install @sylphx/pdf-reader-mcp --client claude

🎯 快速开始

配置

添加到您的MCP客户端（claude_desktop_config.json，Cursor，Cline）：

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

基本使用

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

结果：

  • ✅ 提取全文内容
  • ✅ PDF元数据（作者，标题，日期）
  • ✅ 总页数
  • ✅ 结构共享 - 保留未更改的部分

提取特定页面

{
  "sources": [{
    "path": "documents/manual.pdf",
    "pages": "1-5,10,15-20"
  }],
  "include_full_text": true
}

绝对路径（v1.3.0+）

// Windows - 两种格式都有效！
{
  "sources": [{
    "path": "C:\\Users\\John\\Documents\\report.pdf"
  }],
  "include_full_text": true
}

// Unix/Mac
{
  "sources": [{
    "path": "/home/user/documents/contract.pdf"
  }],
  "include_full_text": true
}

不再有 "绝对路径不允许" 错误！

提取自然排序的图像

{
  "sources": [{
    "path": "presentation.pdf",
    "pages": [1, 2, 3]
  }],
  "include_images": true,
  "include_full_text": true
}

响应包括：

  • 按精确文档顺序排列的文本和图像（按Y坐标排序）
  • 带有元数据（宽度，高度，格式）的Base64编码图像
  • 保留自然阅读流以供AI理解

批量处理

{
  "sources": [
    { "path": "C:\\Reports\\Q1.pdf", "pages": "1-10" },
    { "path": "/home/user/Q2.pdf", "pages": "1-10" },
    { "url": "https://example.com/Q3.pdf" }
  ],
  "include_full_text": true
}

⚡ 所有PDF自动并行处理！

✨ 功能

核心功能

  • ✅ 文本提取 - 整个文档或特定页面，带有智能解析
  • ✅ 图像提取 - 带有完整元数据（宽度，高度，格式）的Base64编码
  • ✅ 内容排序 - 基于Y坐标的布局保存，以实现自然阅读流
  • ✅ 元数据提取 - 作者，标题，创建日期和自定义属性
  • ✅ 页码计数 - 快速枚举，无需加载全部内容
  • ✅ 双源 - 本地文件（绝对或相对路径）和HTTP/HTTPS URL
  • ✅ 批量处理 - 并发处理多个PDF

高级功能

  • ⚡ 5-10倍性能 - 使用Promise.all进行并行页面处理
  • 🎯 智能分页 - 提取范围如“1-5,10-15,20”
  • 🖼️ 多种格式图像 - RGB，RGBA，灰度，自动检测
  • 🛡️ 路径灵活性 - 支持Windows，Unix和相对路径（v1.3.0）
  • 🔍 错误恢复 - 每页错误隔离，详细消息
  • 📏 大文件支持 - 高效流式传输和内存管理
  • 📝 类型安全 - 完整的TypeScript，启用严格模式

🆕 v1.3.0 新功能

🎉 现在支持绝对路径！

// ✅ Windows
{ "path": "C:\\Users\\John\\Documents\\report.pdf" }
{ "path": "C:/Users/John/Documents/report.pdf" }

// ✅ Unix/Mac
{ "path": "/home/john/documents/report.pdf" }
{ "path": "/Users/john/Documents/report.pdf" }

// ✅ 相对路径（仍然有效）
{ "path": "documents/report.pdf" }

其他改进：

  • 🐛 修复了Zod验证错误处理
  • 📦 更新所有依赖项到最新版本
  • ✅ 103个测试通过，保持超过94%的覆盖率
<details> <summary><strong>📋 查看完整变更日志</strong></summary> <br/>

v1.2.0 - 内容排序

  • 基于Y坐标的文本和图像排序
  • 用于AI模型的自然阅读流
  • 智能行分组

v1.1.0 - 图像提取与性能

  • Base64编码的图像提取
  • 并行处理速度提升10倍
  • 全面的测试覆盖（超过94%）

查看完整变更日志 →

</details>

📖 API 参考

read_pdf 工具

单一工具处理所有PDF操作。

参数

参数类型描述默认值
sources数组要处理的PDF源列表必需
include_full_text布尔值提取全文内容false
include_metadata布尔值提取PDF元数据true
include_page_count布尔值包含总页数true
include_images布尔值提取嵌入图像false

源对象

{
  path?: string;        // 本地文件路径（绝对或相对）
  url?: string;         // PDF的HTTP/HTTPS URL
  pages?: string | number[];  // 要提取的页面：“1-5,10”或[1,2,3]
}

示例

仅元数据（快速）：

{
  "sources": [{ "path": "large.pdf" }],
  "include_metadata": true,
  "include_page_count": true,
  "include_full_text": false
}

从URL：

{
  "sources": [{
    "url": "https://arxiv.org/pdf/2301.00001.pdf"
  }],
  "include_full_text": true
}

页面范围：

{
  "sources": [{
    "path": "manual.pdf",
    "pages": "1-5,10-15,20"  // 页面1,2,3,4,5,10,11,12,13,14,15,20
  }]
}

🔧 高级用法

<details> <summary><strong>📐 基于Y坐标的排序</strong></summary> <br/>

内容按照自然阅读顺序返回，基于Y坐标：

文档布局：
┌─────────────────────┐
│ [标题]       Y:100 │
│ [图像]       Y:150 │
│ [文本]        Y:400 │
│ [照片A]     Y:500 │
│ [照片B]     Y:550 │
└─────────────────────┘

响应顺序：
[
  { type: "text", text: "标题..." },
  { type: "image", data: "..." },
  { type: "text", text: "..." },
  { type: "image", data: "..." },
  { type: "image", data: "..." }
]

优点：

  • AI理解空间关系
  • 自然文档理解
  • 适合视觉增强模型
  • 自动多行文本分组
</details> <details> <summary><strong>🖼️ 图像提取</strong></summary> <br/>

启用提取：

{
  "sources": [{ "path": "manual.pdf" }],
  "include_images": true
}

响应格式：

{
  "images": [{
    "page": 1,
    "index": 1,
    "width": 1920,
    "height": 1080,
    "format": "rgb",
    "data": "base64-encoded-png..."
  }]
}

支持的格式： RGB，RGBA，灰度 自动检测： JPEG，PNG和其他嵌入格式

</details> <details> <summary><strong>📂 路径配置</strong></summary> <br/>

绝对路径（v1.3.0+） - 直接文件访问：

{ "path": "C:\\Users\\John\\file.pdf" }
{ "path": "/home/user/file.pdf" }

相对路径 - 工作区文件：

{ "path": "docs/report.pdf" }
{ "path": "./2024/Q1.pdf" }

配置工作目录：

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"],
      "cwd": "/path/to/documents"
    }
  }
}
</details> <details> <summary><strong>📊 大PDF策略</strong></summary> <br/>

策略1：页面范围

{ "sources": [{ "path": "big.pdf", "pages": "1-20" }] }

策略2：渐进加载

// 步骤1：获取页数
{ "sources": [{ "path": "big.pdf" }], "include_full_text": false }

// 步骤2：提取部分
{ "sources": [{ "path": "big.pdf", "pages": "50-75" }] }

策略3：并行批处理

{
  "sources": [
    { "path": "big.pdf", "pages": "1-50" },
    { "path": "big.pdf", "pages": "51-100" }
  ]
}
</details>

🔧 故障排除

“绝对路径不允许”

解决方案： 升级到v1.3.0+

npm update @sylphx/pdf-reader-mcp

完全重启您的MCP客户端。

“文件未找到”

原因：

  • 文件不存在于路径中
  • 错误的工作目录
  • 权限问题

解决方案：

使用绝对路径：

{ "path": "C:\\Full\\Path\\file.pdf" }

或者配置cwd：

{
  "pdf-reader-mcp": {
    "command": "npx",
    "args": ["@sylphx/pdf-reader-mcp"],
    "cwd": "/path/to/docs"
  }
}

“没有显示工具”

解决方案：

npm cache clean --force
rm -rf node_modules package-lock.json
npm install @sylphx/pdf-reader-mcp@latest

完全重启MCP客户端。

🏗️ 架构

技术栈

组件技术
运行时Node.js 22+ ESM
PDF引擎PDF.js (Mozilla)
验证Zod + JSON Schema
协议MCP SDK
语言TypeScript (严格)
测试Vitest (103个测试)
质量Biome (50倍更快)
CI/CDGitHub Actions

设计原则

  • 🔒 安全第一 - 灵活的路径，安全默认设置
  • 🎯 简单的接口 - 一个工具，所有操作
  • ⚡ 性能 - 并行处理，高效内存
  • 🛡️ 可靠性 - 每页隔离，详细错误
  • 🧪 质量 - 超过94%的覆盖率，严格的TypeScript
  • 📝 类型安全 - 没有any类型，严格模式
  • 🔄 **