简介

赋予AI代理在项目背景下使用灵活的MCP工具安全读取和提取PDF文件中的信息（文本、元数据、页数）的能力。

简介

赋予AI代理在项目背景下使用灵活的MCP工具安全读取和提取PDF文件中的信息（文本、元数据、页数）的能力。

PDF Reader MCP 服务器 (@sylphlab/pdf-reader-mcp)

使用单一且灵活的工具，使您的AI代理（如Cline）能够在项目上下文中安全地读取和提取PDF文件中的信息（文本、元数据、页数）。

安装

使用 npm（推荐）

在您的MCP主机环境或项目中作为依赖项安装：

bash pnpm add @sylphlab/pdf-reader-mcp # 或者使用 npm install / yarn add

配置您的MCP主机（例如 mcp_settings.json）以使用 npx：

json { "mcpServers": { "pdf-reader-mcp": { "command": "npx", "args": ["@sylphlab/pdf-reader-mcp"], "name": "PDF Reader (npx)" } } }

（确保主机为目标项目设置了正确的 cwd）

使用 Docker

拉取镜像：

bash docker pull sylphlab/pdf-reader-mcp:latest

配置您的MCP主机以运行容器，并将您的项目目录挂载到 /app：

json { "mcpServers": { "pdf-reader-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/path/to/your/project:/app", // 或者使用 "$PWD:/app", "%CD%:/app" 等 "sylphlab/pdf-reader-mcp:latest" ], "name": "PDF Reader (Docker)" } } }

本地构建（开发用）

1. 克隆：git clone https://github.com/sylphlab/pdf-reader-mcp.git

2. 安装：cd pdf-reader-mcp && pnpm install

3. 构建：pnpm run build

4. 配置MCP主机： json { "mcpServers": { "pdf-reader-mcp": { "command": "node", "args": ["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"], "name": "PDF Reader (Local Build)" } } }

   （确保主机为目标项目设置了正确的 cwd）

快速开始

假设服务器正在运行并在您的MCP主机中已配置：

MCP 请求（从本地PDF获取元数据和第2页文本）：

json { "tool_name": "read_pdf", "arguments": { "sources": [ { "path": "./documents/my_report.pdf", "pages": [2] } ], "include_metadata": true, "include_page_count": false, // 默认为true，这里显式设置为false "include_full_text": false // 因为指定了 pages，所以忽略此选项 } }

预期响应片段：

json { "results": [ { "source": "./documents/my_report.pdf", "success": true, "data": { "page_texts": [ { "page": 2, "text": "来自第2页的文本内容..." } ], "info": { ... }, "metadata": { ... } // 按请求不包括 num_pages } } ] }

为什么选择这个项目？

• 🛡️ 安全： 严格限制文件访问仅限于项目根目录。
• 🌐 灵活： 同时处理本地相对路径和公共URL。
• 🧩 统一： 单个 read_pdf 工具满足多种提取需求（全文、特定页面、元数据、页数）。
• ⚙️ 结构化输出： 以可预测的JSON格式返回数据，便于代理解析。- 🚀 易于集成: 通过 npx 或 Docker 在 MCP 环境中无缝使用。
• ✅ 强大: 使用 pdfjs-dist 进行可靠的解析，并使用 Zod 进行输入验证。

性能优势

使用 Vitest 对示例 PDF 进行的初步基准测试显示，各种操作处理效率高：

(更高的 hz 表示更好的性能。结果可能因 PDF 的复杂性和环境而异。)

有关更多详细信息和未来计划，请参阅性能文档。

功能

• 从 PDF 文件中读取全文内容。
• 从特定页或页范围读取文本内容。
• 读取 PDF 元数据（作者、标题、创建日期等）。
• 获取 PDF 的总页数。
• 在单个请求中处理多个 PDF 源（本地路径或 URL）。
• 安全地在定义的项目根目录内操作。
• 通过 MCP 提供结构化的 JSON 输出。
• 可通过 npm 和 Docker Hub 获取。

设计理念

服务器通过上下文限制优先考虑安全性，通过结构化数据传输提高效率，并简化以方便集成到 AI 代理工作流中。它力求最小依赖性，主要依靠强大的 pdfjs-dist 库。

请参阅完整的设计理念文档。

与其他解决方案的比较

与直接文件访问（通常不可行）或通用文件系统工具相比，此服务器提供了特定于 PDF 的解析功能。与外部 CLI 工具（如 pdftotext）不同，它提供了一个安全的集成 MCP 接口和结构化输出，增强了 AI 代理的可靠性和易用性。

请参阅完整的比较文档。

未来计划（路线图）

• 文档:
  • 完成所有文档部分（指南、API、设计、比较）。
  • 解决 TypeDoc 问题并生成 API 文档。
  • 添加更多示例和高级使用模式。
  • 实现 PWA 支持和移动优化文档站点。
  • 向文档站点添加分享按钮和增长指标。
• 基准测试:
  • 使用多样化的 PDF 文件（大小、复杂性）进行全面基准测试。
  • 测量内存使用情况。
  • 比较 URL 与本地文件的性能。
• 核心功能:
  • 探索针对非常大的 PDF 文件的潜在优化。
  • 调查提取图像或注释的选项（长期目标）。
• 测试:
  • 尽可能将测试覆盖率提高到 100%。
  • 在可行时添加运行时测试。

文档

有关详细的使用说明、API 参考和指南，请访问**完整文档网站**（部署后更新链接）。

社区和支持

• 发现错误或有功能请求？ 请在 GitHub Issues 上提出问题。
• 想贡献代码？ 我们欢迎贡献！请参阅 CONTRIBUTING.md。
• 点赞 & 关注: 如果您觉得这个项目有用，请考虑在 GitHub 上为仓库点星 ⭐ 并关注 👀 以表示支持并保持更新！

许可证

本项目根据 MIT 许可证发布。

工具列表

• read_pdf: Reads content/metadata from one or more PDFs (local/URL). Each source can specify pages to extract.

服务配置

[{'mcpServers': {'pdf-reader-mcp': {'args': ['@sylphlab/pdf-reader-mcp'], 'command': 'npx', 'name': 'PDF Reader (npx)'}}}, {'mcpServers': {'pdf-reader-mcp': {'args': ['/path/to/cloned/repo/pdf-reader-mcp/build/index.js'], 'command': 'node', 'name': 'PDF Reader (Local Build)'}}}]

来源

• 来源：github
• 链接：https://github.com/shtse8/pdf-reader-mcp