mineru-document-explorer

name	mineru-document-explorer
description	MinerU Document Explorer — Agent-native knowledge engine. Use when users ask to search their documents, look up information in PDFs/DOCX/PPTX/Markdown, navigate inside large documents, extract tables/figures, or build wiki knowledge bases. Provides three tool groups: information retrieval (query, get, multi_get, status), document deep reading (doc_toc, doc_read, doc_grep, doc_query, doc_elements, doc_links), and knowledge ingestion (wiki_ingest, doc_write, wiki_lint, wiki_log, wiki_index).
license	MIT
compatibility	Requires qmd CLI or MCP server. Install via npm (npm install -g mineru-document-explorer) or from source (https://github.com/opendatalab/MinerU-Document-Explorer). PDF/DOCX/PPTX support requires Python 3.10+ with pymupdf, python-docx, python-pptx.
metadata	{"author":"MinerU","version":"3.3.0"}
allowed-tools	Bash(qmd:*), mcp__qmd__*, mcp__mineru-document-explorer__*

MinerU Document Explorer

Agent-native knowledge engine — hybrid search and deep reading over Markdown, PDF, DOCX, PPTX. Designed for AI agents to organize knowledge and retrieve information autonomously.

Quick Reference

I want to...	Tool	Example
Search across all docs	query	{ "query": "authentication flow" }
Get a specific file	get	{ "file": "#abc123" } or { "file": "docs/readme.md" }
Get multiple files	multi_get	{ "pattern": "docs/*.md" }
See document structure	doc_toc	{ "file": "paper.pdf" }
Read specific sections	doc_read	{ "file": "paper.pdf", "addresses": ["page:3"] }
Find keyword in a doc	doc_grep	{ "file": "report.md", "pattern": "revenue" }
Semantic search in doc	doc_query	{ "file": "paper.pdf", "query": "methodology" }
Extract tables/figures	doc_elements	{ "file": "report.pdf", "element_types": ["table"] }
Write a wiki page	doc_write	{ "collection": "wiki", "path": "topic.md", "content": "..." }
Check wiki health	wiki_lint	{}

Agent Principles

Follow these rules to use the tools effectively:

1. Collection-relative paths only. All file paths are prefixed by collection name: mydocs/readme.md, papers/survey.pdf. Never use absolute filesystem paths like /Users/.../file.md. You can also use qmd://mydocs/readme.md.

2. Navigate before reading large documents. For PDFs, DOCX, PPTX, or Markdown files >100 lines, always use doc_toc → doc_read instead of get. The get tool dumps the entire document — wasteful for large files.

3. Addresses bridge navigation and reading. doc_toc, doc_grep, and doc_query return address strings like line:45-120. Pass these directly to doc_read. Never call doc_read without addresses from one of these.

4. Use simple query first. Start with { "query": "your terms" }. Only switch to advanced searches mode when simple mode misses. The system auto-expands into BM25 + semantic + reranking.

5. Always pass source when writing wiki pages. This enables provenance tracking and staleness detection via wiki_lint.

6. Prefer MCP over CLI. The MCP server keeps models loaded in memory (~3GB). CLI reloads on every invocation (~5-15s overhead). If MCP is not available, qmd search (BM25 only) is instant and needs no model loading.

Key Concepts

Collections and File Paths

Documents live in collections — named groups with a filesystem path and glob mask. Collections have two types:

• raw (default) — immutable source documents, read-only for agents
• wiki — LLM-maintained pages, agents create/update via doc_write

File paths in all results are collection-relative: mydocs/readme.md, papers/survey.pdf. Use these exact paths when calling tools.

Document IDs (docid)

Every document has a short hash ID like #abc123 shown in search results. Use docids anywhere a file path is accepted: get("#abc123"), doc_toc("#abc123"). The # prefix is optional.

Addresses

Addresses identify locations within a document. They are the bridge between navigation tools (doc_toc, doc_grep, doc_query) and the reading tool (doc_read).

Format	Meaning	Used by
line:N or line:N-M	Line or line range	Markdown
page:N	PDF page	PDF
slide:N	PPTX slide	PPTX
section:N	DOCX section	DOCX

Three Tool Groups (15 tools)

Group	Purpose	Tools
Retrieval	Find and fetch documents	query, get, multi_get, status
Deep Reading	Navigate within a document	doc_toc, doc_read, doc_grep, doc_query, doc_elements, doc_links
Knowledge Ingestion	Build wiki knowledge base	wiki_ingest, doc_write, wiki_lint, wiki_log, wiki_index

---

Playbook 0: First-Run Setup & Configuration

Use when a user first connects MinerU Document Explorer, gives you the project link, or when PDF/DOCX/PPTX operations fail. Walk the user through setup interactively — check each prerequisite and guide them step by step.

Step 1 — Check qmd is installed

which qmd && qmd status

If not installed:

# Option A: npm (recommended)
npm install -g mineru-document-explorer

# Option B: from source
git clone https://github.com/opendatalab/MinerU-Document-Explorer.git
cd MinerU-Document-Explorer && bun install && bun link

Step 2 — Check Python for binary document support

PDF, DOCX, and PPTX processing requires Python 3.10+:

python3 --version

If Python is missing, guide the user to install it for their platform:

• macOS: brew install python@3.12
• Ubuntu/Debian: sudo apt install python3 python3-pip
• Windows: Download from https://python.org

Step 3 — Check and install Python packages

Three packages are required for binary document processing:

python3 -c "import pymupdf; import docx; import pptx; print('All dependencies OK')"

If any import fails, install the missing packages:

pip install pymupdf python-docx python-pptx

Package	Format	What it does
pymupdf	PDF	Text extraction, bookmarks, page-level reading
python-docx	DOCX	Section extraction, table extraction
python-pptx	PPTX	Slide text, table extraction

Step 4 — Ask about advanced PDF processing (optional)

Ask the user: "Do you need high-quality PDF extraction for scanned documents or complex layouts? MinerU Cloud provides significantly better results than basic PyMuPDF."

If yes, guide them to set up MinerU Cloud:

1. Get an API key from https://mineru.net
2. Configure it (pick one method):

# Method A: Environment variable
export MINERU_API_KEY="your-key-here"

# Method B: Config file (~/.config/qmd/doc-reading.json)
mkdir -p ~/.config/qmd
cat > ~/.config/qmd/doc-reading.json << 'EOF'
{
  "docReading": {
    "providers": {
      "fullText": { "pdf": ["mineru_cloud", "pymupdf"] }
    },
    "credentials": {
      "mineru": { "api_key": "YOUR_API_KEY_HERE" }
    }
  }
}
EOF

When MINERU_API_KEY is set, MinerU Cloud is automatically used as the primary PDF provider with PyMuPDF as fallback — no config file needed.

Additional Python package for MinerU Cloud:

pip install mineru-open-sdk

Step 5 — Index documents and verify

# Index a folder (adjust path to user's documents)
qmd collection add ~/Documents --name mydocs --mask '**/*.{md,pdf,docx,pptx}'

# Verify indexing worked
qmd status

# Test search (instant, no model downloads)
qmd search "test"

Step 6 — Configure MCP server (for AI agent integration)

Ask the user which AI client they use and provide the matching config:

Claude Code (~/.claude/settings.json):

{ "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }

Cursor (.cursor/mcp.json) — HTTP mode recommended:

qmd mcp --http --daemon   # start the server first

{ "mcpServers": { "qmd": { "url": "http://localhost:8181/mcp" } } }

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }

Configuration Reference

Config file locations (later overrides earlier):

1. ~/.config/qmd/doc-reading.json — global settings
2. ./qmd.config.json — project-level overrides
3. Environment variables — highest priority

Full config example (~/.config/qmd/doc-reading.json):

{
  "docReading": {
    "providers": {
      "fullText": { "pdf": ["mineru_cloud", "pymupdf"] },
      "toc":      { "pdf": ["native_bookmarks"] },
      "elements": { "docx": ["python_docx_local"], "pptx": ["python_pptx_local"] }
    },
    "credentials": {
      "mineru": {
        "api_key": "your-mineru-api-key",
        "api_url": "https://mineru.net/api/v4"
      },
      "openai": {
        "api_key": "your-openai-api-key",
        "base_url": "https://api.openai.com/v1"
      }
    }
  }
}

Environment variables:

Variable	Purpose
MINERU_API_KEY	MinerU Cloud PDF (auto-enables mineru_cloud provider)
OPENAI_API_KEY	GPT PageIndex (LLM-inferred TOC for PDFs)
OPENAI_BASE_URL	Custom OpenAI-compatible endpoint

Provider options:

Capability	Provider	Requires
PDF full text	pymupdf (default)	pip install pymupdf
PDF full text	mineru_cloud	pip install mineru-open-sdk + API key
PDF full text	mineru_local	pip install mineru-vl-utils[transformers] + model
PDF TOC	native_bookmarks (default)	pip install pymupdf
PDF TOC	gpt_pageindex	pip install tiktoken openai pyyaml + API key
DOCX tables	python_docx_local (default)	pip install python-docx
PPTX tables	python_pptx_local (default)	pip install python-pptx

---

Playbook 1: Search & Answer a Question

Use when the user asks a question and you need to find information.

Step 1 — Search:

query({ "query": "how does authentication work" })

Results include docid, file, score, snippet. Use these to decide what to read.

Step 2 — Read the top result:

If the document is short (snippet suggests it's a small file):

get({ "file": "#abc123" })

If the document is large or structured (PDF, long Markdown):

doc_toc({ "file": "#abc123" })