| name | dr-cook:literature-downloader |
| description | Retrieve full-text academic articles and literature metadata. Use when downloading papers, getting full text from PubMed Central, fetching article metadata by PMID or DOI, or building structured download lists for papers behind paywalls. Triggers on: download paper, get full text, fetch article, retrieve literature, PubMed download, PMC, PMID, DOI lookup, 下载文献, 获取全文, 文献下载, 下载论文, 获取PDF.
|
literature-downloader
1. Overview
literature-downloader retrieves open-access full text and metadata for academic articles using the PubMed MCP server as the primary tool. Three-tier retrieval strategy: (1) PMC full-text via PubMed MCP — highest success rate for biomedical literature; (2) Publisher open-access links from article metadata; (3) Structured download list fallback — when direct retrieval fails, generates a table with DOI, PMID, PMCID, OA status, and direct URLs for manual or institutional access. Does not attempt to bypass paywalls or access subscription-only content. Operates standalone or as a feeder for literature-reviewer in the Grant pipeline.
2. Parameters
Required
| Parameter | Values | Description |
|---|
input_type | pmid | doi | title | search_query | How the article(s) are identified. Infer from format of user input — do not ask unless genuinely ambiguous. |
Optional
| Parameter | Values | Description |
|---|
batch_mode | bool (default: false) | If true, processes a list of identifiers in sequence and returns a consolidated batch report. |
output_format | full_text | metadata_only | download_list (default: full_text if available, else download_list) | Controls the scope of output. If full text is unavailable, automatically falls back to download_list. |
max_results | integer (default: 1 for single identifier; 10 for search_query) | Maximum number of articles to return for search queries. |
Parameter collection rule
Infer input_type from the format of what the user provides: eight-digit number or "PMID: XXXXXXXX" → pmid; "10.XXXX/..." → doi; quoted title → title; natural language topic → search_query. Do not ask unless the input genuinely cannot be classified. Do not ask for optional parameters unless the user has mentioned them.
3. Workflow
Step 1 — Parse input and determine identifier type.
Classify the user's input using the rules in Section 2. If batch_mode is detected (user provides a list of identifiers separated by commas, newlines, or enumerated), set batch_mode = true and apply Steps 2–5 to each identifier in the list; compile a batch report in Step 6.
Step 2 — Resolve identifier to PMID and PMCID.
- If input is a PMID: proceed directly to Step 3 with the PMID.
- If input is a DOI: call
convert_article_ids with the DOI to obtain PMID and PMCID. Consult references/pubmed-mcp-guide.md for parameter syntax.
- If input is a title or search query: call
search_articles with the title or query string. Present the top results (up to max_results) to the user for confirmation before proceeding. Do not retrieve full text for unconfirmed results.
Step 3 — Attempt Tier 1 retrieval: PMC full text.
If a PMCID is available (either supplied directly or obtained via convert_article_ids):
- Call
get_full_text_article with the PMCID. PMCID format must be "PMC" followed by digits (e.g., "PMC9876543").
- If retrieval succeeds: proceed to Step 7 (output).
- If the article is not available in PMC (error "Article not in PMC" or no PMCID exists): proceed to Step 4.
If no PMCID is available: proceed directly to Step 4.
Step 4 — Attempt Tier 2 retrieval: Publisher OA check.
- Call
get_article_metadata with the PMID to retrieve full metadata including OA status, DOI, and available links.
- Consult
references/oa-sources.md for known publisher OA patterns: check the DOI prefix against the publisher table to determine if the article is from a known OA publisher (PLOS, BioMed Central, Frontiers, eLife, PeerJ).
- If a publisher OA link is identified: report the direct URL to the user and attempt retrieval if possible.
- If the article is subscription-only or OA status is unknown: proceed to Step 5.
Step 5 — Tier 3 fallback: Generate structured download list.
Compile all available information into a download list table with the following fields: Title, Authors, Year, Journal, PMID, DOI, PMCID (if any), OA Status, Best URL, Notes.
Include in the Notes field: "Access via institutional VPN and library proxy" for subscription articles, or "Preprint — not peer reviewed" for bioRxiv/medRxiv articles.
State clearly: "This article requires institutional access. Use the download list with your library proxy or university interlibrary loan service."
Step 6 — Batch processing (when batch_mode = true).
Repeat Steps 2–5 for each identifier sequentially. Track outcome per article: full_text, metadata_only, or failed. After all processed, compile a batch report: total count with status breakdown, a per-article table, and a consolidated download list for failed articles. On rate limit errors, process remaining identifiers in smaller groups. See references/pubmed-mcp-guide.md for the batch pattern.
Step 7 — Output results.
Present output per Section 4. Then write context_output per Section 5.
4. Output Format
Single article — full text retrieved
## Article Retrieved
**Title:** [title]
**PMID:** [pmid] **DOI:** [doi] **PMCID:** [pmcid]
**OA Status:** Open Access (PMC) | Open Access (Publisher) | Preprint
**Authors:** [authors] **Year:** [year] **Journal:** [journal]
---
[Full text in markdown; original section headings preserved]
Single article — not retrievable (Tier 3 fallback)
## Download Information
| Field | Value |
|-------|-------|
| Title | ... | PMID | ... | DOI | ... |
| PMCID | None — not deposited in PMC |
| OA Status | Subscription only |
| Best URL | https://doi.org/[doi] |
| Action | Access via institutional library or interlibrary loan |
> This article requires institutional access. Use the download list with your library proxy.
Batch mode report
## Batch Retrieval Report
Retrieved (full text): N | Metadata only: N | Failed (paywall or invalid): N
| # | Title | PMID | DOI | PMCID | OA Status | Retrieval Status | Best URL |
|---|-------|------|-----|-------|-----------|-----------------|----------|
### Failed Articles — Download List
[Consolidated download list table for unretrieved articles]
5. context_output
Reads from upstream
Typically standalone. In pipeline mode, may receive a PMID list from literature-reviewer's references field — treat as batch input with batch_mode = true.
Writes to output
{
"module": "literature-downloader",
"domain": "<if determinable from article content, otherwise null>",
"summary": "Retrieved N articles: N full text, N metadata only, N failed",
"raw_text": "<full text of retrieved article(s); concatenated for batch mode>",
"references": [
{
"pmid": "...",
"doi": "...",
"title": "...",
"authors": "...",
"year": 0,
"retrieval_status": "full_text | metadata_only | failed",
"pmcid": "...",
"oa_status": "open | subscription | unknown"
}
],
"status": "success | partial | failed",
"error_message": "string | null"
}
Status: "success" — full text retrieved, all identifiers resolved. "partial" — mixed outcomes. "failed" — no valid identifiers resolved or MCP unavailable.
Note: references extends the base schema with retrieval_status, pmcid, and oa_status fields.
Downstream readers
raw_text, references → literature-reviewer (synthesis input). references → citation-checker.
6. References
See references/ for:
pubmed-mcp-guide.md — PubMed MCP tool call reference, parameter syntax, expected return structures, and error handling patternsoa-sources.md — Open access source patterns, publisher OA portal URLs, and fallback download list format
