MCP PDF Reader

<div align="center">

🚀 基于 Model Context Protocol 的智能 PDF 处理服务器

功能强大 · 易于使用 · 智能识别

快速开始 · 功能特性 · 使用指南 · 配置说明

</div>

---

📖 项目简介

MCP PDF Reader 是一个专业的 PDF 文档处理工具，通过 Model Context Protocol (MCP) 为 AI 应用提供强大的 PDF 文本提取、搜索、OCR 识别等功能。它能够智能识别 PDF 类型，自动选择最佳处理策略，为用户提供高效便捷的文档处理体验。

🎯 核心优势

• 🤖 智能识别：自动判断 PDF 类型（文本型/扫描型），选择最佳处理方案
• 🔍 强大搜索：支持正则表达式、全字匹配、大小写敏感搜索
• 📊 完整元数据：提取作者、标题、创建日期等 13 项元数据
• 🌏 多语言 OCR：支持中文、英文、日文、韩文等 10 种语言识别
• ⚡ 高性能：令牌缓存机制、智能错误处理、并发保护、使用文件缓存重复读取pdf文件不消耗API调用
• 🛡️ 安全可靠：文件大小限制、路径验证、错误隔离

---

🚀 快速开始

1. 安装依赖

npm install

2. 配置 MCP 服务器

在你的 AI 客户端（如 Cursor）配置文件中添加：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["你的项目路径/mcp_pdf_reader/index.js"]
    }
  }
}

3. （可选）配置百度 OCR

1. 访问：https://console.bce.baidu.com/ai/#/ai/ocr/overview/index
2. 创建应用，每个月大约 1000-5000 页的免费额度，获取 API Key 和 Secret Key

如果需要使用 OCR 功能，有两种配置方式：

方式一：环境变量配置（推荐）

设置环境变量：

# Windows
set BAIDU_OCR_API_KEY=你的API密钥
set BAIDU_OCR_SECRET_KEY=你的Secret密钥

# Linux/Mac
export BAIDU_OCR_API_KEY=你的API密钥
export BAIDU_OCR_SECRET_KEY=你的Secret密钥

方式二：配置文件配置

也可以直接在 Cursor 配置文件中配置：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["你的项目路径/mcp_pdf_reader/index.js"],
      "env": {
        "BAIDU_OCR_API_KEY": "你的API密钥",
        "BAIDU_OCR_SECRET_KEY": "你的Secret密钥"
      }
    }
  }
}

4. 重启客户端

重启 Cursor 或你的 MCP 客户端，即可开始使用！

---

✨ 功能特性

🛠️ 核心工具

功能	工具名称	说明	推荐指数
智能阅读	read-pdf-smart	自动识别文本/扫描型 PDF，选择最佳策略	⭐⭐⭐⭐⭐
文本提取	read-pdf	从文本型 PDF 提取内容，支持页码范围	⭐⭐⭐⭐
内容搜索	search-pdf	全文搜索，支持正则、大小写、全字匹配	⭐⭐⭐⭐
元数据提取	pdf-metadata	获取 PDF 文件的完整元数据信息	⭐⭐⭐
OCR 识别	ocr-pdf-legacy	百度 OCR 识别（手动传递密钥）	⭐⭐⭐
自动 OCR	ocr-pdf-auto-legacy	百度 OCR 识别（自动读取环境变量）	⭐⭐⭐⭐

🎯 智能特性

• 自动类型检测：智能识别 PDF 是文本型还是扫描型
• 自动降级策略：文本提取失败时自动切换到 OCR
• 成本优化：优先使用免费的文本提取，需要时才调用 OCR
• 质量保证：三重文本质量检查（字符密度、行数、空白率）
• 图像检测警告：提醒可能包含的重要图像内容
• 智能缓存：OCR 结果缓存，避免重复识别
• 批量处理：支持多页批量处理和分页处理

---

🛠️ 技术栈

核心依赖

{
  "@modelcontextprotocol/sdk": "^1.12.1",  // MCP 协议框架
  "axios": "^1.12.2",                     // HTTP 请求库
  "pdf-parse": "^1.1.1",                  // PDF 文本解析
  "pdf-to-png-converter": "^3.10.0",      // PDF 转图片工具
  "pdf-lib": "^1.17.1",                   // PDF 文档操作库
  "zod": "^3.25.61"                       // 参数验证库
}

系统要求

• Node.js: 18.0.0 或更高版本
• 内存: 至少 512MB 可用内存（处理大文件需要更多）
• 磁盘: 足够的临时存储空间

---

📚 使用指南

🌟 推荐工具：read-pdf-smart

最智能的 PDF 阅读工具，适合 99% 的使用场景。

参数说明

参数	类型	默认值	说明
file	string	必填	PDF 文件的完整路径
pages	string	'all'	页码范围（支持 'first', 'last', 'all', '1-5', '1,3,5'）
language_type	enum	'CHN_ENG'	OCR 语言类型（需要时使用）

使用示例

// 示例 1: 读取整个 PDF（自动选择最佳方式）
{
  "file": "D:\\Documents\\report.pdf"
}

// 示例 2: 只读取前 3 页
{
  "file": "D:\\Documents\\report.pdf",
  "pages": "1-3"
}

// 示例 3: 只读取第一页和最后一页
{
  "file": "D:\\Documents\\book.pdf",
  "pages": "first"
}

📄 工具：read-pdf

基础文本提取工具，适用于文本型 PDF。

参数说明

参数	类型	默认值	说明
file	string	必填	PDF 文件路径
pages	string	'all'	页码范围（如 '1-5', '1,3,5', 'all'）
include_metadata	boolean	true	是否包含 PDF 元数据
clean_text	boolean	false	是否清理和规范化文本

使用示例

// 基本提取
{
  "file": "D:\\Documents\\report.pdf"
}

// 仅提取第 5-10 页，清理文本，不包含元数据
{
  "file": "D:\\Documents\\report.pdf",
  "pages": "5-10",
  "clean_text": true,
  "include_metadata": false
}

🔍 工具：search-pdf

PDF 全文搜索工具，支持高级搜索选项。

参数说明

参数	类型	默认值	说明
file	string	必填	PDF 文件路径
query	string	必填	要搜索的文本
case_sensitive	boolean	false	是否区分大小写
whole_word	boolean	false	是否全字匹配

使用示例

// 不区分大小写的搜索
{
  "file": "D:\\Documents\\manual.pdf",
  "query": "API"
}

// 全字匹配 + 区分大小写
{
  "file": "D:\\Documents\\code.pdf",
  "query": "const",
  "case_sensitive": true,
  "whole_word": true
}

📊 工具：pdf-metadata

元数据提取工具，获取 PDF 文件信息（不读取文本内容）。

提取的元数据

• 文件名、文件大小、页面数
• 作者、标题、主题
• 创建者、生成器软件
• 创建日期、修改日期
• 关键词
• 是否加密
• PDF 版本

使用示例

{
  "file": "D:\\Documents\\thesis.pdf"
}

🖼️ OCR 工具

ocr-pdf-auto-legacy（推荐）

自动 OCR 识别工具（从环境变量读取密钥，更方便）。

参数说明

参数	类型	默认值	说明
file	string	必填	PDF 文件路径
pages	string	'first'	页码范围（支持 'first', 'last', 'all', '1-5', '1,3,5'）
language_type	enum	'CHN_ENG'	语言类型
detect_direction	boolean	false	是否检测方向
detect_language	boolean	false	是否检测语言

支持的语言类型

• CHN_ENG - 中英文混合（默认）
• ENG - 英文
• JAP - 日文
• KOR - 韩文
• FRE - 法文
• SPA - 西班牙文
• POR - 葡萄牙文
• GER - 德文
• ITA - 意大利文
• RUS - 俄文

使用示例

// 识别第一页（默认）
{
  "file": "D:\\Documents\\invoice.pdf"
}

// 识别所有页面（最多 10 页）
{
  "file": "D:\\Documents\\contract.pdf",
  "pages": "all",
  "detect_direction": true,
  "detect_language": true
}

// 只识别最后一页
{
  "file": "D:\\Documents\\report.pdf",
  "pages": "last"
}

---

⚙️ 配置说明

系统要求

• Node.js: 18.0.0 或更高版本
• 内存: 至少 512MB 可用内存（处理大文件需要更多）
• 磁盘: 足够的临时存储空间

安装步骤

1. 克隆或下载项目

git clone https://github.com/your-repo/mcp-pdf-reader.git
cd mcp-pdf-reader

2. 安装依赖

npm install

3. 配置 Cursor（或其他 MCP 客户端）

编辑 Cursor 配置文件，添加 MCP 服务器配置：

{
  "mcpServers": {
    "pdf-reader": {
      "command": "node",
      "args": ["你的完整项目路径/mcp_pdf_reader/index.js"]
    }
  }
}

4. （可选）配置百度 OCR

获取百度 OCR API 密钥：

1. 访问 百度智能云控制台
2. 创建应用并选择"文字识别 OCR"服务
3. 在应用管理页面获取 API Key 和 Secret Key

配置环境变量：

方式 1：永久配置（推荐）

Windows 系统设置：

1. 右键"此电脑" → "属性" → "高级系统设置"
2. 点击"环境变量"
3. 在"用户变量"中添加：
   • BAIDU_OCR_API_KEY = 你的 API Key
   • BAIDU_OCR_SECRET_KEY = 你的 Secret Key

方式 2：临时配置

# Windows CMD
set BAIDU_OCR_API_KEY=your_api_key
set BAIDU_OCR_SECRET_KEY=your_secret_key

# Windows PowerShell
$env:BAIDU_OCR_API_KEY="your_api_key"
$env:BAIDU_OCR_SECRET_KEY="your_secret_key"

# Linux/Mac
export BAIDU_OCR_API_KEY=your_api_key
export BAIDU_OCR_SECRET_KEY=your_secret_key

5. 重启客户端

重启 Cursor 或你的 MCP 客户端以加载配置。

---

核心模块说明

• MCP 服务器: 基于 @modelcontextprotocol/sdk 实现
• PDF 处理: 集成 pdf-parse 和 pdf-lib 进行文本提取
• OCR 识别: 集成百度 OCR API，支持多语言识别
• 缓存系统: 智能缓存机制，提升处理效率
• 错误处理: 完善的错误处理和用户友好的错误信息

---

🔧 高级配置

文件大小限制

默认最大文件大小：50MB

修改限制（在 index.js 中）：

if (stats.size > 50 * 1024 * 1024) { // 修改这里的数值
    throw new Error(`文件过大: ${(stats.size / 1024 / 1024).toFixed(2)}MB。最大支持 50MB。`);
}

OCR 处理页数限制

默认最多处理：10 页

修改限制（在 index.js 中）：

if (pageNumbers.length > 10) { // 修改这里的数值
    pageNumbers = pageNumbers.slice(0, 10);
}

文本质量检查阈值

可以调整质量判断规则（在 index.js 中）：

// 每页最少字符数
if (text.length < 50 * pageCount) return 'poor';

// 字母数字占比最低要求
if (ratio < 0.3) return 'poor';

---

💡 使用技巧

如何选择合适的工具？

┌─────────────────────────────────────────────────────────────┐
│ 你的需求是什么？                                              │
└─────────────────┬───────────────────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
读取 PDF      搜索内容      查看信息
    │             │             │
    ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌──────────┐
│不确定类型│  │ 文本搜索 │  │ 元数据   │
│         │  └─────────┘  └──────────┘
│         │        │             │
│         │        ▼             ▼
│         │  search-pdf    pdf-metadata
│         │
│    ┌────┴────┐
│    │         │
│  文本型   扫描型
│    │         │
│    ▼         ▼
│ read-pdf  ocr-pdf-auto
│
└────▼────────────────┐
   read-pdf-smart     │ ⭐ 推荐！自动识别
   （智能选择）        │
────────────────────────┘

最佳实践

1. 优先使用 read-pdf-smart

// ✅ 推荐：让工具自动判断
{
  "file": "unknown-document.pdf"
}

2. 处理大文件时指定页码范围

// ✅ 推荐：只处理需要的页面
{
  "file": "large-book.pdf",
  "pages": "1-10"  // 只读前 10 页
}

3. OCR 识别时使用正确的语言类型

// ✅ 推荐：指定正确的语言
{
  "file": "japanese-doc.pdf",
  "language_type": "JAP"  // 日文文档
}

4. 搜索时使用合适的选项

// ✅ 推荐：搜索代码关键字时使用全字匹配
{
  "file": "code-documentation.pdf",
  "query": "const",
  "whole_word": true  // 避免匹配到 "constant"
}

---

🔬 开发指南

添加新工具

// 在 index.js 中添加
server.tool(
    "your-new-tool",
    {
        param1: z.string().describe("参数说明"),
        param2: z.number().optional()
    },
    async ({ param1, param2 }) => {
        try {
            // 你的处理逻辑
            return {
                content: [{
                    type: "text",
                    text: "处理结果"
                }]
            };
        } catch (error) {
            return {
                content: [{
                    type: "text",
                    text: `错误: ${error.message}`
                }]
            };
        }
    }
);

调试技巧

由于 MCP 协议的限制，不能直接使用 console.log。建议：

// 写入日志文件
import fs from 'fs';
fs.appendFileSync('debug.log', `[${new Date().toISOString()}] ${message}\n`);

---

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献方向

• 🐛 Bug 修复：修复已知问题
• ✨ 新功能：添加新的 PDF 处理功能
• 📝 文档改进：完善使用文档和示例
• ⚡ 性能优化：提升处理速度和内存使用
• 🧪 测试：添加单元测试和集成测试
• 🌏 国际化：支持更多语言

代码规范

• 使用 ES6+ 语法
• 添加 详细的中文注释
• 遵循 异步/等待 模式
• 包含 错误处理
• 提供 JSDoc 文档

---

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

---

🙏 致谢

• Model Context Protocol - MCP 协议框架
• pdf-parse - PDF 解析库
• pdf-to-png-converter - PDF 转图片工具
• pdf-lib - PDF 文档操作库
• Baidu AI - OCR 服务提供商
• 所有贡献者和用户的支持！

---

<div align="center">

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！