Dr Cook:literature Downloader

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

Optional

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 patterns
• oa-sources.md — Open access source patterns, publisher OA portal URLs, and fallback download list format