STARWARCLOUD STARWAR.AI
返回市场
pdf导航器-mcp

pdf导航器-mcp

作者：matsengrp6 星标更新：2025-09-09
安装使用来源：spider==github.com

项目介绍

PDF Navigator MCP

一个全面的模型上下文协议（MCP）服务器，用于PDF阅读、导航和文本搜索，并与跨平台PDF查看器集成。通过提供PDF功能来消除PyMuPDF依赖问题。

功能

  • PDF文本提取 - 读取完整的PDF或特定页面/范围
  • PDF结构分析 - 提取目录和页面摘要
  • 带位置的文本搜索 - 查找文本并跳转到结果
  • 直接PDF导航 - 打开PDF到特定页面
  • PDF表单填写 - 将表单字段提取到Markdown中，编辑并填写PDF
  • 跨平台PDF查看器 - 支持Skim、Zathura、Evince等
  • MCP集成 - 与Claude Code和其他MCP客户端兼容
  • 无依赖问题 - 在MCP服务器环境中隔离PyMuPDF

安装

# 使用pipx安装（推荐）
pipx install git+https://github.com/matsengrp/pdf-navigator-mcp.git

# 或在当前环境安装
pip install git+https://github.com/matsengrp/pdf-navigator-mcp.git

Claude Code集成

添加到你的~/.claude.json：

{
  "mcpServers": {
    "pdf-navigator": {
      "type": "stdio",
      "command": "pdf-navigator-mcp"
    }
  }
}

使用方法

在Claude Code中，你可以：

  • "从paper.pdf中读取摘要" → 提取并显示文本内容
  • "paper.pdf的目录是什么？" → 显示PDF结构
  • "读取paper.pdf的第5至10页" → 提取特定页码范围
  • "在paper.pdf中搜索'参数效率'" → 查找文本及其位置
  • "打开paper.pdf到第5页" → 打开PDF查看器到特定页面
  • "从application.pdf中提取表单字段" → 创建包含表单字段的Markdown文件
  • "用我的数据填写PDF表单" → 使用编辑过的Markdown数据填充PDF

MCP工具

阅读工具

  • read_pdf_text(file_path, start_page, end_page) - 从页面范围内提取文本
  • read_pdf_page(file_path, page_number) - 从单个页面提取文本
  • get_pdf_structure(file_path) - 获取目录和页面摘要
  • get_pdf_info(file_path) - 获取文档元数据

导航工具

  • search_pdf_text(file_path, query) - 搜索文本并返回位置
  • open_pdf_page(file_path, page_number) - 打开PDF查看器到特定页面
  • search_and_open(file_path, query, result_index) - 搜索并打开到结果

表单填写工具

  • extract_form_to_markdown(file_path, output_md_path) - 将表单字段提取到Markdown中，检测多行
  • fill_form_from_markdown(pdf_path, markdown_path, output_pdf_path, distribute_text=True, max_chars_per_field=50, respect_line_breaks=True) - 使用智能文本分布从Markdown填充PDF

PDF表单填写工作流程

PDF表单填写功能使用基于Markdown的工作流程：

  1. 提取表单字段 - 分析PDF并创建包含所有检测到字段的Markdown文件
  2. 编辑Markdown - 使用任何文本编辑器填写值
  3. 填写PDF - 应用Markdown数据以创建已填写的PDF

示例工作流程

# 第一步：将表单字段提取到Markdown
# 创建一个带有每个字段占位符的Markdown文件
extract_form_to_markdown("application.pdf", "application_form.md")

# 第二步：在编辑器中编辑application_form.md
# 在每个箭头（→）后填写值

# 第三步：用你的数据填写PDF
fill_form_from_markdown("application.pdf", "application_form.md", "application_filled.pdf")

Markdown格式

提取的Markdown看起来像这样：

# PDF表单：application.pdf
类型：交互式表单
生成日期：2025-08-03

## 表单字段

### 第1页
- 全名 → 约翰·史密斯
- 电子邮件 → john@example.com
- 电话 → 555-0123
- [ ] 订阅新闻通讯 → true

支持的表单类型

  • 交互式表单 - 带有实际表单字段的PDF（可填写的PDF）
  • 静态表单 - 带有下划线/框的PDF（创建可移动的文字注释）

增强的多行表单检测

PDF Navigator现在包括高级多行表单检测和智能文本分布：

特性

  • 多行部分检测 - 自动检测当多个连续空白行跟随部分标题时（例如，“我爱...”后面跟着几个下划线）
  • 智能文本分布 - 使用自然断点将长文本分布在多个相关字段上
  • 自然断点 - 尊重句子、逗号、连词和显式换行
  • 可配置参数 - 控制文本分布行为

文本分布策略

  1. 句子分割 - “我喜欢阅读。玩游戏很有趣。” → 分别填入不同字段
  2. 逗号/分号分割 - “读书，玩游戏，去公园” → 分别填入不同字段
  3. 连词分割 - “阅读和游戏和旅行” → 分别填入不同字段
  4. 单词边界分割 - 根据长度智能分割，同时保留整个单词

配置选项

  • distribute_text: bool - 启用/禁用多行文本分布（默认：True）
  • max_chars_per_field: int - 每个字段的目标字符限制（默认：50）
  • respect_line_breaks: bool - 尊重新行输入文本（默认：True）

示例

而不是将“与父母一起阅读书籍，做拼图和加法，去旅行，与姐姐一起做任何事情”挤进一个小字段，它会自动分配为：

  • 字段1：与父母一起阅读书籍
  • 字段2：做拼图和加法
  • 字段3：去旅行
  • 字段4：与姐姐一起做任何事情

表单填写最佳实践

为了在多行字段中实现最佳文本分布：

- personal_interests_love_1 (我爱...) → 阅读书籍与父母
做拼图和加法
去旅行
与姐姐一起做任何事情

新行允许智能地分布在多个PDF字段上，防止文本拥挤。使用extract_and_fill_form和format_multiline_form_data MCP提示进行引导工作流程。

支持的PDF阅读器

  • Skim (macOS) - skim:// URL方案
  • Zathura (Linux) - --page 参数
  • Evince (Linux) - --page-index 参数
  • SumatraPDF (Windows) - -page 参数
  • Adobe Acrobat (跨平台) - /A page=N 参数

配置

在~/.pdf-navigator-config.json中配置你的PDF阅读器：

{
  "pdf_reader": "skim",
  "reader_path": "/Applications/Skim.app"
}

开发

git clone https://github.com/matsengrp/pdf-navigator-mcp.git
cd pdf-navigator-mcp
pip install -e ".[dev]"

许可证

MIT许可证