PDF Reader MCP Server

📄 @sylphx/pdf阅读器mcp

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

](https://www.npmjs.com/package/@sylphx/pdf-reader-mcp)      ](https://www.npmjs.com/package/@sylphx/pdf-reader-mcp)

并行处理速度提高5-10倍 • Y坐标内容排序 • 94%+测试覆盖率 • 103项测试通过

______________________________________________________________________

🚀 概述

PDF阅读器MCP是 生产就绪 模型上下文协议服务器，为AI代理提供 企业级PDF处理能力。以无与伦比的性能和可靠性提取文本、图像和元数据。

问题：

// Traditional PDF processing
- Sequential page processing (slow)
- No natural content ordering
- Complex path handling
- Poor error isolation

解决方案：

// PDF Reader MCP
- 5-10x faster parallel processing ⚡
- Y-coordinate based ordering 📐
- Flexible path support (absolute/relative) 🎯
- Per-page error resilience 🛡️
- 94%+ test coverage ✅

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

______________________________________________________________________

⚡ 主要特点

演出

• 🚀 速度提高5-10倍 比顺序式自动并行化
• ⚡ 12933次/秒 错误处理，5575次操作/秒文本提取
• 💨 处理50页PDF 多核利用率在几秒钟内
• 📦 轻量级 依赖性最小

开发者体验

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

______________________________________________________________________

📊 性能基准

生产测试的真实性能：

并行处理速度加快

*基准因PDF复杂性和系统资源而异。*

______________________________________________________________________

📦 安装

克劳德代码

claude mcp add pdf-reader -- npx @sylphx/pdf-reader-mcp

克劳德桌面版

添加 claude_desktop_config.json:

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

📍 Config file locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

VS代码

code --add-mcp '{"name":"pdf-reader","command":"npx","args":["@sylphx/pdf-reader-mcp"]}'

光标

1. 打开 设置 → 主控程序 → 添加新的MCP服务器
2. 选择 命令 类型
3. 输入： npx @sylphx/pdf-reader-mcp

帆板运动

添加到您的Windsurf MCP配置中：

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

克莱恩

添加到Cline的MCP设置中：

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

弯曲

1. 首选 设置 → 人工智能 → 管理MCP服务器 → 添加
2. 命令： npx，Args： @sylphx/pdf-reader-mcp

Ontheia

在中添加服务器 设置 → MCP服务器 → 添加服务器 带命令 npx 和args @sylphx/pdf-reader-mcp。参见 Ontheia兼容的MCP服务器 查看完整列表。

Smithery（点击一下）

npx -y @smithery/cli install @sylphx/pdf-reader-mcp --client claude

手动安装

# Quick start - zero installation
npx @sylphx/pdf-reader-mcp

# Or install globally
npm install -g @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 - Both formats work!
{
  "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
}

不再 "Absolute paths are not allowed" 错误！

提取具有自然顺序的图像

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

答复包括：

• 文本和图像 精确的文件顺序 （Y坐标排序）
• 带元数据（宽度、高度、格式）的Base64编码图像
• 为人工智能理解保留自然阅读流

批处理

{
  "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-10x性能 -使用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" }

// ✅ Relative (still works)
{ "path": "documents/report.pdf" }

其他改进：

• 🐛 修复了Zod验证错误处理
• 📦 将所有依赖项更新为最新版本
• ✅ 103项测试通过，覆盖率保持在94%以上

📋 View Full Changelog

v1.2.0-内容排序

• 基于Y坐标的文本和图像排序
• 人工智能模型的自然阅读流程
• 智能线路分组

v1.1.0-图像提取和性能

• Base64编码图像提取
• 并行处理速度提高10倍
• 全面测试覆盖率（94%+）

查看完整变更日志→

______________________________________________________________________

📖 API 参考

read_pdf 工具

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

参数

源对象

{
  path?: string;        // Local file path (absolute or relative)
  url?: string;         // HTTP/HTTPS URL to PDF
  pages?: string | number[];  // Pages to extract: "1-5,10" or [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"  // Pages 1,2,3,4,5,10,11,12,13,14,15,20
  }]
}

______________________________________________________________________

🔧 高级用法

📐 Y-Coordinate Content Ordering

内容以基于Y坐标的自然读取顺序返回：

Document Layout:
┌─────────────────────┐
│ [Title]       Y:100 │
│ [Image]       Y:150 │
│ [Text]        Y:400 │
│ [Photo A]     Y:500 │
│ [Photo B]     Y:550 │
└─────────────────────┘

Response Order:
[
  { type: "text", text: "Title..." },
  { type: "image", data: "..." },
  { type: "text", text: "..." },
  { type: "image", data: "..." },
  { type: "image", data: "..." }
]

优点：

• AI理解空间关系
• 自然文档理解
• 非常适合视觉模型
• 自动多行文本分组

🖼️ Image Extraction

启用提取：

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

响应格式：

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

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

📂 Path Configuration

绝对路径 （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"
    }
  }
}

📊 Large PDF Strategies

策略1：页面范围

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

策略2：渐进式加载

// Step 1: Get page count
{ "sources": [{ "path": "big.pdf" }], "include_full_text": false }

// Step 2: Extract sections
{ "sources": [{ "path": "big.pdf", "pages": "50-75" }] }

策略3：并行批处理

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

______________________________________________________________________

🔒 安全和沙盒

默认情况下，服务器可以读取主机进程可以访问的任何本地文件，并获取任何HTTP（S）URL。在沙盒外运行时，您应该将其限制在特定的工作集内。

限制文件系统访问

使用 --allow-dir （可重复）或 MCP_PDF_ALLOWED_DIRS （env）: 或 , 分开）。一旦设置，所有 path 源必须在允许的目录之一内解析——相对路径、绝对路径和 .. 解析后都会检查遍历。

# CLI flags
npx @sylphx/pdf-reader-mcp --allow-dir=/srv/pdfs --allow-dir=/data/reports

# Environment
MCP_PDF_ALLOWED_DIRS="/srv/pdfs:/data/reports" npx @sylphx/pdf-reader-mcp

{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp", "--allow-dir=/srv/pdfs"]
    }
  }
}

禁用或限制HTTP

# Block all URL sources
npx @sylphx/pdf-reader-mcp --no-http
MCP_PDF_ALLOW_HTTP=false npx @sylphx/pdf-reader-mcp

# Allowlist hosts (everything else rejected)
npx @sylphx/pdf-reader-mcp --allow-host=cdn.example.com --allow-host=files.internal
MCP_PDF_ALLOWED_HOSTS="cdn.example.com,files.internal" npx @sylphx/pdf-reader-mcp

被拒绝的请求很快就会失败 Access denied 在任何磁盘读取或网络调用之前出错。

______________________________________________________________________

🔧 故障排除

“不允许绝对路径”

解决方案： 升级到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客户端。

______________________________________________________________________

🌐 HTTP传输（远程访问）

默认情况下，PDF阅读器MCP使用stdio传输进行本地使用。您还可以将其作为HTTP服务器运行，以便从多台机器进行远程访问。

快速开始

# Run as HTTP server on port 8080
MCP_TRANSPORT=http npx @sylphx/pdf-reader-mcp

环境变量

Docker部署

FROM oven/bun:1
WORKDIR /app
RUN bun add @sylphx/pdf-reader-mcp
ENV MCP_TRANSPORT=http
ENV MCP_HTTP_PORT=8080
EXPOSE 8080
CMD ["bun", "node_modules/@sylphx/pdf-reader-mcp/dist/index.js"]

MCP客户端配置（HTTP）

{
  "servers": {
    "pdf-reader": {
      "type": "http",
      "url": "https://your-server.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

端点

______________________________________________________________________

🏗️ 建筑

技术栈

设计原则

• 🔒 安全第一 -具有安全默认值的灵活路径
• 🎯 简单的界面 -一个工具，所有操作
• ⚡ 演出 -并行处理，高效内存
• 🛡️ 可靠性 -每页隔离，详细错误
• 🧪 质量 -94%以上的覆盖率，严格的TypeScript
• 📝 类型安全 -没有 any 类型，严格模式
• 🔄 向后兼容 -始终平稳升级

______________________________________________________________________

🧪 发展

Setup & Scripts

先决条件：

• Node.js>=22.0.0
• pnpm（推荐）或npm

设置：

git clone https://github.com/SylphxAI/pdf-reader-mcp.git
cd pdf-reader-mcp
pnpm install && pnpm build

脚本：

pnpm run build       # Build TypeScript
pnpm run test        # Run 103 tests
pnpm run test:cov    # Coverage (94%+)
pnpm run check       # Lint + format
pnpm run check:fix   # Auto-fix
pnpm run benchmark   # Performance tests

质量：

• ✅ 103测试
• ✅ 94%+覆盖率
• ✅ 98%+功能覆盖率
• ✅ 零皮棉错误
• ✅ 严格的TypeScript

Contributing

快速入门：

1. Fork存储库
2. 创建分支： git checkout -b feature/awesome
3. 进行更改： pnpm test
4. 格式： pnpm run check:fix
5. 提交：使用 常规承诺
6. 开启PR

提交格式：

feat(images): add WebP support
fix(paths): handle UNC paths
docs(readme): update examples

看 贡献.md

______________________________________________________________________

📚 文档

• 📖 完整文档 -完整指南
• 🚀 入门指南 -快速启动
• 📘 API 参考 -API详细信息
• 🏗️ 设计 -建筑
• ⚡ 演出 -基准
• 🔍 比较 -与替代品

______________________________________________________________________

🗺️ 路线图

✅ 完成

• \[x\] 图像提取（v1.1.0）
• \[x\] 5-10x并行加速（v1.1.0）
• \[x\] Y坐标排序（v1.2.0）
• \[x\] 绝对路径（v1.3.0）
• \[x\] 94%+测试覆盖率（v1.3.0）

🚀 下一步

• \[\]扫描PDF的OCR
• \[\]注释提取
• \[\]表单字段提取
• \[\]表检测
• \[\]100+MB流媒体
• \[\]高级缓存
• \[\]PDF生成

投票地点： 讨论

______________________________________________________________________

🏆 认可

特色：

• 铁匠铺 -MCP目录
• 格拉玛 -人工智能市场
• 艾女士 -安全性已验证

全球信赖 • 企业采用 • 战斗测试

______________________________________________________________________

🤝 支持

](https://github.com/SylphxAI/pdf-reader-mcp/issues) 

• 🐛 错误报告
• 💬 讨论
• 📖 文档
• 📧 电子邮件

表示支持： ⭐ 明星•👀 观看•🐛 报告错误•💡 建议功能•🔀 贡献

______________________________________________________________________

📊 统计

103测试 • 94%+覆盖率 • 生产就绪

______________________________________________________________________

📄 许可证

MIT© Sylphx

______________________________________________________________________

🙏 学分

内置：

• PDF.js -Mozilla PDF引擎
• 包子 -快速JavaScript运行时

特别感谢开源社区❤️

由Sylphx提供技术支持

此项目使用以下内容 @sylphx 包装：

• @sylphx/mcp服务器sdk -MCP服务器框架
• @sylphx/vex -架构验证
• @sylphx/biome配置 -生物特征配置
• @sylphx/tsconfig -TypeScript配置
• @sylphx/bump -版本管理
• @sylphx/医生 -项目健康检查器

______________________________________________________________________

明星历史


______________________________________________________________________

Built with ❤️ by Sylphx