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

为您的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阅读器(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阅读器(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阅读器(本地构建)"
       }
     }
   }

   (确保主机为目标项目设置了正确的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": "第2页的文本内容..." }
        ],
        "info": { ... },
        "metadata": { ... }
        // 按请求未包含num_pages
      }
    }
  ]
}

为什么选择本项目?

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

性能优势

在示例PDF上使用Vitest进行的初步基准测试显示了各种操作的高效处理能力:

(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。
• Star & Watch: 如果您觉得本项目有用，请在GitHub上star⭐和watch👀仓库以示支持并保持更新!

许可证

本项目采用MIT许可证。