使用说明

项目简介

PDF文档阅读器MCP服务器是一个基于Model Context Protocol (MCP) 构建的后端服务，旨在为AI Agent（如Cline/Claude）提供读取和提取PDF文档内容的能力。它通过单一的 'read_pdf' 工具，支持从本地文件系统（限定在项目根目录下）或公开URL中读取PDF文档，并提取文本、元数据和页数等信息。

主要功能点

安全的文件访问控制：所有本地文件操作被严格限制在服务器启动时的工作目录（项目根目录）内，防止未授权访问。
支持本地文件和URL：可以处理本地项目目录内的PDF文件以及公开可访问的URL指向的PDF文件。
灵活的PDF信息提取：通过 'read_pdf' 工具的参数控制，可以灵活提取PDF文档的全文、指定页面的文本、元数据和页数信息。
易于集成：可以通过 'npx' 或 Docker 快速启动和集成到MCP客户端环境中。
参数校验：使用 Zod 进行输入参数校验，确保请求的有效性。

安装步骤

本服务器可以通过 'npx'、'bunx' 或 Docker 镜像运行，推荐使用 'npx' 方式快速开始。

方法一：使用 npx (推荐)

无需安装，直接通过 'npx' 运行。确保你的MCP客户端配置中 'command' 设置为 'npx'，'args' 设置为 '["@shtse8/pdf-reader-mcp"]'。

方法二：使用 bunx

如果你的环境中使用 bun，可以使用 'bunx' 运行。MCP客户端配置中 'command' 设置为 'bunx'，'args' 设置为 '["@shtse8/pdf-reader-mcp"]'。

方法三：使用 Docker

确保你的系统已安装 Docker。

MCP客户端配置中 'command' 设置为 'docker'，'args' 配置如下，并根据你的项目路径进行调整：

[
  "run",
  "-i",
  "--rm",
  "-v",
  "/path/to/your/project:/app",  // 将你的项目路径替换为实际路径
  "shtse8/pdf-reader-mcp:latest"
]

注意： '/path/to/your/project' 需要替换为你实际的项目根目录的绝对路径。为了方便，可以使用 shell 变量 (如 Linux/macOS 下的 '"$PWD:/app"'，Windows Cmd 下的 '"%CD%:/app"'，PowerShell 下的 '${PWD}:/app') 让 Docker 自动挂载当前工作目录作为项目根目录。

方法四：本地构建 (开发环境)

克隆仓库: 'git clone https://github.com/shtse8/pdf-reader-mcp.git'
进入目录: 'cd pdf-reader-mcp'
安装依赖: 'npm install'
构建项目: 'npm run build'
MCP客户端配置中 'command' 设置为 'node'，'args' 设置为 '["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"]'，'/path/to/cloned/repo/pdf-reader-mcp' 需要替换为你克隆仓库的实际本地路径。

服务器配置 (MCP客户端)

在你的MCP客户端配置文件（例如 'mcp_settings.json'）中，配置 PDF文档阅读器MCP服务器。以下是使用 'npx' 启动服务器的配置示例：

{
  "mcpServers": {
    "pdf-reader-mcp": {
      "command": "npx", // 启动命令，使用 npx
      "args": [
        "@shtse8/pdf-reader-mcp" //  npx 的参数，指定要运行的 npm 包
      ],
      "name": "PDF Reader (npx)" // 服务器名称，用于在MCP客户端中标识
    }
  }
}

重要提示： 确保 MCP 客户端启动上述命令时，工作目录 (cwd) 设置为你的项目根目录。这是为了保证服务器能够正确解析项目内的相对路径 PDF 文件。

基本使用方法

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

调用 'read_pdf' 工具的请求示例：

以下是一个 JSON-RPC 请求示例，展示如何调用 'read_pdf' 工具来获取本地 PDF 文件 'report.pdf' 和 URL 'http://example.com/another.pdf' 的元数据和页数：

{
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "name": "read_pdf",
    "arguments": {
      "sources": [
        { "path": "report.pdf" }, // 读取项目根目录下的 report.pdf
        { "url": "http://example.com/another.pdf" } // 读取 URL 指向的 PDF
      ]
    }
  },
  "id": 1
}

'read_pdf' 工具的参数说明：

'sources': (必需) PDF 文档来源数组。每个来源对象必须包含 'path' (本地文件相对路径) 或 'url' (PDF URL) 二者之一。
- 'path': 本地 PDF 文件的相对路径（相对于项目根目录）。
- 'url': PDF 文件的 URL。
- 'pages': (可选) 指定要提取文本的页码或页码范围。可以是数字数组 '[1, 3, 5]' 或页码范围字符串 ''1,3-5,7''。如果指定了 'pages'，则 'include_full_text' 参数将被忽略。
'include_full_text': (可选, 默认 'false') 是否包含每个 PDF 的全文内容。如果为 'true' 且 'sources' 中没有指定 'pages'，则返回全文。
'include_metadata': (可选, 默认 'true') 是否包含每个 PDF 的元数据（'info' 和 'metadata' 对象）。
'include_page_count': (可选, 默认 'true') 是否包含每个 PDF 的总页数 ('num_pages')。

'read_pdf' 工具的响应示例：

响应将包含一个 'results' 数组，每个元素对应一个输入的 'source'。即使部分来源处理失败，也会继续处理其他来源。

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"results\": [\n    {\n      \"source\": \"report.pdf\",\n      \"success\": true,\n      \"data\": {\n        \"info\": { ... },\n        \"metadata\": { ... },\n        \"num_pages\": 10\n      }\n    },\n    {\n      \"source\": \"http://example.com/another.pdf\",\n      \"success\": true,\n      \"data\": {\n        \"info\": { ... },\n        \"metadata\": { ... },\n        \"num_pages\": 5\n      }\n    },\n    {\n      \"source\": \"nonexistent.pdf\",\n      \"success\": false,\n      \"error\": \"File not found...\"\n    }\n  ]\n}"
      }
    ]
  },
  "id": 1
}

请参考仓库的 README 文件和代码注释获取更详细的信息。

关键词