# pdf-reader-mcp

**Repository Path**: crazymonkey186/pdf-reader-mcp

## Basic Information

- **Project Name**: pdf-reader-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-14
- **Last Updated**: 2025-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[![MseeP.ai 安全评估徽章](https://mseep.net/pr/sylphxltd-pdf-reader-mcp-badge.png)](https://mseep.ai/app/sylphxltd-pdf-reader-mcp)

# PDF Reader MCP 服务器 (@sylphlab/pdf-reader-mcp)

<!-- 状态徽章区域 -->

[![CI/CD 流水线](https://github.com/sylphlab/pdf，-reader-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sylphlab/pdf-reader-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/sylphlab/pdf-reader-mcp/graph/badge.svg?token=VYRQFB40UN)](https://codecov.io/gh/sylphlab/pdf-reader-mcp)
[![npm 版本](https://badge.fury.io/js/%40sylphlab%2Fpdf-reader-mcp.svg)](https://badge.fury.io/js/%40sylphlab%2Fpdf-reader-mcp)
[![Docker 拉取次数](https://img.shields.io/docker/pulls/sylphlab/pdf-reader-mcp.svg)](https://hub.docker.com/r/sylphlab/pdf-reader-mcp)
[![许可证：MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- 状态徽章区域结束 -->

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

<a href="https://glama.ai/mcp/servers/@sylphlab/pdf-reader-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@sylphlab/pdf-reader-mcp/badge" alt="PDF Reader Server MCP 服务器" />
</a>

## 安装

### 使用 npm（推荐）

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

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

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

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

_（确保主机为目标项目设置正确的 `cwd`）_

### 使用 Docker

拉取镜像：

```bash
docker pull sylphlab/pdf-reader-mcp:latest
```

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

```json
{
  "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 主机：
   ```json
   {
     "mcpServers": {
       "pdf-reader-mcp": {
         "command": "node",
         "args": ["/path/to/cloned/repo/pdf-reader-mcp/build/index.js"],
         "name": "PDF Reader (本地构建)"
       }
     }
   }
   ```
   _（确保主机为目标项目设置正确的 `cwd`）_

## 快速开始

假设服务器已运行并配置在您的 MCP 主机中：

**MCP 请求（获取本地 PDF 的元数据和第 2 页文本）：**

```json
{
  "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'，所以会被忽略
  }
}
```

**预期响应片段：**

```json
{
  "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) | 相对速度 |
| :--------------------------- | :-------------- | :------- |
| 处理不存在的文件             | ~12,933         | 最快     |
| 获取全文本                   | ~5,575          |          |
| 获取特定页面（第 1 页）      | ~5,329          |          |
| 获取特定页面（第 1 和 2 页） | ~5,242          |          |
| 获取元数据和页数             | ~4,912          | 最慢     |

_（hz 越高表示性能越好。结果可能因 PDF 复杂度和环境而异。）_

有关更多详细信息和未来计划，请参阅 [性能文档](./docs/performance/index.md)。

## 功能

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

## 设计理念

服务器通过上下文限制优先考虑安全性，通过结构化数据传输提高效率，并为 AI 代理工作流简化集成。它旨在减少依赖，依靠强大的 `pdfjs-dist` 库。

请参阅完整的 [设计理念](./docs/design/index.md) 文档。

## 与其他解决方案的比较

与直接文件访问（通常不可行）或通用文件系统工具相比，此服务器提供 PDF 特定的解析功能。与外部 CLI 工具（如 `pdftotext`）不同，它提供安全、集成的 MCP 接口和结构化输出，提高了 AI 代理的可靠性和易用性。

请参阅完整的 [比较](./docs/comparison/index.md) 文档。

## 未来计划（路线图）

- **文档：**
  - 完成所有文档部分（指南、API、设计、比较）。
  - 解决 TypeDoc 问题并生成 API 文档。
  - 添加更多示例和高级使用模式。
  - 为文档网站实现 PWA 支持和移动优化。
  - 为文档网站添加分享按钮和增长指标。
- **基准测试：**
  - 使用各种 PDF 文件（大小、复杂度）进行全面基准测试。
  - 测量内存使用情况。
  - 比较 URL 与本地文件性能。
- **核心功能：**
  - 探索非常大 PDF 文件的潜在优化。
  - 研究提取图像或注释的选项（长期）。
- **测试：**
  - 在可行的情况下将测试覆盖率提高到 100%。
  - 一旦可行，添加运行时测试。

## 文档

有关详细用法、API 参考和指南，请访问 **[完整文档网站](https://sylphlab.github.io/pdf-reader-mcp/)**（部署后将更新链接）。

## 社区与支持

- **发现错误或有功能请求？** 请在 [GitHub Issues](https://github.com/sylphlab/pdf-reader-mcp/issues) 上打开一个 issue。
- **想要贡献？** 我们欢迎贡献！请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
- **点赞 & 关注：** 如果您觉得这个项目有用，请考虑在 [GitHub](https://github.com/sylphlab/pdf-reader-mcp) 上给它点赞 ⭐ 并关注 👀，以表示您的支持并保持更新！，

## 许可证

本项目采用 [MIT 许可证](./LICENSE) 授权。