Pdf Navigator MCP

PDF导航器MCP

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

特性

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

安装

# Install with pipx (recommended)
pipx install git+https://github.com/matsengrp/pdf-navigator-mcp.git

# Or install in current environment
pip install git+https://github.com/matsengrp/pdf-navigator-mcp.git

Claude代码集成

添加到您的 ~/.claude.json:

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

用法

在Claude Code中，您可以：

• “阅读paper.pdf中的摘要” → 提取并显示文本内容
• “paper.pdf的目录是什么？” → 显示PDF结构
• “阅读paper.pdf的第5-10页” → 提取特定页面范围
• “在paper.pdf中搜索‘参数效率’” → 查找文本和位置
• “打开纸张.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) -通过多行检测提取表单字段进行标记
• 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. 编辑标记 -使用任何文本编辑器填写值
3. 填写PDF -将标记数据应用回以创建填充的PDF

工作流示例

# Step 1: Extract form fields to markdown
# Creates a markdown file with placeholders for each field
extract_form_to_markdown("application.pdf", "application_form.md")

# Step 2: Edit application_form.md in your editor
# Fill in values after each arrow (→)

# Step 3: Fill the PDF with your data
fill_form_from_markdown("application.pdf", "application_form.md", "application_filled.pdf")

Markdown格式

提取的标记如下：

# PDF Form: application.pdf
Type: Interactive Form
Generated: 2025-08-03

## Form Fields

### Page 1
- Full Name → John Smith
- Email → john@example.com
- Phone → 555-0123
- [ ] Subscribe to newsletter → true

支持的表单类型

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

增强型多行形状检测

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

特性

• 多线段检测 -当一个节标题后面有多个连续的空行时（例如，“I love…”后面跟着几个下划线），会自动检测
• 智能文本分发 -使用自然断点将长文本分布在多个相关字段中
• 自然断点 -尊重句子、逗号、连词和明确的换行符
• 可配置参数 -控制文本分发行为

文本分发策略

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 (I love...) → Reading books with my parents
Doing puzzles and addition
Going on trips
Anything with my big sister

换行符支持在多个PDF字段之间进行智能分发，防止文本过于拥挤。使用 extract_and_fill_form 和 format_multiline_form_data MCP提示引导工作流。

支持的PDF阅读器

• 浏览 （macOS）- skim:// URL方案
• 迷走星球 （Linux）- --page 论点
• 表明 （Linux）- --page-index 论点
• 苏门答腊PDF （Windows）- -page 论点
• Adobe Acrobat （跨平台）- /A page=N 论点

配置

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

{
  "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许可证