PDF Asset Extractor (MCP Tools)

描述

將 PDF 文件分解為可查詢的資產（圖片、表格、章節），並建立跨文獻知識圖譜。

核心能力：

• 📄 PDF 匯入 → 雙引擎（PyMuPDF 快速 / Marker 高精度）自動提取圖片、表格、文字
• 🖼️ 圖片提取 → 以 base64 返回，支援 Vision AI 分析
• 📊 表格提取 → 轉換為 Markdown 格式
• 🧭 章節導航 → 動態層級 Section Tree（支援任意深度）
• 🔍 知識圖譜 → 跨文獻關係查詢 (LightRAG)
• 📈 圖譜視覺化 → 導出 Mermaid 圖表

觸發條件

• 「ingest PDF」、「匯入 PDF」、「解析文件」、「分析論文」
• 「看 manifest」、「文件結構」、「有什麼圖表」
• 「取得圖片」、「fetch figure」、「拿表格」、「extract」
• 「知識圖譜」、「cross-document」、「比較文獻」、「RAG」
• 「視覺化圖譜」、「export graph」、「mermaid」
• 「章節」、「section」、「導航」、「樹狀結構」

🔧 雙引擎策略

Marker 產出額外資料

• blocks.json — 結構化區塊（含 bbox、polygon、section_hierarchy）
• 支援 Section Navigation 動態層級導航

⚠️ 重要警告

🖼️ 圖片 Context 限制

Base64 圖片非常大，一次只處理一張！

- 一張圖片 ≈ 200KB base64 ≈ ~270K tokens
- 對話 context 有限，多張圖片會快速耗盡
- 建議流程：先 inspectdocumentmanifest → 選定目標圖 → 一次 fetch 一張

👁️ 視覺能力提醒

如果 AI 有視覺能力（Vision），可直接分析返回的圖片
如果是純文字 AI，應誠實告知無法分析圖片內容

📸 圖片 ID 命名規則

系統以 fig{page}{index} 命名，非解析圖說文字
需手動對照 manifest 頁碼與實際 Figure 編號

🔧 可用 MCP Tools

文件處理

資產查詢

Section Navigation 🧭 (需 Marker blocks.json)

區塊搜尋 (Marker blocks)

知識圖譜

📂 MCP Resources（動態更新）

Resources 會自動更新，可直接瀏覽文件大綱：

Resource 使用範例

# 瀏覽已處理的文件
→ documents://list

# 查看文件大綱（推薦起點）
→ document://abc123def/outline

# 列出所有圖片
→ document://abc123def/figures

# 知識圖譜概覽
→ knowledge-graph://summary

📋 標準操作流程

1️⃣ PDF 匯入（ETL）

使用者：「幫我匯入這份 PDF」/ 「分析這份論文」

步驟：
1. 取得 PDF 絕對路徑
2. 呼叫 ingest_documents（預設 async_mode=True）
3. 使用 get_job_status 追蹤進度
4. 完成後提供 doc_id

範例呼叫：

# 異步匯入（推薦，大檔案用）
ingest_documents(file_paths=["/papers/study.pdf"])
# 返回 job_id，用 get_job_status 追蹤

# 同步匯入（小檔案）
ingest_documents(file_paths=["/papers/small.pdf"], async_mode=False)

2️⃣ 查看文件結構

使用者：「這份文件有什麼圖表？」

步驟：
1. 呼叫 list_documents 找到 doc_id
2. 呼叫 inspect_document_manifest
3. 列出所有 figures/tables/sections

範例呼叫：

list_documents()
inspect_document_manifest(doc_id="abc123def")

Manifest 內容：

• 📊 Tables: tab1, tab2...（ID、頁碼）
• 🖼️ Figures: fig21, fig31...（ID、尺寸、頁碼）
• 📑 Sections: secintro, secmethods...（標題、行號）

3️⃣ 取得特定資產

取得圖片（⚠️ 一次一張）

fetch_document_asset(
    doc_id="abc123def",
    asset_type="figure",
    asset_id="fig_3_1"
)
# 返回 ImageContent (base64) + metadata

取得表格

fetch_document_asset(
    doc_id="abc123def",
    asset_type="table",
    asset_id="tab_1"
)
# 返回 Markdown 格式表格

取得章節/全文

# 特定章節
fetch_document_asset(doc_id="abc123def", asset_type="section", asset_id="sec_methods")

# 全文 Markdown
fetch_document_asset(doc_id="abc123def", asset_type="full_text", asset_id="full")

4️⃣ 知識圖譜查詢

使用者：「比較這兩篇文獻的發現」/ 「AlphaFold 是什麼？」

步驟：
1. 確認文件已 ingest 且已建立索引
2. 選擇查詢模式
3. 呼叫 consult_knowledge_graph

查詢模式：

範例呼叫：

consult_knowledge_graph(
    query="What is AlphaFold and how does it work?",
    mode="hybrid"
)

5️⃣ 知識圖譜視覺化 ✨ NEW

使用者：「顯示知識圖譜」/ 「圖譜長什麼樣？」

步驟：
1. 選擇輸出格式
2. 呼叫 export_knowledge_graph
3. Mermaid 格式可直接渲染

輸出格式：

範例呼叫：

# 快速概覽
export_knowledge_graph(format="summary")

# Mermaid 視覺化（可渲染）
export_knowledge_graph(format="mermaid", limit=25)

# 完整 JSON 數據
export_knowledge_graph(format="json", limit=100)

Mermaid 輸出範例：

graph TD
    N0["AlphaFold"]
    N1["DeepMind"]
    N2["Protein Structure"]
    N0 -->|developed by| N1
    N0 -->|predicts| N2

🎯 情境範例

情境 A：分析新 PDF 論文

使用者：「幫我分析這份 PDF」

執行流程：
1. ingest_documents → 取得 job_id
2. get_job_status → 等待完成
3. inspect_document_manifest → 了解結構
4. fetch section (Introduction) → 快速瀏覽
5. 根據需要 fetch 特定圖表
6. consult_knowledge_graph → 整合分析

情境 B：提取圖表

使用者：「給我 Figure 3」

執行流程：
1. list_documents → 找到 doc_id
2. inspect_document_manifest → 找 fig_X_X 對應
3. fetch_document_asset(asset_type="figure", asset_id="fig_3_1")
4. 返回圖片 + metadata

情境 C：跨文獻比較

使用者：「比較 A 和 B 論文的結論」

執行流程：
1. 確認兩份文件都已 ingest
2. consult_knowledge_graph(mode="global")
3. export_knowledge_graph(format="mermaid") → 視覺化關係

情境 D：探索知識圖譜

使用者：「圖譜裡有什麼？」

執行流程：
1. export_knowledge_graph(format="summary") → 統計
2. export_knowledge_graph(format="mermaid", limit=20) → 視覺化

⚡ Context 預算

📊 輸出格式

操作後應回報：

## PDF 處理結果

### 📄 文件資訊
- **doc_id**: `abc123def`
- **標題**: Nobel Prize Chemistry 2024
- **頁數**: 15 頁

### 📊 可用資產
| 類型 | 數量 | 範例 ID |
|------|------|---------|
| Figures | 8 | fig_2_1, fig_5_1 |
| Tables | 3 | tab_1, tab_2 |
| Sections | 5 | sec_intro, sec_methods |

### 🔗 知識圖譜
- **節點**: 383
- **關係**: 99
- 可使用 `export_knowledge_graph` 視覺化