### Start MCP Server with Uvicorn

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Installs dependencies and starts the MCP Server using Uvicorn. Supports different transport modes by setting environment variables.

```bash
cd mcp_server
uv sync                          # 安装独立依赖
uv run python -m uniparser_mcp   # 启动（stdio 模式）

# 切换传输模式
UNIPARSER_MCP_TRANSPORT=streamable-http \
FASTMCP_HOST=0.0.0.0 \
FASTMCP_PORT=8080 \
uv run python -m uniparser_mcp
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Install project dependencies in the mcp_server directory using uv to avoid conflicts with the main project.

```bash
cd mcp_server
uv sync
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Example JSON configuration for MCP servers, specifying the command, arguments, and environment variables for the uniparser service.

```json
{
  "mcpServers": {
    "uniparser": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/UniParser-Tools/src/mcp_server",
        "python",
        "-m",
        "uniparser_mcp"
      ],
      "env": {
        "UNIPARSER_BASE_URL": "http://127.0.0.1:40001",
        "UNIPARSER_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Initialize UniParser Client and Setup Output Directory

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

Initializes the `UniParserClient` with the host URL and API key. It also creates a local directory to save the cropped images. Replace 'xxxxxxx' with your actual API key.

```python
host = "https://uniparser.dp.tech/"  # 官网

# 替换为你的认证 api key
api_key = "xxxxxxx"
# 初始化客户端
parser = UniParserClient(host=host, api_key=api_key)

# 创建一个目录来保存切图结果
save_dir = "./outputs/crop_images"
os.makedirs(save_dir, exist_ok=True)
print("✅ 准备就绪")
```

--------------------------------

### Install UniParser-Tools

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Install the UniParser-Tools package using pip. You can install from a requirements file or as an editable package.

```bash
pip install -r requirements.txt
```

```bash
pip install -e .
```

--------------------------------

### Install UniParser Tools Dependencies

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Install the necessary dependencies for UniParser Tools using pip. This can be done by installing from a requirements file or in editable mode.

```bash
pip install -r requirements.txt
# 或以可编辑包形式安装
pip install -e .
```

--------------------------------

### Run UniParser User Service

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Typical command to start the UniParser user service. Ensure UNIPARSER_BASE_URL is set to http://127.0.0.1:40001 for local development.

```bash
python services/server_user.py
```

--------------------------------

### Initialize UniParser Client

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/01.quick_start.ipynb

Initialize the UniParser client with the host URL and API key. Ensure to handle API key securely, for example, by using environment variables. Note the concurrency limits for public services.

```python
# 目前有多个可用host开启，但是不同host对应功能不完全相同，解析质量也不一样
# 具体请在售后群中咨询相关的的host信息和功能
# 使用时请勿并发数量过大，公开 অনুমতি Uni-Parser 服务最高仅允许5并发

host = "https://uniparser.dp.tech/"  # 官网

# 替换为你的认证 api key
api_key = os.getenv('UNIPARSER_API_KEY')

# 初始化客户端
parser = UniParserClient(host=host, api_key=api_key)

# 创建一个目录来保存解析结果
save_dir = "./outputs/quick_start"
os.makedirs(save_dir, exist_ok=True)
```

--------------------------------

### Get Formatted Parsing Results in Markdown

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Retrieve formatted parsing results for a given token. This example specifically requests Markdown format for content, tables, and equations, suitable for LLM consumption.

```python
from uniparser_tools.common.constant import FormatFlag

# Get Markdown formatted full text content
result = parser.get_formatted(
    token,
    content=True,
    textual=FormatFlag.Markdown,
    table=FormatFlag.Markdown,
    equation=FormatFlag.Markdown,
)

if result["status"] == "success":
    print(result["content"])
```

--------------------------------

### Run Tests with uv

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Install development dependencies and run tests using pytest. Use -s or --capture=no to see print statements.

```bash
cd mcp_server
uv sync --extra dev
uv run pytest tests/ -v
```

```bash
uv run pytest tests/ -v -s
```

```bash
uv run pytest tests/ -v --capture=no
```

--------------------------------

### Import Dependencies for PDF Image Cropping

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

Imports necessary libraries including `json`, `os`, `requests`, `collections`, `pathlib`, `fitz` (PyMuPDF), `PIL` (Pillow), and UniParser client components. Ensure `PyMuPDF`, `Pillow`, and `requests` are installed.

```python
import json
import os
import time
import requests
from collections import Counter
from pathlib import Path

import fitz  # PyMuPDF
from PIL import Image

from uniparser_tools.api.clients import UniParserClient
from uniparser_tools.common.constant import FormatFlag, ParseMode, ParseModeTextual
```

--------------------------------

### Image Processing Output Example

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.molecule_extracrtion.ipynb

Displays the output of an image processing operation, showing the image mode and dimensions.

```text
Result:
<PIL.Image.Image image mode=RGB size=266x152>
```

```text
Result:
<PIL.Image.Image image mode=RGB size=511x350>
```

```text
Result:
<PIL.Image.Image image mode=RGB size=512x337>
```

```text
Result:
<PIL.Image.Image image mode=RGB size=512x323>
```

```text
Result:
<PIL.Image.Image image mode=RGB size=512x339>
```

--------------------------------

### High-Resolution Extraction of Equations from PDF

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

This example shows how to extract 'equation' and 'formula' types with higher resolution by setting DPI to 300. This is useful for elements requiring greater detail.

```python
if os.path.exists(pdf_path):
    out_path2 = os.path.join(save_dir, "equations_highres")
    os.makedirs(out_path2, exist_ok=True)
    
    # 使用 300 DPI
    cropped_files_2 = crop_pdf_elements(
        pdf_path=pdf_path, 
        json_data=json_data, 
        output_dir=out_path2, 
        target_types=['equation', 'formula'],
        dpi=300
    )
```

--------------------------------

### Retrieve parsed results in various formats

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/01.quick_start.ipynb

Retrieve parsed results using the task token. This example demonstrates fetching content in different formats (latex, html, markdown, plain, markup) by iterating through `FormatFlag`. The `content` parameter must be True for formatted output.

```python
# 任务提交成功后，会返回一个token，用于获取解析结果
assert trigger_file_result["status"] == "success"
token = trigger_file_result["token"]
for formatted in list(FormatFlag)[1:]:
    # content must be True
    # formatted 只对objects和content产生作用，pages_dict和pages_tree不受影响
    result = parser.get_formatted(
        token,
        content=True,
        objects=False,
        pages_dict=False,
        pages_tree=False,
        molecule_source=False,
        textual=formatted,
        chart=formatted,
        table=formatted,
        molecule=formatted,
        equation=formatted,
        figure=formatted,
        expression=formatted,
    )
    if result["status"] != "success":
        print(f"Get formatted failed for {formatted}, results is: {json.dumps(result, indent=4)}")
        continue

    head, tail = "", ""
    suffix = ""
    if formatted == "latex":
        head = "\\documentclass{article}\\n\\n\\usepackage{booktabs}\\n\\n\\begin{document}\\n"
        tail = "\\end{document}"
        suffix = "tex"
    elif formatted == "html":
        head = "<html>\n\n<body>\n"
        tail = "</body>\n\n</html>"
        suffix = "html"
    elif formatted == "markdown":
        suffix = "md"
    elif formatted == "plain":
        suffix = "plain"
    elif formatted == "markup":
        suffix = "txt"
    else:
        print(f"Unknown format: {formatted}")
        continue

    with open(f"{save_dir}/{token}.{suffix}", "w") as f:
        if head:
            f.write(head + "\n")
        try:
            f.write(result["content"])
        except Exception:
            pass
        if tail:
            f.write(tail + "\n")
```

--------------------------------

### Parse Local PDF File (Synchronous Mode)

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Submit a local PDF file for parsing using trigger_file. This example uses synchronous mode (sync=True) and configures high-quality OCR for textual elements, equations, and tables, while dumping base64 for charts, figures, and expressions. It also specifies parsing only the first three pages and uses the GapTree ordering method.

```python
from uniparser_tools.common.constant import ParseMode, ParseModeTextual, OrderingMethod

# 科学文献推荐配置（同步模式）
result = parser.trigger_file(
    file_path="./paper.pdf",
    textual=ParseModeTextual.OCRHighQuality,   # 高质 OCR，支持行内公式
    equation=ParseMode.OCRHighQuality,          # 高质公式识别
    table=ParseMode.OCRHighQuality,             # 高质表格识别
    chart=ParseMode.DumpBase64,                 # 图表保留原图 base64
    figure=ParseMode.DumpBase64,                # 图片保留原图 base64
    expression=ParseMode.DumpBase64,            # 化学反应式保留原图
    molecule=ParseMode.OCRFast,                 # 分子结构快速识别
    pages=[1, 2, 3],                            # 可选：仅解析指定页
    ordering_method=OrderingMethod.GapTree,     # 默认排序算法
    sync=True,
)

if result["status"] == "success":
    token = result["token"]
    print(f"解析成功，token: {token}")
else:
    # 所有方法均不抛异常，错误信息统一在 status/description 字段
    print(result.get("description") or result.get("message"))
```

--------------------------------

### Retrieve Raw Parsing Results

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Retrieve the raw parsing results using a token obtained from a previous parsing task. This example requests the full text content, the nested pages tree structure, and the molecule source (SMILES/mol format). The token can be reused without additional charges.

```python
# 获取嵌套树结构（适合复杂语义分析）
result = parser.get_result(
    token,
    content=True,         # 返回全文字符串（LLM 友好）
    objects=False,        # 返回平铺语义块列表
    pages_dict=False,     # 返回按页组织的原始布局
    pages_tree=True,      # 返回带父子关系的嵌套树
    molecule_source=True, # 返回分子 SMILES/mol 源
)

if result["status"] == "success":
    print(result["content"])         # 全文字符串
    pages_tree_raw = result["pages_tree"]  # 原始 dict，需用 dict2obj 转换
```

--------------------------------

### Parse Image File

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Submit an image file (e.g., PNG, JPG) for parsing using trigger_snip. This example configures fast OCR for textual elements and molecules, and high-quality OCR for tables. The image will be automatically converted to base64 for upload.

```python
from uniparser_tools.common.constant import ParseMode, ParseModeTextual

result = parser.trigger_snip(
    snip_path="./figure.png",
    textual=ParseModeTextual.OCRFast,   # 快速 OCR
    equation=ParseMode.OCRFast,          # 快速公式识别
    table=ParseMode.OCRHighQuality,      # 高质表格识别
    molecule=ParseMode.OCRFast,
)

if result["status"] == "success":
    token = result["token"]
    print(f"图片解析提交成功，token: {token}")
```

--------------------------------

### Get Formatted Result

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Retrieves the parsed result in a specified format. The same token can be reused multiple times with different output configurations.

```APIDOC
## Get Formatted Result

### Description
Retrieves the parsed result in a specified format. The same token can be reused multiple times with different output configurations.

### Method
```python
parser.get_formatted(token: str, content: bool, textual: FormatFlag, table: FormatFlag, equation: FormatFlag)
```

### Parameters
#### Path Parameters
- **token** (str) - Required - The token obtained from `trigger_file`.

#### Query Parameters
- **content** (bool) - Optional (default: `True`) - Whether to return the full content.
- **textual** (FormatFlag) - Optional - Formatting flag for textual elements.
- **table** (FormatFlag) - Optional - Formatting flag for table elements.
- **equation** (FormatFlag) - Optional - Formatting flag for equation elements.

### Request Example
```python
from uniparser_tools.common.constant import FormatFlag

result = parser.get_formatted(
    token,
    content=True,
    textual=FormatFlag.Markdown,
    table=FormatFlag.Markdown,
    equation=FormatFlag.Markdown,
)

if result["status"] == "success":
    print(result["content"])
```
```

--------------------------------

### Extract Figures and Tables from PDF

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

This example demonstrates how to use the `crop_pdf_elements` function to extract only 'figure' and 'table' types from a PDF. It sets the DPI to 150 for sufficient clarity for general display.

```python
if os.path.exists(pdf_path):
    out_path1 = os.path.join(save_dir, "figs_and_tables")
    os.makedirs(out_path1, exist_ok=True)
    
    # 裁剪 DPI 我们设为 150，对于一般屏幕展示足够清晰
    cropped_files_1 = crop_pdf_elements(
        pdf_path=pdf_path, 
        json_data=json_data, 
        output_dir=out_path1, 
        target_types=['figure', 'table'],
        dpi=150
    )
```

--------------------------------

### Retrieve formatted parsing results

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/02.advance.ipynb

Retrieves the formatted parsing results using the token obtained from the submission. This example specifically requests the pages_tree structure and applies formatting flags to various extracted elements. Error handling is included for failed retrieval.

```python
assert trigger_file_result["status"] == "success"
token = trigger_file_result["token"]
# token = "e4d85a146b4554c8b23a9753232253cf"
formatted = FormatFlag.Plain  # formatted 只对objects和content产生作用，pages_dict和pages_tree不受影响
result = parser.get_formatted(
    token,
    content=False,
    objects=False,
    pages_dict=False,
    pages_tree=True,
    molecule_source=False,
    textual=formatted,
    chart=formatted,
    table=formatted,
    molecule=formatted,
    equation=formatted,
    figure=formatted,
    expression=formatted,
)
if result["status"] != "success":
    print(f"Get formatted failed for {formatted}, results is: {json.dumps(result, indent=4)}")
```

--------------------------------

### Parse PDF from Public URL

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Submit a PDF file for parsing directly from a public URL using trigger_url. This example specifies 'DigitalExported' mode for textual elements to extract embedded text directly, high-quality OCR for tables and equations, and fast OCR for molecules. An optional proxy can be configured.

```python
from uniparser_tools.common.constant import ParseModeTextual, ParseMode

result = parser.trigger_url(
    pdf_url="https://arxiv.org/pdf/1706.03762",
    textual=ParseModeTextual.DigitalExported,  # 数字原生 PDF，直接提取内嵌文字
    table=ParseMode.OCRHighQuality,
    equation=ParseMode.OCRHighQuality,
    molecule=ParseMode.OCRFast,
    proxy=None,   # 可选：设置 HTTP 代理，如 "http://proxy.example.com:8080"
)

if result["status"] == "success":
    token = result["token"]
    print(f"URL 解析提交成功，token: {token}")
```

--------------------------------

### get_formatted() — Get Formatted Output

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Builds upon `get_result()` by allowing specification of output formats for each semantic type individually (`FormatFlag`). The same token can be used to mix different formats for different semantic types. `marginalia=True` additionally outputs headers, footers, and page numbers.

```APIDOC
## `get_formatted()` — Get Formatted Output

Builds upon `get_result()` by allowing specification of output formats for each semantic type individually (`FormatFlag`). The same token can be used to mix different formats for different semantic types. `marginalia=True` additionally outputs headers, footers, and page numbers.

```python
from uniparser_tools.common.constant import FormatFlag

# Example: Get Markdown for text, HTML for tables, and LaTeX for equations
result = parser.get_formatted(
    token,
    textual=FormatFlag.Markdown,
    table=FormatFlag.HTML,
    equation=FormatFlag.LaTeX,
    marginalia=True,  # Include page headers, footers, and numbers
)

if result["status"] == "success":
    print(result["textual"])
    print(result["table"])
    print(result["equation"])
    print(result["marginalia"])
```
```

--------------------------------

### Submit PDF Parsing Task and Get Token

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

Submits a PDF file for parsing using `parser.trigger_file`. It specifies various parsing modes for different content types like text, tables, molecules, charts, and figures. The function returns a status and a token for retrieving the results.

```python
# 设置解析文件路径
pdf_path = "./tasks/He_Deep_Residual_Learning_CVPR_2016_paper.pdf"

# 提交解析任务
trigger_file_result = parser.trigger_file(
    pdf_path,
    textual=ParseModeTextual.DigitalExported,
    table=ParseMode.OCRFast,
    molecule=ParseMode.OCRFast,
    chart=ParseMode.DumpBase64,
    figure=ParseMode.DumpBase64,
    expression=ParseMode.DumpBase64,
    equation=ParseMode.OCRFast,
)

if trigger_file_result["status"] != "success":
    print(json.dumps(trigger_file_result, indent=4))
    raise Exception("trigger file failed")

token = trigger_file_result['token']
print(f"任务提交成功, Token: {token}")
```

--------------------------------

### get_result() — Get Raw Parsing Result

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Retrieve the parsing result using a token. Supports retrieving results in four output formats by enabling them as needed. The token can be reused, and multiple calls do not incur additional charges. `return_half=False` will block and wait if parsing is not yet complete. `molecule_source=True` returns the original molecule source (SMILES/mol format).

```APIDOC
## `get_result()` — Get Raw Parsing Result

Retrieve the parsing result using a token. Supports retrieving results in four output formats by enabling them as needed. The token can be reused, and multiple calls do not incur additional charges. `return_half=False` will block and wait if parsing is not yet complete. `molecule_source=True` returns the original molecule source (SMILES/mol format).

```python
# Get nested tree structure (suitable for complex semantic analysis)
result = parser.get_result(
    token,
    content=True,         # Return full text string (LLM friendly)
    objects=False,        # Return flattened semantic block list
    pages_dict=False,     # Return original layout organized by page
    pages_tree=True,      # Return nested tree with parent-child relationships
    molecule_source=True, # Return molecule SMILES/mol source
)

if result["status"] == "success":
    print(result["content"])         # Full text string
    pages_tree_raw = result["pages_tree"]  # Raw dict, needs conversion using dict2obj
```
```

--------------------------------

### Initialize UniParser client and set up output directory

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/02.advance.ipynb

Initializes the UniParser client with a host URL and API key. It also creates a directory to save parsing results. Ensure to consult support for valid host information and API keys. Avoid excessive concurrent requests, as public Uni-Parser services have a limit of 5 concurrent requests.

```python
# 目前有多个可用host开启，但是不同host对应功能不完全相同，解析质量也不一样
# 具体请在售后群中咨询相关的的host信息和功能
# 使用时请勿并发数量过大，公开Uni-Parser服务最高仅允许5并发

host = "https://uniparser.dp.tech/"  # 官网

# 替换为你的认证 api key
api_key = os.getenv('UNIPARSER_API_KEY')

# 初始化客户端
parser = UniParserClient(host=host, api_key=api_key)

# 创建一个目录来保存解析结果
save_dir = "./outputs/advance"
os.makedirs(save_dir, exist_ok=True)
```

--------------------------------

### Initialize UniParser Client (Async)

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Initialize the UniParserClient for use in an asynchronous context. Ensure the API key is set via environment variable.

```python
import os
from uniparser_tools.api.clients import UniParserClient

# Set API key
api_key = os.getenv('UNIPARSER_API_KEY')

# Initialize client
parser = UniParserClient(
    host="https://uniparser.dp.tech/",
    api_key=api_key
)
```

--------------------------------

### Initialize UniParserClient

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Initializes the UniParserClient with the host URL and API key. The API key is recommended to be stored in the UNIPARSER_API_KEY environment variable.

```APIDOC
## Initialize UniParserClient

### Description
Initializes the UniParserClient with the host URL and API key. The API key is recommended to be stored in the UNIPARSER_API_KEY environment variable.

### Method
```python
UniParserClient(host: str, api_key: str)
```

### Parameters
#### Path Parameters
- **host** (str) - Required - The base URL of the UniParser service.
- **api_key** (str) - Required - The API key for authentication. It's recommended to use the `UNIPARSER_API_KEY` environment variable.

### Request Example
```python
import os
from uniparser_tools.api.clients import UniParserClient

api_key = os.getenv('UNIPARSER_API_KEY')
parser = UniParserClient(
    host="https://uniparser.dp.tech/",
    api_key=api_key
)
```
```

--------------------------------

### Initialize UniParser Client

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Initialize the UniParserClient with the host URL and API key. The API key is recommended to be stored in the UNIPARSER_API_KEY environment variable.

```python
import os
parser = UniParserClient(
    host="https://uniparser.dp.tech/",
    api_key=os.getenv("UNIPARSER_API_KEY"),
)
```

--------------------------------

### Initialize UniParserClient

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Initialize the UniParserClient with the service host URL and API Key. The API Key is automatically injected via the 'X-API-Key' header and is recommended to be stored in the UNIPARSER_API_KEY environment variable.

```APIDOC
## Initialize UniParserClient

`UniParserClient` is the entry point for all operations. It requires the service root URL and an API Key. The API Key is automatically injected via the `X-API-Key` request header. It is recommended to store it in the `UNIPARSER_API_KEY` environment variable to avoid hardcoding.

```python
import os
from uniparser_tools.api.clients import UniParserClient

parser = UniParserClient(
    host="https://uniparser.dp.tech/",
    api_key=os.getenv("UNIPARSER_API_KEY"),  # Required; raises AssertionError if missing
)

# Check service status
health = parser.health()
print(health)  # {"status": "success"}

version = parser.version()
print(version)  # {"status": "success", "version": "x.y.z"}
```
```

--------------------------------

### Initialize UniParserClient and Check Service Status

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Initialize the UniParserClient with the service host and API key. The API key is recommended to be stored in the UNIPARSER_API_KEY environment variable. After initialization, you can check the service's health and version.

```python
import os
from uniparser_tools.api.clients import UniParserClient

parser = UniParserClient(
    host="https://uniparser.dp.tech/",
    api_key=os.getenv("UNIPARSER_API_KEY"),  # 必填；缺失时抛 AssertionError
)

# 检查服务状态
health = parser.health()
print(health)  # {"status": "success"}

version = parser.version()
print(version)  # {"status": "success", "version": "x.y.z"}
```

--------------------------------

### Core PDF Element Cropping Function

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

This function crops specified element types from a PDF page. It requires PyMuPDF and Pillow to be installed. Ensure the JSON data structure matches the expected format for element bounding boxes.

```python
import fitz
import os
from PIL import Image

# Assuming IMAGE_TYPES and traverse_tree are defined elsewhere
# For example:
IMAGE_TYPES = ['figure', 'table', 'equation', 'formula', 'image']
def traverse_tree(node, page_nodes):
    if 'children' in node:
        for child in node['children']:
            traverse_tree(child, page_nodes)
    else:
        page_nodes.append(node)

def crop_pdf_elements(pdf_path, json_data, output_dir, target_types=None, dpi=150):
    """
    核心切图函数
    """
    if target_types is None:
        target_types = IMAGE_TYPES
        
    # 使用 PyMuPDF 打开原始文档
    doc = fitz.open(pdf_path)
    
    # PDF的默认DPI通常为72，我们通过 scale_factor 放大渲染倍数来提升清晰度
    scale_factor = dpi / 72.0
    
    saved_files = []
    print(f" 开始切图 (DPI: {dpi}) | 目标类型: {target_types} ...")
    
    # 遍历每一页
    for page_idx in range(len(doc)):
        page = doc[page_idx]
        page_data = json_data[page_idx] if isinstance(json_data, list) else json_data
        
        # 1. 展开当前页的节点
        page_nodes = []
        traverse_tree(page_data, page_nodes)
        
        # 过滤出我们需要的目标类型
        target_nodes = [n for n in page_nodes if n.get('type') in target_types]
        if not target_nodes:
            continue
            
        # 2. 将当前PDF页渲染为图片
        mat = fitz.Matrix(scale_factor, scale_factor)
        pix = page.get_pixmap(matrix=mat)
        mode = "RGBA" if pix.alpha else "RGB"
        page_image = Image.frombytes(mode, [pix.width, pix.height], pix.samples)
        
        # 页面真实宽高（注意这和渲染出来的pix宽高的比例就是 scale_factor）
        page_w, page_h = page.rect.width, page.rect.height
        
        # 3. 遍历节点进行裁剪
        for idx, node in enumerate(target_nodes):
            node_type = node.get('type')
            bbox = node.get('bbox')
            if not bbox:
                continue
                
            # bbox格式：{'x1': 0.1, 'y1': 0.1, 'x2': 0.5, 'y2': 0.5}
            # 将相对坐标转换为渲染图片的实际像素坐标
            x1 = int(bbox['x1'] * page_w * scale_factor)
            y1 = int(bbox['y1'] * page_h * scale_factor)
            x2 = int(bbox['x2'] * page_w * scale_factor)
            y2 = int(bbox['y2'] * page_h * scale_factor)
            
            # 防御性判断坐标是否有效
            if x2 <= x1 or y2 <= y1:
                continue
                
            # 在整页图片上执行裁剪
            cropped = page_image.crop((x1, y1, x2, y2))
            
            # 保存文件
            filename = f"page{page_idx:03d}_{node_type}_{idx:03d}.png"
            filepath = os.path.join(output_dir, filename)
            cropped.save(filepath, 'PNG')
            saved_files.append(filepath)
            
        print(f"✅ 第 {page_idx} 页: 裁剪了 {len(target_nodes)} 张图片")
        
    doc.close()
    print(f"🎉 切图完成！共保存在 {output_dir} 下的 {len(saved_files)} 个文件中.\n")
    return saved_files
```

--------------------------------

### Import necessary libraries

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/01.quick_start.ipynb

Import the required libraries for using UniParser Tools.

```python
import json
import os

from uniparser_tools.api.clients import UniParserClient
from uniparser_tools.common.constant import FormatFlag, ParseMode, ParseModeTextual
from uniparser_tools.utils.convert import dict2obj
```

--------------------------------

### Configure MCP Server for AI Assistants

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Configuration for integrating UniParser's MCP Server with AI assistants like Cursor or Claude Code. Specifies the command, arguments, and environment variables for the server.

```json
{
  "mcpServers": {
    "uniparser": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/UniParser-Tools/mcp_server",
        "python",
        "-m",
        "uniparser_mcp"
      ],
      "env": {
        "UNIPARSER_BASE_URL": "http://127.0.0.1:40001",
        "UNIPARSER_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Run UniParser MCP Server Locally

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Commands to run the UniParser MCP server locally. Ensure environment variables UNIPARSER_BASE_URL and UNIPARSER_API_KEY are set.

```bash
cd mcp_server
uv run python -m uniparser_mcp
```

```bash
uv run uniparser-mcp
```

--------------------------------

### Run Integration Tests

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Specific command to run only integration tests. Set UNIPARSER_INTEGRATION=0 to skip integration tests if no backend service is available.

```bash
uv run pytest tests/test_client_integration.py -v
```

```bash
UNIPARSER_INTEGRATION=0 uv run pytest tests/ -v
```

--------------------------------

### Run Tests with Logging Enabled

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/mcp_server/README.md

Run tests with logging enabled to DEBUG level and output directed to the console.

```bash
uv run pytest tests/ -v -s -o log_cli=true -o log_cli_level=DEBUG
```

--------------------------------

### Import necessary libraries for UniParser

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/02.advance.ipynb

Imports essential libraries from the uniparser_tools package and IPython.display for displaying content.

```python
import json
import os

from IPython.display import HTML, Latex, Markdown, display

from uniparser_tools.api.clients import UniParserClient
from uniparser_tools.common.constant import FormatFlag, ParseMode, ParseModeTextual
from uniparser_tools.utils.convert import dict2obj
from uniparser_tools.utils.processor import tree_repr
```

--------------------------------

### trigger_file() — Parse Local PDF File

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Submit a local PDF file for parsing. `sync=True` (default) waits synchronously for parsing to complete. `sync=False` returns a token immediately for background parsing, with results optionally sent via `callback_url`. Parsing modes for seven semantic types (textual, table, equation, chart, figure, expression, molecule) can be configured individually. The `pages` parameter allows limiting parsing to specific page numbers.

```APIDOC
## `trigger_file()` — Parse Local PDF File

Submit a local PDF file for parsing. `sync=True` (default) waits synchronously for parsing to complete. `sync=False` returns a token immediately for background parsing, with results optionally sent via `callback_url`. Parsing modes for seven semantic types (`textual`, `table`, `equation`, `chart`, `figure`, `expression`, `molecule`) can be configured individually. The `pages` parameter allows limiting parsing to specific page numbers.

```python
from uniparser_tools.common.constant import ParseMode, ParseModeTextual, OrderingMethod

# Recommended configuration for scientific literature (synchronous mode)
result = parser.trigger_file(
    file_path="./paper.pdf",
    textual=ParseModeTextual.OCRHighQuality,   # High-quality OCR, supports inline formulas
    equation=ParseMode.OCRHighQuality,          # High-quality equation recognition
    table=ParseMode.OCRHighQuality,             # High-quality table recognition
    chart=ParseMode.DumpBase64,                 # Charts retain original image as base64
    figure=ParseMode.DumpBase64,                # Figures retain original image as base64
    expression=ParseMode.DumpBase64,            # Chemical reaction formulas retain original image
    molecule=ParseMode.OCRFast,                 # Fast molecule structure recognition
    pages=[1, 2, 3],                            # Optional: parse only specified pages
    ordering_method=OrderingMethod.GapTree,     # Default sorting algorithm
    sync=True,
)

if result["status"] == "success":
    token = result["token"]
    print(f"Parsing successful, token: {token}")
else:
    # All methods do not throw exceptions; error information is uniformly in status/description fields
    print(result.get("description") or result.get("message"))
```
```

--------------------------------

### Parse PDF File with High Quality Settings

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/README.md

Trigger file parsing with high-quality OCR settings for text, equations, and tables. Other elements like charts and figures are set to return original image Base64, and expressions to fast OCR.

```python
from uniparser_tools.common.constant import ParseMode, ParseModeTextual

# Scientific literature parsing mode (recommended defaults)
result = parser.trigger_file(
    pdf_path="./example.pdf",
    textual=ParseModeTextual.OCRHighQuality,  # high quality
    equation=ParseMode.OCRHighQuality,        # high quality
    table=ParseMode.OCRHighQuality,           # high quality
    chart=ParseMode.DumpBase64,               # original image base64
    figure=ParseMode.DumpBase64,              # original image base64
    expression=ParseMode.DumpBase64,          # original image base64
    molecule=ParseMode.OCRFast,               # fast
)

if result["status"] == "success":
    token = result["token"]
    print(f"Parsing successful, token: {token}")
```

--------------------------------

### Submit a PDF parsing task

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/02.advance.ipynb

Submits a PDF file for parsing by the UniParser service. It specifies the parsing modes for different elements like text, tables, molecules, charts, figures, expressions, and equations. Check the status and retrieve the token upon successful submission.

```python
# 设置解析文件路径
pdf_path = "./tasks/He_Deep_Residual_Learning_CVPR_2016_paper.pdf"

# 提交解析任务
trigger_file_result = parser.trigger_file(
    pdf_path,
    textual=ParseModeTextual.DigitalExported,
    table=ParseMode.OCRFast,
    molecule=ParseMode.OCRFast,
    chart=ParseMode.DumpBase64,
    figure=ParseMode.DumpBase64,
    expression=ParseMode.DumpBase64,
    equation=ParseMode.OCRFast,
)
if trigger_file_result["status"] != "success":
    print(json.dumps(trigger_file_result, indent=4))
    raise Exception("trigger file failed")
print(f"trigger file success, token is: {trigger_file_result['token']}")
```

--------------------------------

### Submit a file parsing task

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/01.quick_start.ipynb

Submit a file for parsing using the `trigger_file` method. Specify parsing modes for different content types like text, equations, tables, and figures. Check the status and retrieve the task token upon success.

```python
# 设置解析文件路径
pdf_path = "./tasks/He_Deep_Residual_Learning_CVPR_2016_paper.pdf"

# 提交解析任务（科学文献解析模式默认值）
# textual/equation/table: high quality ; chart/figure/expression: 原图 base64 ; molecule: fast
trigger_file_result = parser.trigger_file(
    pdf_path,
    textual=ParseModeTextual.OCRHighQuality,
    equation=ParseMode.OCRHighQuality,
    table=ParseMode.OCRHighQuality,
    chart=ParseMode.DumpBase64,
    figure=ParseMode.DumpBase64,
    expression=ParseMode.DumpBase64,
    molecule=ParseMode.OCRFast,
)
if trigger_file_result["status"] != "success":
    print(json.dumps(trigger_file_result, indent=4))
    raise Exception("trigger file failed")
print(trigger_file_result['token'])
```

--------------------------------

### Perform BBox Geometric Operations

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Iterate through parsed items to access and print BBox properties like area, dimensions, and coordinates. Demonstrates calculating IoU, intersection, union, and expanding/shrinking BBoxes. Requires `BBox`, `Point`, and `dict2obj` from `uniparser_tools.utils`.

```python
from uniparser_tools.utils.bbox import BBox, Point
from uniparser_tools.utils.convert import dict2obj

result = parser.get_result(token, pages_tree=True)
pages_tree = dict2obj(result["pages_tree"])

for page in pages_tree:
    for item in page:
        bbox = item.bbox
        print(f"面积: {bbox.area}")
        print(f"宽×高: {bbox.width} × {bbox.height}")
        print(f"左上角: {bbox.tl}  右下角: {bbox.br}  中心: {bbox.ctr}")
        print(f"xyxy: {bbox.xyxy}")  # (x1, y1, x2, y2)
        print(f"xywh: {bbox.xywh}")  # (x, y, w, h)

        # 与另一个 bbox 求 IoU / 交集 / 并集
        other = page[1].bbox if len(page) > 1 else bbox
        print(f"IoU: {bbox.iou(other):.3f}")
        print(f"交集: {bbox.intersection(other)}")
        print(f"并集: {bbox.union(other)}")

        # 扩展/收缩
        expanded = bbox.expand(pix=5, wh=None)
        shrunken = bbox.shrink(pix=3, wh=None)
```

--------------------------------

### Bounding Box Operations

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/skills/UniParser-Tools/utilities.md

Utilize the `BBox` class for geometric calculations and operations on bounding boxes, including area, dimensions, intersection over union (IoU), and expansion/shrinking.

```python
from uniparser_tools.utils.bbox import BBox, Point

# BBox propertiesbox.area        # Areabox.width       # Widthbox.height      # Heightbox.tl          # Top-left pointbox.br          # Bottom-right pointbox.ctr         # Center pointbox.xyxy        # (x1, y1, x2, y2) tuplebox.xywh        # (x, y, w, h) tuple

# BBox operationsbox.iou(other)           # Intersection over Unionbox.iof(other)           # Intersection over Foregroundbox.intersection(other)  # Intersection boxbox.union(other)         # Union boxbox.expand(pix, wh)      # Expand by pixelsbox.shrink(pix, wh)      # Shrink by pixels
```

--------------------------------

### trigger_snip() — Parse Image File

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Submit an image file (PNG/JPG, etc.) for parsing. The image is automatically converted to base64 before upload. Parameters are identical to `trigger_file()`, suitable for screenshots, single-page scans, etc.

```APIDOC
## `trigger_snip()` — Parse Image File

Submit an image file (PNG/JPG, etc.) for parsing. The image is automatically converted to base64 before upload. Parameters are identical to `trigger_file()`, suitable for screenshots, single-page scans, etc.

```python
from uniparser_tools.common.constant import ParseMode, ParseModeTextual

result = parser.trigger_snip(
    snip_path="./figure.png",
    textual=ParseModeTextual.OCRFast,   # Fast OCR
    equation=ParseMode.OCRFast,          # Fast equation recognition
    table=ParseMode.OCRHighQuality,      # High-quality table recognition
    molecule=ParseMode.OCRFast,
)

if result["status"] == "success":
    token = result["token"]
    print(f"Image parsing submitted successfully, token: {token}")
```
```

--------------------------------

### Debug Tree Representation

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/skills/UniParser-Tools/utilities.md

Use `tree_repr` to visualize the hierarchical structure of nested groups for debugging purposes. Set `verbose=True` to include bounding box information.

```python
from uniparser_tools.utils.processor import tree_repr

# Example output:
# group
# ├── figuregroup
# │   ├── figure
# │   └── figurecaption
# └─ tablegroup
#     ├── table
#     └─ tablecaption

print(tree_repr(item, verbose=False))  # verbose=True includes bbox
```

--------------------------------

### trigger_url() — Parse Public Network PDF URL

Source: https://context7.com/dptech-corp/uniparser-tools/llms.txt

Submit a PDF parsing task via a URL. The server directly downloads the file from the specified URL, eliminating the need for local storage. Optional proxy parameters are supported.

```APIDOC
## `trigger_url()` — Parse Public Network PDF URL

Submit a PDF parsing task via a URL. The server directly downloads the file from the specified URL, eliminating the need for local storage. Optional proxy parameters are supported.

```python
from uniparser_tools.common.constant import ParseModeTextual, ParseMode

result = parser.trigger_url(
    pdf_url="https://arxiv.org/pdf/1706.03762",
    textual=ParseModeTextual.DigitalExported,  # Digitally native PDF, extracts embedded text directly
    table=ParseMode.OCRHighQuality,
    equation=ParseMode.OCRHighQuality,
    molecule=ParseMode.OCRFast,
    proxy=None,   # Optional: set HTTP proxy, e.g., "http://proxy.example.com:8080"
)

if result["status"] == "success":
    token = result["token"]
    print(f"URL parsing submitted successfully, token: {token}")
```
```

--------------------------------

### Retrieve Pages Tree Data

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/playground/app.crop_images.ipynb

Polls the UniParser API using the obtained token to fetch the `pages_tree` data. This process retries up to 5 times with a 3-second delay between attempts if the data is not immediately available. The `pages_tree` contains detailed structural information, including bounding boxes.

```python
# 等待并获取 pages_tree 数据
json_data = None
print("正在获取 pages_tree 数据...")
for i in range(5):
    result = parser.get_formatted(
        token,
        content=False,
        objects=False,
        pages_dict=False,
        pages_tree=True,
        molecule_source=False,
        textual=FormatFlag.Plain,
    )
    
    if result.get("status") == "success" and result.get("pages_tree") is not None:
        json_data = result["pages_tree"]
        print(f"✅ 获取成功，共 {len(json_data)} 页数据")
        break
    
    print(f"⏳ 数据尚未准备好，等待重试... ({i+1}/5)")
    time.sleep(3)

if not json_data:
    raise Exception("获取 pages_tree 数据失败")
```

--------------------------------

### Text Processing Utilities

Source: https://github.com/dptech-corp/uniparser-tools/blob/main/skills/UniParser-Tools/utilities.md

Employ functions like `is_head_of_paragraph` and `is_tail_of_paragraph` to identify paragraph boundaries. `find_figure_caption_kws` extracts keywords from figure captions.

```python
from uniparser_tools.utils.processor import (
    is_head_of_paragraph,
    is_tail_of_paragraph,
    find_figure_caption_kws,
    recursive_required_items,
    recursive_required_content,
)

# Check if text starts like a paragraph heading
is_head_of_paragraph("Figure 3 shows...")  # True

# Check if text ends like a paragraph
is_tail_of_paragraph("the results.")  # True

# Extract figure keywords from caption
kws = find_figure_caption_kws("See Figure 3 and Table S2")
# Returns: ["Fig3", "TableS2"]

# Recursively extract items of specific types
items = recursive_required_items(group, required_types=[LayoutType.Paragraph])
content = recursive_required_content(group, required_types=[...])
```