@mcpcn/mcp-pdf-reader

# PDF Reader MCP Server (@mcpcn/mcp-pdf-reader) 一个基于 Model Context Protocol (MCP) 的高性能 PDF 阅读服务器，专门为 AI 代理（如 Cline、Claude Desktop）提供安全可靠的 PDF 读取和提取信息（文本、元数据、页数）。 ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white) ![Node.js](https://img.shields.io/badge/Node.js-43853D?style=flat&logo=node.js&logoColor=white) ![MCP](https://img.shields.io/badge/MCP-Compatible-blue) ![Zod](https://img.shields.io/badge/Zod-Validation-green) ## ✨ 功能特点 - 📖 **安全PDF阅读** - 严格限制访问项目根目录下的文件，确保安全性 - 🌐 **多源支持** - 支持本地文件和在线URL两种PDF源 - 📄 **灵活文本提取** - 支持全文提取或特定页面文本提取 - 📊 **完整元数据获取** - 提取PDF文档信息和结构化元数据 - 📈 **高效批量处理** - 并行处理多个PDF文件，显著提升性能 - 🚀 **可靠PDF解析** - 基于 pdfjs-dist 库的企业级PDF解析 - 🔧 **标准MCP集成** - 完全兼容MCP协议，无缝集成到AI工作流 - 🛡️ **输入验证** - 使用Zod进行严格的输入参数验证 - ⚡ **性能优化** - 智能字体加载优化和并行处理 - 🤖 **智能依赖管理** - 自动检测和安装缺失的依赖，用户无需手动配置 ## 🚀 快速开始 ### 一键安装（推荐） ```bash cd typescript/PDF阅读 npm run setup ``` 这个命令会自动： - ✅ 检查Node.js版本（需要>=18） - 📦 安装所有必要依赖 - 🔨 编译TypeScript代码 - 🎉 准备服务运行环境 ### 手动安装如果一键安装失败，可以手动执行： ```bash cd typescript/PDF阅读 npm install npm run build ``` ### MCP 配置 #### Claude Desktop 配置 (macOS) 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`： ```json { "mcpServers": { "pdf-reader": { "command": "node", "args": [ "/path/to/your/skills/typescript/PDF阅读/dist/index.js" ] } } } ``` #### Cline/Cursor 配置在 Cursor 设置中的 MCP 服务器配置中添加： ```json { "mcpServers": { "pdf-reader": { "command": "node", "args": [ "path/to/your/skills/typescript/PDF阅读/dist/index.js" ], "autoApprove":["read_pdf"] } } } ``` ## 🔧 使用说明 ### read_pdf 工具 **功能：** 读取PDF文件内容，提取文本、元数据和页数信息 **参数：** - `sources` (必需): PDF源文件数组 - `path` (必需): PDF文件路径（本地路径或URL） - `pages` (可选): 要提取的特定页面数组，如 [1, 2, 3] - `include_metadata` (可选): 是否包含PDF元数据，默认 true - `include_page_count` (可选): 是否包含页数统计，默认 true - `include_full_text` (可选): 是否包含完整文本内容，默认 true ### 使用示例 #### 1. 读取本地PDF文件的完整内容 ```json { "tool_name": "read_pdf", "arguments": { "sources": [ { "path": "./documents/report.pdf" } ], "include_metadata": true, "include_page_count": true, "include_full_text": true } } ``` #### 2. 提取特定页面内容 ```json { "tool_name": "read_pdf", "arguments": { "sources": [ { "path": "./documents/manual.pdf", "pages": [1, 3, 5] } ], "include_metadata": false, "include_page_count": false, "include_full_text": false } } ``` #### 3. 从URL读取PDF ```json { "tool_name": "read_pdf", "arguments": { "sources": [ { "path": "https://example.com/document.pdf" } ] } } ``` #### 4. 批量处理多个PDF ```json { "tool_name": "read_pdf", "arguments": { "sources": [ { "path": "./docs/file1.pdf", "pages": [1, 2] }, { "path": "./docs/file2.pdf" }, { "path": "https://example.com/remote.pdf" } ] } } ``` ### 响应格式成功响应示例： ```json { "results": [ { "source": "./documents/report.pdf", "success": true, "data": { "num_pages": 25, "info": { "Title": "Annual Report 2023", "Author": "Company Name", "CreationDate": "D:20231215120000Z" }, "metadata": { "dc:title": "Annual Report 2023" }, "full_text": "This is the extracted text content from the PDF..." } } ] } ``` 特定页面响应示例： ```json { "results": [ { "source": "./documents/manual.pdf", "success": true, "data": { "num_pages": 100, "page_texts": [ { "page": 1, "text": "Page 1 content..." }, { "page": 3, "text": "Page 3 content..." } ] } } ] } ``` ## 🔒 安全特性 - **路径限制**: 只能访问项目根目录及其子目录下的文件 - **协议限制**: URL仅支持HTTP/HTTPS协议 - **文件验证**: 自动验证文件存在性和可读性 - **错误处理**: 完善的错误捕获和友好的错误信息 ## 🎯 技术亮点 ### 与 sylphxltd/pdf-reader-mcp 同等水平本项目参考了开源项目 [sylphxltd/pdf-reader-mcp](https://github.com/sylphxltd/pdf-reader-mcp)，实现了以下关键特性： - ✅ **Zod输入验证** - 严格的类型检查和参数验证，确保数据安全 - ✅ **并行处理** - 多文件并行处理，显著提升批量操作性能 - ✅ **错误隔离** - 单个文件错误不影响其他文件处理 - ✅ **内存优化** - 智能字体加载策略，减少内存占用 - ✅ **结构化输出** - 标准化的JSON响应格式，便于AI解析 - ✅ **安全沙箱** - 严格的路径验证，防止目录遍历攻击 ### 性能优势 - **并行处理**: 多PDF文件同时处理，而非顺序执行 - **智能缓存**: PDF库延迟加载和复用 - **内存优化**: 禁用不必要的标准字体加载 - **错误恢复**: 健壮的错误处理不会中断整体流程 ## 💻 对话示例 ``` 用户：请帮我读取桌面上的年度报告.pdf文件助手：我来帮你读取PDF文件... 📖 PDF阅读完成！ 📁 文件：年度报告.pdf 📊 页数：45页 📄 标题：2023年度财务报告 👤 作者：财务部 📝 内容摘要：本报告包含公司2023年的完整财务状况... 用户：只需要第1页和第5页的内容助手：我来提取特定页面的内容... 📖 已提取指定页面： 📄 第1页：标题页内容... 📄 第5页：财务数据概览... ``` ## ⚠️ 注意事项 1. **文件路径**: 使用相对路径，确保文件在项目根目录下 2. **文件格式**: 支持标准PDF格式文件 3. **网络访问**: URL方式需要网络连接，可能需要较长加载时间 4. **内存使用**: 大文件处理时可能需要更多内存 5. **编码支持**: 支持UTF-8编码的文本提取 ## 🔧 故障排除 ### 常见问题 1. **pdfjs-dist 加载失败错误** ``` 错误：无法加载 pdfjs-dist，请执行 npm install 并确保 Node 版本>=18 ``` **原因**: pdfjs-dist 库加载失败或Node.js版本不兼容 **解决方案**: - **自动解决**: 服务会自动尝试多种加载策略和依赖安装 - **手动解决**: ```bash cd typescript/PDF阅读 rm -rf node_modules package-lock.json npm install npm run build ``` - **检查Node版本**: 确保 Node.js >= 18.0.0 2. **空页面数组错误** ``` 错误：输入参数验证失败: sources.0.pages: 如果指定pages数组，不能为空 ``` **原因**: 传入了空的pages数组 `"pages": []` **解决方案**: - 不指定pages参数（将提取全文） - 或者指定具体页面 `"pages": [1, 2, 3]` 3. **绝对路径访问错误** ``` 错误：绝对路径不安全或不是PDF文件: /Users/xxx/file.pdf ``` **原因**: 绝对路径安全检查失败 **解决方案**: - 确保文件是PDF格式（.pdf扩展名） - 确保路径不包含危险字符（如 `..`, `~/`, `$` 等） - 如果可能，使用相对路径 4. **文件不存在错误** ``` 错误：文件不存在: ./documents/report.pdf ``` **解决方案**: 检查文件路径是否正确，确保文件存在 5. **路径安全错误** ``` 错误：文件路径不安全，只能访问项目根目录下的文件 ``` **解决方案**: 使用相对路径，确保文件在项目根目录下 6. **PDF解析错误** ``` 错误：无法解析PDF文件 ``` **解决方案**: 确认PDF文件格式正确且未损坏 7. **网络错误** ``` 错误：HTTP error! status: 404 ``` **解决方案**: 检查URL是否正确且可访问 8. **Node.js版本问题** ``` 错误：需要 Node.js 版本 >= 18 ``` **解决方案**: 升级Node.js到18或更高版本 ## 📝 开发信息 - **框架**: Model Context Protocol (MCP) SDK - **PDF解析**: pdfjs-dist - **文件操作**: fs-extra - **输入验证**: Zod - **Node.js版本**: >= 18.0.0 - **TypeScript版本**: >= 5.6.0 ## 🔄 更新日志 ### v1.1.1 (最新版本) - 错误修复版本 - 🔧 **修复 pdfjs-dist 加载失败** - 改进加载策略，支持多种导入方式 - 🔧 **支持绝对路径访问** - 允许安全的绝对路径PDF文件访问 - 🔧 **修复空页面数组处理** - 使用Zod验证拒绝空pages数组 - 🔧 **增强错误诊断** - 详细的错误信息和调试输出 - 🔧 **改进Node.js版本检查** - 更准确的版本兼容性检测 - 🔧 **优化依赖管理** - 更智能的自动安装和错误恢复 ### v1.1.0 - ✅ 添加 Zod 输入验证，提高参数安全性 - ✅ 实现并行处理，显著提升批量PDF处理性能 - ✅ 优化错误处理和响应格式 - ✅ 增强安全性检查和路径验证 - ✅ 改进内存使用和性能优化 - ✅ 更新依赖到最新版本 - ✅ 与 sylphxltd/pdf-reader-mcp 项目功能对标 ### v1.0.1 - 基础PDF阅读功能实现 - 自动依赖管理 - 本地文件和URL支持 ## 📄 许可证本项目采用 MIT 许可证。 --- 基于 [sylphxltd/pdf-reader-mcp](https://github.com/sylphxltd/pdf-reader-mcp) 项目启发开发，实现了同等水平的功能特性。