# PDF MCP Flow  - AI 驱动的 PDF 处理引擎

**中文** | [English](README_EN.md)

> 🚀 **专为 LLM 和 RAG 设计的 MCP 文档处理服务器** | PDF 转 Markdown | 格式转换 | 智能提取

**MCP PDF Flow** 是一个强大的 **Model Context Protocol (MCP)** 服务器，旨在弥合 LLM（如 Claude）与本地文档之间的鸿沟。

它不仅是**PDF 转 Markdown** 的最佳工具，还提供了一套完整的文档处理工作流，支持 **RAG（检索增强生成）** 场景下的数据清洗和格式化。

## ✨ 核心优势

*   **🤖 LLM 友好**：输出清洗后的结构化 Markdown，完美适配 AI 上下文阅读。
*   **🔍 智能 RAG 支持**：支持语义模糊搜索和元数据提取，快速定位文档关键信息。
*   **🔄 全能格式转换**：PDF ⇋ Word ⇋ Markdown 无缝互转。

## ✨ 功能特性

*   **📝 智能文本提取**：
    *   精准提取 PDF 页面文本。
    *   **智能 Markdown 识别**：自动识别标题、列表、段落结构，合并跨行文本，输出干净的 Markdown。
*   **🖼️ 图片提取**：
    *   支持提取页面内的所有图片。
    *   **自动保存与引用**：默认将图片保存到本地 `extracted_images/` 目录，并在 Markdown 中插入图片路径引用，避免大量 Base64 数据占用上下文。
    *   **Base64 预览**：可选直接返回图片 Base64 编码，支持在 MCP 客户端中即时预览（适合少量小图）。
*   **📂 批量处理**：支持对指定目录下的 PDF 文件进行批量提取，自动生成 Markdown 和图片，并保持目录结构整洁。
*   **📊 增强表格提取**：
    *   **高精度识别**：自动处理跨行表头、错位列和复杂排版。
    *   **智能清洗**：自动移除空行、空表头，过滤伪表格（如文本列表）。
    *   **批量导出**：支持一键提取目录下所有 PDF 中的表格为 Markdown 文件。
*   **🔍 模糊搜索**：
    *   **智能查找**：支持通过文件名关键词（模糊匹配、拼写错误兼容）快速定位 PDF 文件路径。
    *   **递归搜索**：默认支持多级目录递归查找。
*   **🔄 格式转换**：
    *   **Markdown 转 Word**：将生成的 Markdown 报告一键转换为格式完美的 Word (.docx) 文档。
    *   **Word 转 PDF**：支持将 Word 文档转换为 PDF 文件。
        *   *自动适配*：优先使用 Microsoft Word，若未安装则自动回退到 WPS Office。
*   **⚙️ 灵活提取**：支持提取全部页面、指定页码范围（如 `1`, `1-5`）或按关键词智能搜索。
*   **ℹ️ 元数据获取**：支持获取 PDF 标题、作者、页数及**目录结构 (TOC)**。

## 🛠️ 环境要求

*   **操作系统**：Windows (推荐，用于支持 Word/WPS 转换) / macOS / Linux
*   **Python**：>= 3.10
*   **Office 软件** (仅 Word 转 PDF 功能需要)：
    *   Microsoft Word (最佳兼容性)
    *   或 WPS Office (支持 Windows)

## 📦 安装与使用

本项目使用 `uv` 进行包管理。

### 1. 克隆项目
```bash
git clone https://github.com/Dublin1231/PDF_MCP_Flow.git
cd mcp-pdf-flow
```

### 2. 安装依赖
```bash
uv sync
```

### 3. 运行服务

本服务是一个 MCP Server，设计为由 Claude Desktop 等客户端**自动启动**。
您**不需要**手动在终端运行启动命令。请继续阅读下方的 [Claude Desktop 配置](#-claude-desktop-配置) 章节完成设置。一旦配置完成，Claude Desktop 启动时会自动在后台运行此服务。

## 🔌 Claude Desktop 配置

要将此工具添加到 Claude Desktop，请编辑配置文件：

*   **Windows**: `%AppData%\Claude\claude_desktop_config.json`
*   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

添加以下内容（请**务必**将路径修改为您本地的实际路径）：

```jsonc
{
  "mcpServers": {
    "simple-pdf": {
      "command": "uv",
      "args": [
        "--directory",
        "D:/path/to/your/mcp-pdf-flow", // ⚠️ 请务必修改为您本地的实际项目路径
        "run",
        "simple-pdf"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        // (可选) 指定额外的 PDF 搜索路径。Windows 使用分号 (;)，Mac/Linux 使用冒号 (:) 分隔
        "PDF_SEARCH_PATHS": //"D:\\example;E:\\example"
      }
    }
  }
}
```

*注意：*
*   *Windows 用户路径分隔符请使用 `/` 或 `\\`。*
*   *`PDF_SEARCH_PATHS` 为可选配置，用于指定额外的 PDF 搜索路径，多个路径用 `;` (Windows) 或 `:` (Mac/Linux) 分隔。*

## 💬 如何在对话中使用

**你不需要手动填写 JSON 参数！** 只需要在对话中告诉 Claude 你想做什么，它会自动调用工具。

### 场景示例

#### 1. 读取 PDF
*   **指定绝对路径**：
    > **用户**: "帮我读取 `D:\Documents\report.pdf` 的第 1 到 5 页。"
*   **读取项目目录下文件**：
    > **用户**: "读取当前目录下的 `test.pdf`。"
    > *(注：Claude 会自动查找运行目录下的文件)*

#### 2. 转换 Markdown 为 Word
> **用户**: "把刚刚提取的内容保存为 Word 文档，放在 `D:\Documents\output.docx`。"
>
> **Claude**: (自动调用 `convert_markdown_to_docx` 工具)

#### 3. Word 转 PDF
> **用户**: "把 `D:\Documents\draft.docx` 转换成 PDF。"
>
> **Claude**: (自动调用 `convert_docx_to_pdf` 工具)

#### 4. 批量处理 PDF
> **用户**: "批量处理 `D:\Docs` 目录下的所有 PDF，导出为 Markdown。"
>
> **Claude**: (自动调用 `batch_extract_pdf_content` 工具)

#### 5. 批量处理并指定输出目录
> **用户**: "批量处理 `D:\Docs` 下的 PDF，将 Markdown 存到 `D:\Output\MD`，图片存到 `D:\Output\Images`。"
>
> **Claude**: (调用 `batch_extract_pdf_content`，参数 `custom_output_dir="D:\\Output\\MD"`, `custom_image_output_dir="D:\\Output\\Images"`)

#### 6. 批量处理并平铺输出（不保留目录结构）
> **用户**: "把 `D:\Docs` 下所有子文件夹里的 PDF 都提取出来，全部放到 `D:\All_MDs` 这个文件夹里，不要建子文件夹。"
>
> **Claude**: (调用 `batch_extract_pdf_content`，参数 `custom_output_dir="D:\\All_MDs"`, `preserve_structure=False`, `create_folder=False`)

#### 7. 模糊查找 PDF
> **用户**: "帮我找一下 `D:\Study` 下面关于 `springboot` 的 PDF 文件。"
>
> **Claude**: (自动调用 `search_pdf_files` 工具)

#### 8. 获取 PDF 目录结构
> **用户**: "提取 `D:\Books\Guide.pdf` 的目录大纲。"
>
> **Claude**: (自动调用 `get_pdf_metadata` 工具)


#### 9. 批量提取表格
> **用户**: "把 `D:\Books` 下所有 PDF 的表格提取出来，存到 `D:\Tables`。"
>
> **Claude**: (自动调用 `batch_extract_tables` 工具)


---

## 📖 工具列表

> **💡 小贴士：如何获取“绝对路径”？**
> *   **Windows**: 按住 `Shift` 键，右键点击文件，选择“复制文件地址 (Copy as path)”。粘贴时去掉首尾的引号。
>     *   示例: `C:\Users\Name\Documents\report.pdf`
> *   **macOS**: 选中文件，按下 `Option + Command + C` 复制路径。
>     *   示例: `/Users/name/Documents/report.pdf`


### 1. `extract_pdf_content`
提取 PDF 内容的核心工具。

**参数：**
*   `file_path` (必填): PDF 文件的绝对路径。
    *   *Windows 示例*: `D:\Documents\paper.pdf`
    *   *macOS 示例*: `/Users/username/Documents/paper.pdf`
*   `page_range` (可选): 页码范围，默认为 "all"。
    *   示例: `"1"`, `"1-5"`, `"1,3,5"`, `"all"`。
*   `keyword` (可选): 关键词搜索。若提供，将忽略页码范围，仅提取包含关键词的页面。
*   `format` (可选): 输出格式。
    *   `"text"` (默认): 纯文本提取。
    *   `"markdown"`: **推荐**。智能识别标题和段落，适合 LLM 阅读。
    *   `"json"`: 返回结构化 JSON 数据，包含每一页的文本和图片信息，适合程序化处理。
*   `include_text` (可选): 是否提取文本，默认为 `true`。
*   `include_images` (可选): 是否提取图片，默认为 `false`。
*   `use_local_images_only` (可选): 图片处理模式，默认为 `true`。
    *   `true` (默认): 图片保存到本地 `extracted_images` 目录，Markdown 中使用路径引用。**推荐用于大文件或包含大量图片的 PDF，防止 Token 溢出**。
    *   `false`: 返回图片的 Base64 数据流，可直接预览，但消耗大量 Token。
*   `skip_table_detection` (可选): **极速模式**开关，默认为 `false`。
    *   `false` (默认): 智能检测并提取表格，转换为 Markdown 表格格式。
    *   `true`: **跳过表格检测**。适用于仅需要纯文本内容的场景，速度可提升 3-4 倍（约 400+ 页/秒）。

### 2. `batch_extract_pdf_content`
批量处理指定目录下的所有 PDF 文件。

**参数：**
*   `directory` (必填): 要搜索的根目录绝对路径。
*   `pattern` (可选): 文件匹配模式，默认为 `**/*.pdf` (支持递归)。
*   `custom_output_dir` (可选): 指定输出根目录。如果不填，默认使用项目根目录。最终输出将在该目录下创建 `output` 文件夹，并根据模式包含以下子目录：
    *   `output_standard_with_image`: 包含图片，标准模式（含表格）。
    *   `output_fast_with_image_no_table`: 包含图片，极速模式（跳过表格检测）。
    *   `output_standard_no_image`: 标准模式+纯文本 (**不含图片**，含表格)。
    *   `output_fast_no_image_and_table`: 极速模式+纯文本 (**不含图片，不含表格**)。
    *   `output_only_image`: 仅提取图片模式 (不生成 Markdown 文件，图片保存在 `output/output_only_image/extracted_images` 目录)。
*   `format` (可选): 输出格式，支持 `markdown` (默认), `json`, `text`。
*   `include_text` (可选): 是否提取文本，默认为 `true`。
*   `include_images` (可选): 是否提取图片，默认为 `false`。
*   `use_local_images_only` (可选): 图片处理模式，默认为 `true`。
*   `skip_table_detection` (可选): **极速模式**开关，默认为 `false`。
    *   `false` (默认): 智能检测并提取表格，转换为 Markdown 表格格式。
    *   `true`: **跳过表格检测**。适用于仅需要纯文本内容的场景，速度可提升 3-4 倍（约 400+ 页/秒）。
*   `create_folder` (可选): **是否创建专属文件夹**，默认为 `false`。
    *   `true`: 为每个 PDF 创建专属的同名文件夹（例如 `output/subdir/file/file.md`）。
    *   `false` (默认): 不创建专属文件夹（例如 `output/subdir/file.md`）。
*   `preserve_structure` (可选): **目录结构保持**开关，默认为 `true`。
    *   `true` (默认): 保持源文件的目录层级结构（例如 `output/SourceSubDir/file.md`）。
    *   `false`: **集中/扁平化**模式。忽略源目录结构，将所有结果直接放在输出根目录（例如 `output/file.md`）。


### 3. `get_pdf_metadata`
快速获取 PDF 的元数据和目录结构。

**参数：**
*   `file_path` (必填): PDF 文件的绝对路径。

### 4. `convert_markdown_to_docx`
将 Markdown 内容转换为 Word 文档。

**参数：**
*   `markdown_content` (必填): 要转换的 Markdown 文本内容。
*   `output_path` (必填): 输出 .docx 文件的绝对路径。
    *   *注意*: 这里需要填写**你希望保存的新文件路径**。
    *   *示例*: `D:\Documents\report_output.docx`

### 5. `convert_docx_to_pdf`
将 Word 文档转换为 PDF 文件。

**参数：**
*   `docx_path` (必填): 输入的 .docx 文件绝对路径。
*   `pdf_path` (可选): 输出 .pdf 文件的绝对路径。
    *   如果不提供，将在原 docx 文件同目录下生成同名 pdf 文件。

### 6. `search_pdf_files`
通过文件名模糊搜索 PDF 文件路径。

**参数：**
*   `query` (必填): 文件名关键词。支持模糊匹配（如拼写错误）、中文匹配。
*   `directory` (可选): 搜索根目录。默认为当前工作目录。
*   `limit` (可选): 返回的最大结果数量，默认 10。
*   `threshold` (可选): 匹配阈值 (0.0-1.0)，默认 0.45。


### 7. `batch_extract_tables`
批量提取目录中所有 PDF 的表格。

**默认输出路径：**
*   `output/output_only_table`: 仅提取表格模式 (表格保存在 `output/output_only_table` 目录)。

**参数：**
*   `directory` (必填): 要搜索的根目录绝对路径。
*   `output_dir` (可选): 指定输出根目录。最终表格 Markdown 文件将保存在该目录下的 `output/output_only_table` 文件夹中。如果不填，默认为当前目录。
*   `pattern` (可选): 文件匹配模式，默认为 `**/*.pdf`。

**✨ 表格提取增强特性：**
*   **智能表头合并**：自动处理跨行表头和被拆分的列名。
*   **错位列修复**：智能识别并合并因格式问题错位的标题和内容列。
*   **空行/空表头优化**：
    *   自动移除无效的空行。
    *   智能识别 KV 结构表格，仅在必要时保留表头，避免对中文 KV 表格生成错误的空表头。
*   **伪表格过滤**：
    *   自动识别并过滤文本列表（如目录、步骤说明）。
    *   自动过滤被误判为表格的代码块或长文本段落。
*   **排版优化**：智能处理单元格内的换行符，保持列表结构清晰，同时让普通长文本自然回流。

## 📂 输出目录结构

运行工具后，图片将按以下结构保存：

```
extracted_images/
  └── PDF文件名/
      ├── page_1_img_1.jpeg
      ├── page_1_img_2.png
      └── ...
```

## 💻 开发

*   **核心代码**: `src/simple_pdf/server.py`
*   **转换逻辑**: `src/simple_pdf/convert.py`