pdf-asset-extractor

PDF Asset Extractor (MCP Tools)

Description

Decompose PDF documents into queryable assets (images, tables, sections), and build a cross-document knowledge graph.

Core Capabilities：

📄 PDF Import → Dual engine (PyMuPDF fast / Marker high-precision) automatically extracts images, tables, and text
🖼️ Image Extraction → Returned as base64, supports Vision AI analysis
📊 Table Extraction → Converted to Markdown format
🧭 Section Navigation → Dynamic hierarchical Section Tree (supports arbitrary depth)
🔍 Knowledge Graph → Cross-document relationship queries (LightRAG)
📈 Graph Visualization → Export Mermaid diagrams

Trigger Conditions

"ingest PDF", "import PDF", "parse document", "analyze paper"
"view manifest", "document structure", "what charts are there"
"get image", "fetch figure", "get table", "extract"
"knowledge graph", "cross-document", "compare literature", "RAG"
"visualize graph", "export graph", "mermaid"
"section", "section", "navigation", "tree structure"

🔧 Dual Engine Strategy

Engine	Strengths	Weaknesses	Trigger Method
PyMuPDF (default)	Fast, lightweight (~50MB)	Lower layout analysis precision	`ingest_documents()`
Marker (high precision)	Precise bbox, section hierarchy	Heavy model (~1GB), slower	`ingest_documents(use_marker=True)` or `parse_pdf_structure()`

Marker produces additional data

blocks.json — Structured blocks (including bbox, polygon, section_hierarchy)
Supports Section Navigation dynamic hierarchical navigation

⚠️ Important Warnings

🖼️ Image Context Limitations

Base64 images are very large, only process one at a time!

One image ≈ 200KB base64 ≈ ~270K tokens

Conversation context is limited, multiple images will quickly exhaust it

Recommended workflow: first inspect_document_manifest → select target image → fetch one at a time

👁️ Vision Capability Reminder

If the AI has vision capabilities (Vision), it can directly analyze the returned images If it is a text-only AI, it should honestly state that it cannot analyze image content

📸 Image ID Naming Rules

The system names by fig_{page}_{index} , not by parsing figure captions Manual cross-referencing of manifest page numbers with actual Figure numbers is required

🔧 Available MCP Tools

Document Processing

Tool	Purpose	Parameters
`ingest_documents`	Import PDF (ETL process)	`file_paths: list[str]`, `async_mode: bool`, `use_marker: bool`
`parse_pdf_structure`	Marker structured parsing (single file)	`file_path: str`
`get_job_status`	Query ETL progress	`job_id: str`
`list_jobs`	List all jobs	`active_only: bool`
`cancel_job`	Cancel ETL job	`job_id: str`

Asset Query

Tool	Purpose	Parameters
`list_documents`	List all processed documents	None
`inspect_document_manifest`	View document structure (image/table/section list)	`doc_id: str`
`fetch_document_asset`	Get specific asset	`doc_id`, `asset_type`, `asset_id`

Section Navigation 🧭 (requires Marker blocks.json)

Tool	Purpose	Parameters
`list_section_tree`	Display the full section hierarchy tree structure	`doc_id: str`
`get_section_detail`	Retrieve detailed information for a specific section	`doc_id: str`, `section_path: str`
`get_section_blocks`	Extract all blocks of a specific section	`doc_id: str`, `section_path: str`
`search_sections`	Search section names	`doc_id: str`, `query: str`

Block search (Marker blocks)

Tool	Purpose	Parameters
`search_source_location`	Search for specific content in blocks.json	`doc_id: str`, `query: str`, `block_types: list`

Knowledge graph

Tool	Purpose	Parameters
`consult_knowledge_graph`	Cross-document RAG query	`query: str`, `mode: str`
`export_knowledge_graph`	Export graph (JSON/Mermaid)	`format: str`, `limit: int`

📂 MCP Resources (dynamically updated)

Resources are updated automatically, allowing you to directly browse the document outline:

Resource URI	Description
`documents://list`	List of all processed documents
`document://{doc_id}/outline`	📋 Full document outline(recommended starting point)
`document://{doc_id}/manifest`	Full manifest JSON
`document://{doc_id}/figures`	Image list (ID, page number, dimensions)
`document://{doc_id}/tables`	Table list
`document://{doc_id}/sections`	Section hierarchy structure
`knowledge-graph://summary`	Knowledge graph statistics overview

Resource usage examples

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

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

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

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

📋 Standard operating procedure

1️⃣ PDF import (ETL)

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

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

Example call：

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

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

2️⃣ View document structure

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

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

Example call：

list_documents()
inspect_document_manifest(doc_id="abc123def")

Manifest content：

📊 Tables: tab_1, tab_2... (ID, page number)
🖼️ Figures: fig_2_1, fig_3_1... (ID, dimensions, page number)
📑 Sections: sec_intro, sec_methods... (title, line number)

3️⃣ Retrieve specific assets

Retrieve images (⚠️ one at a time)

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

Retrieve tables

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

Retrieve sections/full text

# 特定章節
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️⃣ Knowledge graph query

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

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

Query mode：

Mode	Purpose	Suitable scenarios
`local`	Detail query	Specific drug dosages, concrete data
`global`	Global mode	Cross-document trends, topic summarization
`hybrid`	Hybrid mode (recommended)	General Q&A

Example call：

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

5️⃣ Knowledge graph visualization ✨ NEW

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

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

Output format：

Format	Purpose	Recommended limit
`summary`	Statistics + sample nodes	50 (default)
`mermaid`	Mermaid flowchart	20-30
`json`	Full node/edge JSON	100+

Example call：

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

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

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

Mermaid output example：

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

🎯 Scenario examples

Scenario A: Analyze a new PDF paper

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

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

Scenario B: Extract figures and tables

使用者：「給我 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

Scenario C: Cross-document comparison

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

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

Scenario D: Explore the knowledge graph

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

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

⚡ Context budget

Asset type	Approximate token count	Recommendation
Section (1 page)	~500-1000	✅ Prefer to use
Table	~200-500	✅ Low cost
Figure (base64)	~200K-500K	⚠️ One at a time
Full text (10 pages)	~10K-20K	⚠️ As needed
Knowledge Graph (summary)	~500	✅ Quick overview
Knowledge Graph (mermaid)	~1K-3K	✅ Visualization

📊 Output format

After the operation, report:

## 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` 視覺化

About this skill

Description

Trigger Conditions

🔧 Dual Engine Strategy

Marker produces additional data

⚠️ Important Warnings

🖼️ Image Context Limitations

👁️ Vision Capability Reminder

📸 Image ID Naming Rules

🔧 Available MCP Tools

Document Processing

Asset Query

Section Navigation 🧭 (requires Marker blocks.json)

Block search (Marker blocks)

Knowledge graph

📂 MCP Resources (dynamically updated)

Resource usage examples

📋 Standard operating procedure

1️⃣ PDF import (ETL)

2️⃣ View document structure

3️⃣ Retrieve specific assets

Retrieve images (⚠️ one at a time)

Retrieve tables

Retrieve sections/full text

4️⃣ Knowledge graph query

5️⃣ Knowledge graph visualization ✨ NEW

🎯 Scenario examples

Scenario A: Analyze a new PDF paper

Scenario B: Extract figures and tables

Scenario C: Cross-document comparison

Scenario D: Explore the knowledge graph

⚡ Context budget

📊 Output format