MinerU OCR Local & API

Parse complex PDFs and document images with MinerU, using either the hosted MinerU API or the local open-source MinerU runtime. Use when Codex needs MinerU-b...

Security Scan

The skill implements MinerU API and local CLI workflows that match its name, but the registry metadata omits required configuration (notably MINERU_API_TOKEN and/or a local MinerU runtime) and SKILL.md contains developer-specific paths — these mismatches and a few scope choices warrant caution before installing or providing credentials.

Purpose & Capability

The code and SKILL.md implement exactly the advertised capability (hosted MinerU API and local open-source MinerU CLI). However the registry metadata claims no required environment variables or binaries, while the runtime actually requires MINERU_API_TOKEN for API mode and a local mineru binary or python -m mineru.cli.client for local mode. That metadata omission is an incoherence the user should be aware of.

Instruction Scope

SKILL.md provides detailed, narrow runtime instructions and enforces 'always use python scripts/mineru_caller.py' and 'do not parse the document yourself', which keeps behavior consistent. Two items to note: (1) SKILL.md points to a local developer path in its verification example (an absolute path under C:/Users/shangfukai/...), which references outside files and appears to be a leftover from the author's environment; (2) the instructions require reading saved JSON envelopes and artifact paths (intended behavior) so agents will report file paths and may write temp files.

Install Mechanism

This is an instruction-and-scripts skill with no install spec. The only external dependency is the httpx Python package (requirements.txt). There are no remote downloads or obscure install URLs in the package, and a mock server and smoke tests are included for local testing.

Credentials

The runtime legitimately uses MINERU_API_TOKEN, MINERU_API_BASE_URL, and multiple MINERU_LOCAL_* environment variables for local execution. Those credentials are proportional to the functionality. The concern is that the skill registry metadata declares 'required env vars: none' and 'primary credential: none', which contradicts the code and SKILL.md that require a token for API mode and/or a configured local runtime.

Persistence & Privilege

The skill does not request special platform privileges, always:false is set, and it does not attempt to modify other skills or system-wide agent settings. It writes results/artifacts to temp directories by design (artifact paths are reported). Autonomous invocation is allowed (default) but not combined with other high-risk flags.

What to consider before installing

This skill largely does what it says (use MinerU API or run a local MinerU CLI), but inspect and test before giving it secrets. Key points to consider before installing or using: 1) MINERU_API_TOKEN is required for API mode — do not set that token unless you trust the MinerU service and want the skill to send your document bytes to the configured MINERU_API_BASE_URL. 2) For local parsing you must install the official MinerU runtime or provide MINERU_LOCAL_CMD or MINERU_LOCAL_PYTHON; the skill will invoke that binary or python module. 3) The registry metadata incorrectly lists no required env vars/binaries — treat that as a packaging error, not a guarantee of no secrets needed. 4) SKILL.md includes a developer-specific verification path; harmless but indicates the package may have come from a local dev environment. 5) Use the included mock_mineru_server.py to run offline tests, and run scripts/smoke_test.py --skip-run to validate imports/config without executing network calls. 6) If you plan to use API mode, prefer creating a scoped, revocable API token and review network calls (or run the mock server first). If you want higher assurance, review the parse_document call paths in scripts/lib.py (it uses httpx and spawns the local mineru CLI) and consider running the skill in a sandbox before granting access to sensitive files or credentials.

Hard Rules

1. Use python scripts/mineru_caller.py for every MinerU request.
2. Do not parse the document yourself as a fallback.
3. If MinerU returns an error, show the error and stop.
4. Treat the saved JSON envelope and generated artifact files as the source of truth.
5. Prefer the top-level text field when the user asks for the full extracted document.

Choose The Mode

• Use --mode api when the user wants the hosted MinerU service, already has MINERU_API_TOKEN, needs URL input, or wants the official cloud API workflow.
• Use --mode local when the user wants the open-source MinerU runtime from https://github.com/opendatalab/MinerU, wants data to stay local, or explicitly asks for local parsing.
• Use --mode auto only when the user does not care which mode is used. auto prefers API when MINERU_API_TOKEN is configured and falls back to local only for local files.

Standard Workflow

1. For a hosted API parse from URL:

   python scripts/mineru_caller.py --mode api --file-url "https://example.com/paper.pdf" --pretty
   

2. For a hosted API parse from a local file:

   python scripts/mineru_caller.py --mode api --file-path "C:/docs/paper.pdf" --pretty
   

3. For a local open-source MinerU parse:

   python scripts/mineru_caller.py --mode local --file-path "C:/docs/paper.pdf" --pretty
   

4. When the input is a local file and the user will need an IDE-accessible path, prefer saving beside the source file:

   python scripts/mineru_caller.py --mode local --file-path "C:/docs/paper.pdf" --download-dir "C:/docs/paper.mineru" --pretty
   

5. Read these output fields before answering:

   • mode: actual execution mode used
   • text: complete document Markdown from full.md or <file_stem>.md
   • result.submit: raw task-creation response for API URL parsing
   • result.batch: raw upload-batch response for API local-file parsing
   • result.poll: final API task-status payload
   • result.local: local MinerU CLI invocation summary
   • artifacts.full_md_path: absolute path to the main Markdown file
   • artifacts.local_parse_dir: local MinerU parse directory when using --mode local
   • artifacts.downloaded_zip: downloaded MinerU archive when using --mode api

Useful Flags

• --mode api|local|auto: choose hosted API, local runtime, or automatic selection
• --no-wait: return after submission without polling; API mode only
• --no-download: skip downloading full_zip_url; API mode only
• --download-dir DIR: store API downloads or local MinerU outputs in a specific directory
• --language en: pass a language hint
• --ocr: force OCR mode
• --disable-formula: turn off formula extraction
• --local-cmd PATH: explicit path to mineru.exe or mineru
• --local-python PATH: explicit Python path for python -m mineru.cli.client
• --local-backend pipeline: choose the local MinerU backend
• --local-method auto|txt|ocr: choose the local MinerU parse method
• --local-model-source modelscope: useful in environments where Hugging Face access is restricted
• --local-device cpu: force a local inference device when needed

Present Results

• If the user asks for all text, show the top-level text field.
• If the user asks where files were saved, report the paths in artifacts.
• If the output is large, give the saved file paths first and then the requested excerpt or summary.
• If API mode completed but archive download failed, report artifacts.full_zip_url.

Configuration

For API mode:

MINERU_API_TOKEN
MINERU_API_BASE_URL=https://mineru.net
MINERU_API_TIMEOUT=60
MINERU_API_POLL_TIMEOUT=900
MINERU_API_POLL_INTERVAL=5

For local mode, configure at least one runtime entry point:

MINERU_LOCAL_CMD=C:\path\to\mineru.exe
MINERU_LOCAL_PYTHON=C:\path\to\python.exe
MINERU_LOCAL_BACKEND=pipeline
MINERU_LOCAL_METHOD=auto
MINERU_LOCAL_LANG=ch
MINERU_LOCAL_MODEL_SOURCE=modelscope
MINERU_LOCAL_DEVICE_MODE=cpu
MINERU_LOCAL_TIMEOUT=3600

Local mode only supports --file-path. It does not accept --file-url.

Error Handling

• Missing API token: show the configuration error and stop.
• Missing local runtime: show the configuration error and stop.
• Failed task or failed local CLI run: show the error and stop.
• Poll timeout: tell the user the task id and that polling timed out.
• API archive download TLS error: rely on the built-in curl fallback before reporting failure.
• Missing expected output files: return any artifact paths that do exist and report the missing output.

References

• references/output_schema.md: JSON envelope and artifact layout for both modes.

Load the reference file when:

• You need to explain which saved files matter.
• You need to inspect mode-specific artifacts such as downloaded_zip, local_parse_dir, middle_json, or content_list.

Verification

Validate the skill folder:

python C:/Users/shangfukai/.codex/skills/.system/skill-creator/scripts/quick_validate.py D:/shangfukai/dev/skills/mineru-ocr-local-api-1.1.0

Check configuration only:

python scripts/smoke_test.py --mode api --skip-run
python scripts/smoke_test.py --mode local --skip-run

Run a local end-to-end test:

python scripts/smoke_test.py --mode local --test-file "D:/path/to/file.pdf"

Run an API end-to-end test:

python scripts/smoke_test.py --mode api --test-url "https://example.com/file.pdf"