JinDaGe - PDF Reader MCP Server MCP Details

article

README

🚀 PDF 阅读器

PDF 阅读器是一款功能强大的工具，它能安全、灵活地读取 PDF 文件，通过单个工具满足多种提取需求，并以结构化的 JSON 格式输出数据，便于集成到各类环境中。

🚀 快速开始

使用 npm 安装该工具：

npm install @pdf-reader/core

示例代码如下：

import { PDFReader } from '@pdf-reader/core';

async function main() {
    const reader = new PDFReader();
    const text = await reader.extractText('path/to/your.pdf');
    console.log(text);
}

main().catch(console.error);

✨ 主要特性

🛡️ 安全性：严格限制文件访问权限，仅限于项目根目录。
🌐 灵活性：支持本地相对路径和公共 URL。
🧩 统一功能：单个 read_pdf 工具即可实现多种提取需求（全文本、特定页面、元数据、页数统计）。
⚙️ 结构化输出：返回易于解析的预测 JSON 格式数据。
🚀 易于集成：设计用于通过 npx 或 Docker 容器在 MCP 环境中无缝使用。
✅ 可靠性：使用 pdfjs-dist 进行可靠的解析，并借助 Zod 实现输入验证。

📦 安装指南

使用 npm 进行安装：

npm install @pdf-reader/core

💻 使用示例

基础用法

import { PDFReader } from '@pdf-reader/core';

async function main() {
    const reader = new PDFReader();
    const text = await reader.extractText('path/to/your.pdf');
    console.log(text);
}

main().catch(console.error);

高级用法

// 在单次请求中处理多个 PDF 源文件（本地路径或 URL）
import { PDFReader } from '@pdf-reader/core';

async function main() {
    const reader = new PDFReader();
    const sources = ['path/to/local.pdf', 'https://example.com/remote.pdf'];
    const results = await reader.processMultipleSources(sources);
    console.log(results);
}

main().catch(console.error);

📚 详细文档

功能

读取 PDF 文件的全文本内容。
提取特定页面或页面范围的文本内容。
读取 PDF 的元数据（作者、标题、创建日期等）。
获取 PDF 的总页数。
在单次请求中处理多个 PDF 源文件（本地路径或 URL）。
安全地在定义的项目根目录内运行。
提供结构化的 JSON 输出，通过 MCP 接口传递。

设计理念

该服务器优先考虑安全性，通过限制上下文来实现文件访问的安全性。同时，其设计注重高效性和简洁性，便于与 AI 代理工作流程集成。它依赖于最少的依赖项，并使用可靠的 pdfjs-dist 库进行 PDF 解析。有关完整的设计理念文档。

功能对比

与其他解决方案相比：

与直接文件访问：提供了针对 PDF 的特定解析功能。
与通用文件系统工具 (例如 pdftotext)：通过 MCP 接口提供了一个安全、集成的界面，并生成结构化的输出，提高了可靠性和易用性。有关完整对比文档。

未来计划（路线图）

文档：
- 完成所有文档部分（指南、API 参考、设计、比较）。
- 解决 TypeDoc 问题并生成 API 文档。
- 添加更多示例和高级用法。
- 实现 PWA 支持并在移动设备上进行优化。
- 在文档网站中添加分享按钮和增长指标。
基准测试：使用各种 PDF 文件（大小、复杂度）进行全面测试。
性能优化：优化现有功能，提升处理速度和效率。

依赖项

pdfjs-dist：使用 pdf.js 库来处理和解析 PDF 文件。
Zod：用于输入验证和类型安全。

贡献指南

欢迎社区贡献！请参考贡献文档了解如何参与开发。

文档链接

有关详细信息，请参阅项目文档：

🔧 技术细节

性能优势

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

| 场景 | 操作数（每秒 hz） | 相对速度 | | :------------------------------- | :------------------------- | :------------- | | 处理未找到文件的情况 | ~12,933 | 最快 | | 获取全文本内容 | ~5,575 | | | 获取特定页面（第 1 页） | ~5,329 | | | 获取指定页面（第 1 和 2 页） | ~5,242 | | | 获取元数据和总页数 | ~4,912 | 最慢 |

（更高的 hz 值表示性能越好。实际结果可能因 PDF 文件的复杂性和环境而异。）

有关更多详细信息，请参阅性能文档。

📄 许可证

文档中未提及相关内容，暂不展示。

📞 联系方式

如需反馈或问题，请联系维护团队。

感谢您使用 PDF 阅读器！

PDF Reader MCP Server