PDF Reader MCP Server (@sylphlab/pdf-reader-mcp)

<!-- Status Badges Area -->

<!-- End Status Badges Area -->

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

安装

使用 npm (推荐)

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

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

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

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

(确保主机为目标项目设置正确的 cwd)

使用 Docker

拉取镜像：

docker pull sylphlab/pdf-reader-mcp:latest

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

{
  "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 主机:

   {
     "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 页文本）：

{
  "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'，因此被忽略
  }
}

预期响应片段：

{
  "results": [
    {
      "source": "./documents/my_report.pdf",
      "success": true,
      "data": {
        "page_texts": [
          { "page": 2, "text": "Text content from page 2..." }
        ],
        "info": { ... },
        "metadata": { ... }
        // 未包含 num_pages，因为已请求
      }
    }
  ]
}

为什么选择这个项目？

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

性能优势

使用 Vitest 在示例 PDF 上进行的初始基准测试显示了对各种操作的有效处理：

场景	每秒操作数 (hz)	相对速度
处理不存在的文件	~12,933	最快
获取全文	~5,575
获取特定页面（第 1 页）	~5,329
获取特定页面（第 1 页和第 2 页）	~5,242
获取元数据和页数	~4,912	最慢

(更高的 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 上打开一个 issue。
• 想要贡献？ 我们欢迎贡献！ 请参阅 CONTRIBUTING.md。
• Star & Watch： 如果您发现此项目有用，请考虑在 GitHub 上 star ⭐ 和 watch 👀 存储库，以表示您的支持并保持更新！

许可证

该项目已获得 MIT 许可证 的许可。