📄 @sylphx/pdf阅读器mcp

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

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

---

🚀 概述

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

问题：

TYPESCRIPT``` 1 2 3 4 5// Traditional PDF processing

• Sequential page processing (slow)
• No natural content ordering
• Complex path handling
• Poor error isolation

**解决方案：**


TYPESCRIPT```
1
2
3
4
5
6// 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 -单一工具优雅地处理所有操作

---

📊 性能基准

生产测试的真实性能：

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

并行处理速度加快

文档	顺序	并行	加速
10页PDF	~2s	~0.3s	速度快5-8倍
50页PDF	~10s	~1s	快10倍
100+页	约20秒	约2秒	线性缩放 配备CPU内核

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

---

📦 安装

克劳德代码

BASH``` 1claude mcp add pdf-reader — npx @sylphx/pdf-reader-mcp

### 克劳德桌面版


添加到 `claude_desktop_config.json`:


JSON```
1
2
3
4
5
6
7
8{
  "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

BASH``` 1code —add-mcp ’{“name”:“pdf-reader”,“command”:“npx”,“args”:[“@sylphx/pdf-reader-mcp”]}‘

### 光标


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


### 帆板运动


添加到您的Windsurf MCP配置中：


JSON```
1
2
3
4
5
6
7
8{
  "mcpServers": {
    "pdf-reader": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"]
    }
  }
}

克莱恩

添加到Cline的MCP设置中：

JSON``` 1 2 3 4 5 6 7 8{ “mcpServers”: { “pdf-reader”: { “command”: “npx”, “args”: [“@sylphx/pdf-reader-mcp”] } } }

### 曲速


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


### Smithery（点击一下）


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

手动安装

BASH``` 1 2 3 4# Quick start - zero installation npx @sylphx/pdf-reader-mcp

Or install globally

npm install -g @sylphx/pdf-reader-mcp

---


## 🎯 快速开始


### 基本用法


JSON```
1
2
3
4
5
6
7
8{
  "sources": [{
    "path": "documents/report.pdf"
  }],
  "include_full_text": true,
  "include_metadata": true,
  "include_page_count": true
}

结果：

• ✅ 已提取全文内容
• ✅ PDF元数据（作者、标题、日期）
• ✅ 总页数
• ✅ 结构共享-保留不变的零件

提取特定页面

JSON``` 1 2 3 4 5 6 7{ “sources”: [{ “path”: “documents/manual.pdf”, “pages”: “1-5,10,15-20” }], “include_full_text”: true }

### 绝对路径（v1.3.0+）


JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14// 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" 错误！

提取具有自然顺序的图像

JSON``` 1 2 3 4 5 6 7 8{ “sources”: [{ “path”: “presentation.pdf”, “pages”: [1, 2, 3] }], “include_images”: true, “include_full_text”: true }

**答复包括：**


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


### 批处理


JSON```
1
2
3
4
5
6
7
8{
  "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的新增功能

🎉 现在支持绝对路径！

JSON``` 1 2 3 4 5 6 7 8// ✅ 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操作的单一工具。


#### 参数


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


#### 源对象


TYPESCRIPT```
1
2
3
4
5{
  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]
}

例子

仅元数据（快速）：

JSON``` 1 2 3 4 5 6{ “sources”: [{ “path”: “large.pdf” }], “include_metadata”: true, “include_page_count”: true, “include_full_text”: false }

**来自URL：**


JSON```
1
2
3
4
5
6{
  "sources": [{
    "url": "https://arxiv.org/pdf/2301.00001.pdf"
  }],
  "include_full_text": true
}

页面范围：

JSON``` 1 2 3 4 5 6{ “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坐标的自然读取顺序返回：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16Document 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**


**启用提取：**


JSON```
1
2
3
4{
  "sources": [{ "path": "manual.pdf" }],
  "include_images": true
}

响应格式：

JSON``` 1 2 3 4 5 6 7 8 9 10{ “images”: [{ “page”: 1, “index”: 0, “width”: 1920, “height”: 1080, “format”: “rgb”, “data”: “base64-encoded-png…” }] }

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




**📂 Path Configuration**


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


JSON```
1
2{ "path": "C:\\Users\\John\\file.pdf" }
{ "path": "/home/user/file.pdf" }

相对路径 -工作区文件：

JSON``` 1 2{ “path”: “docs/report.pdf” } { “path”: ”./2024/Q1.pdf” }

**配置工作目录：**


JSON```
1
2
3
4
5
6
7
8
9{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphx/pdf-reader-mcp"],
      "cwd": "/path/to/documents"
    }
  }
}

📊 Large PDF Strategies

策略1：页面范围

JSON``` 1{ “sources”: [{ “path”: “big.pdf”, “pages”: “1-20” }] }

**策略2：渐进式加载**


JSON```
1
2
3
4// 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：并行批处理

JSON``` 1 2 3 4 5 6{ “sources”: [ { “path”: “big.pdf”, “pages”: “1-50” }, { “path”: “big.pdf”, “pages”: “51-100” } ] }

---


## 🔧 故障排除


### “不允许绝对路径”


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


BASH```
1npm update @sylphx/pdf-reader-mcp

完全重新启动MCP客户端。

---

“找不到文件”

原因：

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

解决：

使用绝对路径：

JSON``` 1{ “path”: “C:\Full\Path\file.pdf” }

或配置 `cwd`:


JSON```
1
2
3
4
5
6
7{
  "pdf-reader-mcp": {
    "command": "npx",
    "args": ["@sylphx/pdf-reader-mcp"],
    "cwd": "/path/to/docs"
  }
}

---

“没有工具显示”

解决方案：

BASH``` 1 2 3npm cache clean —force rm -rf node_modules package-lock.json npm install @sylphx/pdf-reader-mcp@latest

完全重新启动MCP客户端。



---


## 🌐 HTTP传输（远程访问）


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


### 快速开始


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

环境变量

变量	默认值	描述
MCP_TRANSPORT	stdio	运输类型： stdio 或 http
MCP_HTTP_PORT	8080	HTTP服务器端口
MCP_HTTP_HOST	0.0.0.0	HTTP服务器主机名
MCP_API_KEY	-	用于身份验证的可选API密钥

Docker部署

DOCKERFILE``` 1 2 3 4 5 6 7FROM 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）


JSON```
1
2
3
4
5
6
7
8
9
10
11{
  "servers": {
    "pdf-reader": {
      "type": "http",
      "url": "https://your-server.com/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

端点

端点	方法	描述
/mcp	POST	JSON-RPC端点
/mcp/health	GET	健康检查

---

🏗️ 建筑

技术栈

组件	技术
运行时	Node.js 22+ESM
PDF引擎	PDF.js（Mozilla）
验证	Zod+JSON模式
协议	MCP-SDK
语言	TypeScript（严格）
测试	Vitest（103次测试）
质量	生物识别（快50倍）
CI/CD	GitHub操作

设计原则

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

---

🧪 发展

Setup & Scripts

先决条件：

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

设置：

BASH``` 1 2 3git clone https://github.com/SylphxAI/pdf-reader-mcp.git cd pdf-reader-mcp pnpm install && pnpm build

**脚本：**


BASH```
1
2
3
4
5
6pnpm 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

提交格式：

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

看 贡献.md

---

📚 文档

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

---

🗺️ 路线图

✅ 完成

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

🚀 下一步

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

投票地点： 讨论

---

🏆 认可

特色：

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

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

---

🤝 支持

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

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

---

📊 统计

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