MCP PDF Reader

# MCP PDF Reader <div align="center"> **🚀 基于 Model Context Protocol 的智能 PDF 处理服务器** [](https://nodejs.org/) [](LICENSE) [](https://github.com/modelcontextprotocol) **功能强大** · **易于使用** · **智能识别** [快速开始](#快速开始) · [功能特性](#功能特性) · [使用指南](#使用指南) · [配置说明](#配置说明) </div> --- ## 📖 项目简介 MCP PDF Reader 是一个专业的 PDF 文档处理工具，通过 Model Context Protocol (MCP) 为 AI 应用提供强大的 PDF 文本提取、搜索、OCR 识别等功能。它能够智能识别 PDF 类型，自动选择最佳处理策略，为用户提供高效便捷的文档处理体验。 ### 🎯 核心优势 - **🤖 智能识别**：自动判断 PDF 类型（文本型/扫描型），选择最佳处理方案 - **🔍 强大搜索**：支持正则表达式、全字匹配、大小写敏感搜索 - **📊 完整元数据**：提取作者、标题、创建日期等 13 项元数据 - **🌏 多语言 OCR**：支持中文、英文、日文、韩文等 10 种语言识别 - **⚡ 高性能**：令牌缓存机制、智能错误处理、并发保护、使用文件缓存重复读取pdf文件不消耗API调用 - **🛡️ 安全可靠**：文件大小限制、路径验证、错误隔离 --- ## 🚀 快速开始 ### 1. 安装依赖 ```bash npm install ``` ### 2. 配置 MCP 服务器 在你的 AI 客户端（如 Cursor）配置文件中添加： ```json { "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 功能，有两种配置方式： #### 方式一：环境变量配置（推荐） 设置环境变量： ```bash # 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 配置文件中配置： ```json { "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 结果缓存，避免重复识别 - **批量处理**：支持多页批量处理和分页处理 --- ## 🛠️ 技术栈 ### 核心依赖 ```json { "@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 语言类型（需要时使用） | #### 使用示例 ```javascript // 示例 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` | 是否清理和规范化文本 | #### 使用示例 ```javascript // 基本提取 { "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` | 是否全字匹配 | #### 使用示例 ```javascript // 不区分大小写的搜索 { "file": "D:\\Documents\\manual.pdf", "query": "API" } // 全字匹配 + 区分大小写 { "file": "D:\\Documents\\code.pdf", "query": "const", "case_sensitive": true, "whole_word": true } ``` ### 📊 工具：pdf-metadata **元数据提取工具**，获取 PDF 文件信息（不读取文本内容）。 #### 提取的元数据 - 文件名、文件大小、页面数 - 作者、标题、主题 - 创建者、生成器软件 - 创建日期、修改日期 - 关键词 - 是否加密 - PDF 版本 #### 使用示例 ```javascript { "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` - 俄文 ##### 使用示例 ```javascript // 识别第一页（默认） { "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. 克隆或下载项目 ```bash git clone https://github.com/your-repo/mcp-pdf-reader.git cd mcp-pdf-reader ``` #### 2. 安装依赖 ```bash npm install ``` #### 3. 配置 Cursor（或其他 MCP 客户端） 编辑 Cursor 配置文件，添加 MCP 服务器配置： ```json { "mcpServers": { "pdf-reader": { "command": "node", "args": ["你的完整项目路径/mcp_pdf_reader/index.js"] } } } ``` #### 4. （可选）配置百度 OCR **获取百度 OCR API 密钥**： 1. 访问 [百度智能云控制台](https://console.bce.baidu.com/) 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：临时配置** ```bash # 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 中）： ```javascript if (stats.size > 50 * 1024 * 1024) { // 修改这里的数值 throw new Error(`文件过大: ${(stats.size / 1024 / 1024).toFixed(2)}MB。最大支持 50MB。`); } ``` ### OCR 处理页数限制 默认最多处理：**10 页** 修改限制（在 index.js 中）： ```javascript if (pageNumbers.length > 10) { // 修改这里的数值 pageNumbers = pageNumbers.slice(0, 10); } ``` ### 文本质量检查阈值 可以调整质量判断规则（在 index.js 中）： ```javascript // 每页最少字符数 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` ```javascript // ✅ 推荐：让工具自动判断 { "file": "unknown-document.pdf" } ``` #### 2. 处理大文件时指定页码范围 ```javascript // ✅ 推荐：只处理需要的页面 { "file": "large-book.pdf", "pages": "1-10" // 只读前 10 页 } ``` #### 3. OCR 识别时使用正确的语言类型 ```javascript // ✅ 推荐：指定正确的语言 { "file": "japanese-doc.pdf", "language_type": "JAP" // 日文文档 } ``` #### 4. 搜索时使用合适的选项 ```javascript // ✅ 推荐：搜索代码关键字时使用全字匹配 { "file": "code-documentation.pdf", "query": "const", "whole_word": true // 避免匹配到 "constant" } ``` --- ## 🔬 开发指南 ### 添加新工具 ```javascript // 在 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`。建议： ```javascript // 写入日志文件 import fs from 'fs'; fs.appendFileSync('debug.log', `[${new Date().toISOString()}] ${message}\n`); ``` --- ## 🤝 贡献指南 我们欢迎所有形式的贡献！ ### 贡献方向 - 🐛 **Bug 修复**：修复已知问题 - ✨ **新功能**：添加新的 PDF 处理功能 - 📝 **文档改进**：完善使用文档和示例 - ⚡ **性能优化**：提升处理速度和内存使用 - 🧪 **测试**：添加单元测试和集成测试 - 🌏 **国际化**：支持更多语言 ### 代码规范 - 使用 **ES6+ 语法** - 添加 **详细的中文注释** - 遵循 **异步/等待** 模式 - 包含 **错误处理** - 提供 **JSDoc 文档** --- ## 📄 许可证 本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。 --- ## 🙏 致谢 - [Model Context Protocol](https://github.com/modelcontextprotocol) - MCP 协议框架 - [pdf-parse](https://www.npmjs.com/package/pdf-parse) - PDF 解析库 - [pdf-to-png-converter](https://www.npmjs.com/package/pdf-to-png-converter) - PDF 转图片工具 - [pdf-lib](https://pdf-lib.js.org/) - PDF 文档操作库 - [Baidu AI](https://ai.baidu.com/) - OCR 服务提供商 - 所有贡献者和用户的支持！ --- <div align="center"> **如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！**