📄 @sylphx/pdf-reader-mcp

面向 AI Agent 的生产级 PDF 处理服务器

5-10 倍并行处理加速 • 基于 Y 轴坐标的内容排序 • 94%+ 测试覆盖率 • 103 项测试通过

---

🚀 项目概述

PDF Reader MCP 是一个生产级的模型上下文协议（Model Context Protocol）服务器，旨在为 AI Agent 提供企业级的 PDF 处理能力。以卓越的性能和可靠性提取文本、图像及元数据。

痛点：

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

解决方案：

// PDF Reader MCP
- 5-10 倍并行处理加速 ⚡
- 基于 Y 轴坐标的内容排序 📐
- 灵活的路径支持（绝对/相对） 🎯
- 单页面级错误恢复能力 🛡️
- 94%+ 测试覆盖率 ✅

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

---

⚡ 核心特性

性能

• 🚀 5-10 倍提速：通过自动并行化处理，比顺序处理快 5-10 倍
• ⚡ 高效处理：12,933 ops/sec 的错误处理能力，5,575 ops/sec 的文本提取速度
• 💨 极速体验：利用多核能力，数秒内处理 50 页 PDF
• 📦 轻量级：依赖项极少

开发体验

• 🎯 路径灵活：支持绝对路径与相对路径，兼容 Windows/Unix (v1.3.0)
• 🖼️ 智能排序：基于 Y 轴坐标的内容排序，完美保留文档原始布局
• 🛡️ 类型安全：采用严格模式的 TypeScript 编写
• 📚 久经考验：103 项测试，94%+ 代码覆盖率，98%+ 函数覆盖率
• 🎨 简洁 API：单一工具即可优雅处理所有操作

---

📊 性能基准测试

生产环境下的真实性能表现：

操作	Ops/sec	性能等级	使用场景
错误处理	12,933	⚡⚡⚡⚡⚡	验证与安全性
全量文本提取	5,575	⚡⚡⚡⚡	文档分析
单页提取	5,329	⚡⚡⚡⚡	单页操作
多页处理	5,242	⚡⚡⚡⚡	批量处理
仅元数据	4,912	⚡⚡⚡	快速检查

并行处理加速比

文档规模	顺序处理	并行处理	加速效果
10 页 PDF	~2s	~0.3s	5-8 倍提升
50 页 PDF	~10s	~1s	10 倍提升
100+ 页	~20s	~2s	随 CPU 核心数线性扩展

性能基准会根据 PDF 复杂度和系统资源有所波动。

---

📦 安装指南

Claude Code

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

Claude Desktop

在 claude_desktop_config.json 中添加：

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

📍 配置文件位置

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

VS Code

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

Cursor

1. 进入 Settings → MCP → Add new MCP Server
2. 选择 Command 类型
3. 输入: npx @sylphx/pdf-reader-mcp

Windsurf

添加到 Windsurf MCP 配置：

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

Cline

添加到 Cline 的 MCP 设置中：

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

Warp

1. 前往 Settings → AI → Manage MCP Servers → Add
2. Command: npx, Args: @sylphx/pdf-reader-mcp

Smithery (一键安装)

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

手动安装

# 快速启动 - 无需安装
npx @sylphx/pdf-reader-mcp

# 或全局安装
npm install -g @sylphx/pdf-reader-mcp

---

🎯 快速入门