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 ```bash which qmd && qmd status ``` If not installed: ```bash # 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+: ```bash 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: ```bash python3 -c "import pymupdf; import docx; import pptx; print('All dependencies OK')" ``` If any import fails, install the missing packages: ```bash 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): ```bash # 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: ```bash pip install mineru-open-sdk ``` ### Step 5 — Index documents and verify ```bash # 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`): ```json { "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } } ``` **Cursor** (`.cursor/mcp.json`) — HTTP mode recommended: ```bash qmd mcp --http --daemon # start the server first ``` ```json { "mcpServers": { "qmd": { "url": "http://localhost:8181/mcp" } } } ``` **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```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`): ```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:** ```json 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): ```json get({ "file": "#abc123" }) ``` If the document is large or structured (PDF, long Markdown): ```json doc_toc({ "file": "#abc123" })