关键词

PDF读取文件解析文档提取上下文服务AI工具

PDF阅读器MCP服务器

项目简介

本项目是一个基于 Model Context Protocol (MCP) 构建的服务器，专注于提供 PDF 文档的读取和信息提取功能。它作为一个 MCP 工具服务器，可以与支持 MCP 协议的 LLM 客户端（如 Cline/Claude）配合使用，使 AI 智能体能够安全地访问和理解项目根目录下的 PDF 文件内容，或者直接处理网络上的 PDF 文件。

主要功能点

  • 安全的文件访问控制：所有本地文件操作都被严格限制在服务器启动时设置的项目根目录下，防止未经授权的访问，使用相对路径访问本地文件。
  • 支持本地和远程PDF：可以处理项目根目录下的本地 PDF 文件，也可以直接读取公共 URL 上的 PDF 文件。
  • 高效的PDF处理：利用 'pdf-parse' 库高效地提取 PDF 文件的文本内容、元数据和页面信息。
  • 灵活的'read_pdf'工具：提供单一且功能强大的 'read_pdf' 工具，通过参数控制信息提取的类型和范围，简化了 LLM 客户端的交互。
  • 易于集成：可以通过 'npx' 命令快速启动，或者使用 Docker 容器部署。
  • 参数验证：使用 Zod 库对所有输入参数进行严格的校验，确保请求的合法性。

安装步骤

推荐方式：使用 'npx' (无需安装，需Node.js环境)

  1. 确保你的环境中已安装 Node.js 和 npm。
  2. 无需额外安装，直接在 MCP 客户端的配置文件中配置服务器启动命令即可。

Docker 方式 (需要 Docker 环境)

  1. 确保你的环境中已安装 Docker。
  2. 无需额外安装，直接在 MCP 客户端的配置文件中配置 Docker 镜像运行命令即可。

本地构建 (开发或自定义需求)

  1. 克隆仓库到本地： 
    git clone https://github.com/sylphlab/pdf-reader-mcp.git
  2. 进入项目目录： 
    cd pdf-reader-mcp
  3. 安装依赖： 
    npm install
  4. 构建项目： 
    npm run build

服务器配置

MCP 客户端配置示例 (以 'mcp_settings.json' 为例):

使用 'npx' 启动 (推荐):

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx",
      "args": ["@sylphlab/pdf-reader-mcp"],
      "name": "PDF Reader (npx)" // 服务器名称，可自定义
    }
  }
}

使用 'bunx' 启动 (需要 Bun 环境):

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/pdf-reader-mcp"],
      "name": "PDF Reader (bunx)" // 服务器名称，可自定义
    }
  }
}

使用 Docker 启动:

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app", // 将你的项目根目录挂载到容器的 /app 目录
        "sylphlab/pdf-reader-mcp:latest" // Docker 镜像名称
      ],
      "name": "PDF Reader (Docker)" // 服务器名称，可自定义
    }
  }
}

注意:

  • '/path/to/your/project' 需要替换为你的项目根目录的实际路径。
  • 非常重要： 无论使用哪种方式启动，MCP客户端必须确保启动命令时的工作目录 (cwd) 设置为你的项目根目录。这是为了保证 PDF 阅读器服务器能够正确、安全地访问项目内的本地 PDF 文件。

使用本地构建启动:

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "node",
      "args": ["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"], //  '/path/to/cloned/repo/pdf-reader-mcp' 替换为仓库克隆到本地的实际路径
      "name": "PDF Reader (Local Build)" // 服务器名称，可自定义
    }
  }
}

注意:

  • '/path/to/cloned/repo/pdf-reader-mcp' 需要替换为仓库克隆到本地的实际路径。

基本使用方法

本服务器提供一个名为 'read_pdf' 的工具，用于读取 PDF 文件信息。

调用 'read_pdf' 工具的请求示例 (JSON-RPC 'callTool' 请求参数):

{
  "name": "read_pdf", // 工具名称
  "arguments": {
    "sources": [ // PDF 文件来源数组，可以包含多个来源
      {
        "path": "report.pdf" // 本地 PDF 文件相对项目根目录的路径
        // 或者
        // "url": "http://example.com/document.pdf" // 远程 PDF 文件 URL
      },
      {
        "url": "http://example.com/another.pdf"
      }
    ],
    "include_full_text": false, // 是否包含全部文本内容 (默认为 false)
    "include_metadata": true,  // 是否包含元数据 (默认为 true)
    "include_page_count": true // 是否包含页数 (默认为 true)
  }
}

更详细的 'read_pdf' 工具参数说明:

  • 'sources' (array, 必填): PDF 文件来源数组。每个元素为一个来源对象，必须包含 'path' (本地文件路径) 或 'url' (远程 URL) 中的一个。
    • 'path' (string, 可选): 本地 PDF 文件相对于项目根目录的路径。
    • 'url' (string, 可选): 远程 PDF 文件的 URL。
    • 'pages' (string | number[], 可选): 指定需要提取文本的页码或页码范围。例如：
      • '[1, 3, 5]'：提取第1, 3, 5页
      • '"1,3-5,7"'：提取第1, 3, 4, 5, 7页
      • 如果指定了 'pages'，则 'include_full_text' 参数会被忽略。
  • 'include_full_text' (boolean, 可选, 默认为 'false'): 是否包含 PDF 文件的全部文本内容。如果为 'true'，则返回 PDF 文件的完整文本。如果指定了 'sources' 中某个来源的 'pages' 参数，则该来源的 'include_full_text' 将被忽略。
  • 'include_metadata' (boolean, 可选, 默认为 'true'): 是否包含 PDF 文件的元数据 (info 和 metadata 对象)。
  • 'include_page_count' (boolean, 可选, 默认为 'true'): 是否包含 PDF 文件的总页数。

'read_pdf' 工具返回结果示例 (JSON-RPC 'callTool' 响应结果):

{
  "results": [
    {
      "source": "report.pdf", // 来源标识 (path 或 url)
      "success": true,       // 是否成功处理
      "data": {            // 成功时返回的数据
        "info": { ... },      // PDF info 元数据 (如果 include_metadata 为 true)
        "metadata": { ... },  // PDF metadata 元数据 (如果 include_metadata 为 true)
        "num_pages": 10,      // PDF 总页数 (如果 include_page_count 为 true)
        // "full_text": "...", // PDF 全部文本内容 (如果 include_full_text 为 true 且未指定 pages)
        "page_texts": [      // 指定 pages 时返回的页码文本数组
          { "page": 1, "text": "..." },
          { "page": 3, "text": "..." }
        ],
        "warnings": ["Requested page numbers 4, 5 exceed total pages (3)."] // 警告信息
      }
    },
    {
      "source": "http://example.com/another.pdf",
      "success": true,
      "data": {
        "info": { ... },
        "metadata": { ... },
        "num_pages": 5
      }
    },
    {
      "source": "nonexistent.pdf",
      "success": false,      // 处理失败
      "error": "File not found at 'nonexistent.pdf'. Resolved to: nonexistent.pdf" // 错误信息
    }
  ]
}

信息

分类

数据库与文件

访问项目