@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) ## ✨ 功能特点 - 📖 **安全PDF阅读** - 仅限访问项目根目录下的PDF文件，确保安全性 - 🌐 **多源支持** - 支持本地文件和在线URL两种PDF源 - 📄 **灵活文本提取** - 支持全文提取或特定页面文本提取 - 📊 **元数据获取** - 提取PDF文档信息和元数据 - 📈 **批量处理** - 一次请求处理多个PDF文件 - 🚀 **高性能** - 基于 pdfjs-dist 库的可靠PDF解析 - 🔧 **易于集成** - 标准MCP协议，无缝集成到AI工作流 ## 🚀 快速开始 ### 安装依赖 ```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协议 - **文件验证**: 自动验证文件存在性和可读性 - **错误处理**: 完善的错误捕获和友好的错误信息 ## 💻 对话示例 ``` 用户：请帮我读取桌面上的年度报告.pdf文件助手：我来帮你读取PDF文件... 📖 PDF阅读完成！ 📁 文件：年度报告.pdf 📊 页数：45页 📄 标题：2023年度财务报告 👤 作者：财务部 📝 内容摘要：本报告包含公司2023年的完整财务状况... 用户：只需要第1页和第5页的内容助手：我来提取特定页面的内容... 📖 已提取指定页面： 📄 第1页：标题页内容... 📄 第5页：财务数据概览... ``` ## ⚠️ 注意事项 1. **文件路径**: 使用相对路径，确保文件在项目根目录下 2. **文件格式**: 支持标准PDF格式文件 3. **网络访问**: URL方式需要网络连接，可能需要较长加载时间 4. **内存使用**: 大文件处理时可能需要更多内存 5. **编码支持**: 支持UTF-8编码的文本提取 ## 🔧 故障排除 ### 常见问题 1. **文件不存在错误** ``` 错误：文件不存在: ./documents/report.pdf ``` **解决方案**: 检查文件路径是否正确，确保文件存在 2. **路径安全错误** ``` 错误：文件路径不安全，只能访问项目根目录下的文件 ``` **解决方案**: 使用相对路径，确保文件在项目根目录下 3. **PDF解析错误** ``` 错误：无法解析PDF文件 ``` **解决方案**: 确认PDF文件格式正确且未损坏 4. **网络错误** ``` 错误：HTTP error! status: 404 ``` **解决方案**: 检查URL是否正确且可访问 ## 📝 开发信息 - **框架**: Model Context Protocol (MCP) SDK - **PDF解析**: pdfjs-dist - **文件操作**: fs-extra - **Node.js版本**: >= 18.0.0 - **TypeScript版本**: >= 5.0.0 ## 📄 许可证本项目采用 MIT 许可证。 --- 基于 [sylphxltd/pdf-reader-mcp](https://github.com/sylphxltd/pdf-reader-mcp) 项目启发开发。