@cyanheads/pubmed-mcp-server 2.5.6 → 2.6.0

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.js

@@ -1,32 +1,29 @@
 /**
- * @fileoverview PMC full-text fetch tool. Retrieves full-text articles from PubMed
- * Central via NCBI EFetch with db=pmc. Supports PMCID input or PMID-to-PMCID resolution.
+ * @fileoverview Full-text fetch tool. Primary source is PubMed Central (NCBI
+ * EFetch, `db=pmc`). When a PMID has no PMC copy but does have a DOI,
+ * transparently falls back to Unpaywall to retrieve a legally-deposited
+ * open-access copy (HTML or PDF). Output uses a discriminated union on
+ * `source` so callers can reason about structural reliability per article.
  * @module src/mcp-server/tools/definitions/fetch-fulltext.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { htmlExtractor, pdfParser } from '@cyanheads/mcp-ts-core/utils';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
+import { extractDoi, extractPmid } from '../../../services/ncbi/parsing/article-parser.js';
 import { parsePmcArticle } from '../../../services/ncbi/parsing/pmc-article-parser.js';
 import { findAll, findOne } from '../../../services/ncbi/parsing/pmc-xml-helpers.js';
+import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
+import { getUnpaywallService } from '../../../services/unpaywall/unpaywall-service.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { pmidStringSchema } from './_schemas.js';
 function normalizePmcId(id) {
     return id.replace(/^PMC/i, '');
 }
-async function resolvePmidsToPmcIds(pmids, signal) {
-    const records = await getNcbiService().idConvert(pmids, 'pmid', signal ? { signal } : undefined);
-    const resolved = new Map();
-    for (const record of records) {
-        if (record.pmid !== undefined && record.pmcid) {
-            resolved.set(String(record.pmid), normalizePmcId(String(record.pmcid)));
-        }
-    }
-    return { resolved, unavailable: pmids.filter((pmid) => !resolved.has(pmid)) };
-}
 function filterSections(sections, sectionFilter) {
     const lowerFilter = sectionFilter.map((s) => s.toLowerCase());
     return sections.filter((s) => s.title && lowerFilter.some((f) => s.title?.toLowerCase().includes(f)));
 }
-// ─── Tool Definition ─────────────────────────────────────────────────────────
+// ─── Schemas ─────────────────────────────────────────────────────────────────
 const SubsectionSchema = z
     .object({
     title: z.string().optional().describe('Subsection heading'),
@@ -72,27 +69,82 @@ const PublicationDateSchema = z
     day: z.string().optional().describe('Publication day'),
 })
     .describe('Publication date');
-const FulltextArticleSchema = z
+const PmcArticleSchema = z
     .object({
+    source: z.literal('pmc').describe('Content came from PubMed Central as structured JATS XML'),
     pmcId: z.string().describe('PMC ID'),
     pmcUrl: z.string().describe('PMC URL'),
     pmid: z.string().optional().describe('PubMed ID'),
     pubmedUrl: z.string().optional().describe('PubMed URL'),
+    doi: z.string().optional().describe('DOI'),
     title: z.string().optional().describe('Article title'),
     abstract: z.string().optional().describe('Abstract'),
     authors: z.array(AuthorSchema).optional().describe('Authors'),
-    doi: z.string().optional().describe('DOI'),
+    affiliations: z.array(z.string()).optional().describe('Author affiliations'),
     journal: JournalSchema.optional(),
     keywords: z.array(z.string()).optional().describe('Keywords'),
-    sections: z.array(SectionSchema).describe('Article body sections'),
-    references: z.array(ReferenceSchema).optional().describe('Reference list'),
     articleType: z.string().optional().describe('Article type'),
-    affiliations: z.array(z.string()).optional().describe('Author affiliations'),
     publicationDate: PublicationDateSchema.optional(),
+    sections: z.array(SectionSchema).describe('Article body sections'),
+    references: z.array(ReferenceSchema).optional().describe('Reference list'),
+})
+    .describe('Structured PMC full-text article — reliable section/reference structure');
+const UnpaywallArticleSchema = z
+    .object({
+    source: z
+        .literal('unpaywall')
+        .describe('Content fetched from an open-access copy indexed by Unpaywall. Best-effort — structural fidelity depends on `contentFormat`.'),
+    contentFormat: z
+        .enum(['html-markdown', 'pdf-text'])
+        .describe('How `content` was extracted. html-markdown: Defuddle extracted Markdown from an HTML landing page; light section structure may survive but is not guaranteed. pdf-text: unpdf extracted plain text from a PDF; no section, reference, or heading structure.'),
+    pmid: z.string().describe('PubMed ID the article was resolved from'),
+    pubmedUrl: z.string().describe('PubMed URL'),
+    doi: z.string().describe('DOI used to locate the open-access copy'),
+    sourceUrl: z.string().describe('URL the content was fetched from'),
+    title: z.string().optional().describe('Detected article title when present'),
+    content: z.string().describe('Full article text — Markdown or plain text per `contentFormat`'),
+    wordCount: z
+        .number()
+        .optional()
+        .describe('Approximate word count reported by the HTML extractor; absent for PDFs'),
+    totalPages: z
+        .number()
+        .optional()
+        .describe('Page count reported by the PDF extractor; absent for HTML'),
+    license: z.string().optional().describe('License identifier from Unpaywall (e.g. cc-by, cc0)'),
+    hostType: z
+        .string()
+        .optional()
+        .describe('`publisher` or `repository` — where the OA copy is hosted'),
+    version: z
+        .string()
+        .optional()
+        .describe('OA version: submittedVersion | acceptedVersion | publishedVersion'),
+})
+    .describe('Best-effort full text from an open-access copy');
+const ArticleSchema = z
+    .discriminatedUnion('source', [PmcArticleSchema, UnpaywallArticleSchema])
+    .describe('Full-text article; shape depends on `source` (pmc = structured, unpaywall = best-effort)');
+const UnavailableReasonSchema = z
+    .enum([
+    'no-pmc-fallback-disabled',
+    'no-doi',
+    'no-oa',
+    'fetch-failed',
+    'parse-failed',
+    'service-error',
+])
+    .describe(`Why the PMID has no full text. no-pmc-fallback-disabled: not in PMC and UNPAYWALL_EMAIL is unset so the Unpaywall fallback is off. no-doi: not in PMC and the ID Converter returned no DOI to try Unpaywall with. no-oa: DOI exists but Unpaywall has no open-access copy indexed. fetch-failed: OA location found but the content could not be downloaded. parse-failed: content was downloaded but text extraction produced nothing usable. service-error: Unpaywall or an upstream host returned a server error.`);
+const UnavailableSchema = z
+    .object({
+    pmid: z.string().describe('PMID full text could not be returned for'),
+    reason: UnavailableReasonSchema,
+    detail: z.string().optional().describe('Additional context when available'),
 })
-    .describe('Full-text PMC article');
+    .describe('One PMID that could not be returned with an explanation of why');
+// ─── Tool Definition ─────────────────────────────────────────────────────────
 export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
-    description: 'Fetch full-text articles from PubMed Central (PMC). Returns complete article body text, sections, and references for open-access articles. Accepts PMC IDs directly or PubMed IDs (auto-resolved via the PMC ID Converter).',
+    description: 'Fetch full-text articles. Primary source is PubMed Central (structured JATS with sections and references). When a PMID has no PMC copy, transparently falls back to Unpaywall (open-access copies hosted by publishers or institutional repositories) and returns best-effort HTML-as-Markdown or PDF-as-text. Set UNPAYWALL_EMAIL to enable the fallback. Accepts PMC IDs directly or PubMed IDs (auto-resolved via the PMC ID Converter).',
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([SCHEMA_SCHOLARLY_ARTICLE, EDAM_DATA_RETRIEVAL]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/fetch-fulltext.tool.ts',
@@ -108,28 +160,37 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .min(1)
             .max(10)
             .optional()
-            .describe('PubMed IDs to resolve to PMC full text. Provide this OR pmcids, not both. Only works for open-access articles available in PMC.'),
-        includeReferences: z.boolean().default(false).describe('Include reference list'),
+            .describe('PubMed IDs. Articles in PMC are returned as structured JATS. Articles not in PMC are retrieved from Unpaywall when UNPAYWALL_EMAIL is set and a DOI is available. Provide this OR pmcids, not both.'),
+        includeReferences: z
+            .boolean()
+            .default(false)
+            .describe('Include reference list. Applies to `source=pmc` results only.'),
         maxSections: z
             .number()
             .int()
             .min(1)
             .max(50)
             .optional()
-            .describe('Maximum top-level body sections'),
+            .describe('Maximum top-level body sections. Applies to `source=pmc` results only.'),
         sections: z
             .array(z.string())
             .optional()
-            .describe('Filter to specific sections by title, case-insensitive (e.g. ["Introduction", "Methods", "Results", "Discussion"])'),
+            .describe('Filter to specific sections by title, case-insensitive (e.g. ["Introduction", "Methods", "Results", "Discussion"]). Applies to `source=pmc` results only.'),
     }),
     output: z.object({
-        articles: z.array(FulltextArticleSchema).describe('Full-text articles'),
+        articles: z.array(ArticleSchema).describe('Full-text articles'),
         totalReturned: z.number().describe('Number of articles returned'),
-        unavailablePmids: z.array(z.string()).optional().describe('PMIDs not available in PMC'),
-        unavailablePmcIds: z.array(z.string()).optional().describe('PMC IDs that returned no data'),
+        unavailable: z
+            .array(UnavailableSchema)
+            .optional()
+            .describe('Per-PMID explanations for any requested PMIDs with no returnable full text'),
+        unavailablePmcIds: z
+            .array(z.string())
+            .optional()
+            .describe('PMC IDs requested directly that returned no data'),
     }),
     async handler(input, ctx) {
-        ctx.log.info('Executing pubmed_pmc_fetch', {
+        ctx.log.info('Executing pubmed_fetch_fulltext', {
             hasPmcids: !!input.pmcids,
             hasPmids: !!input.pmids,
             idCount: (input.pmcids ?? input.pmids)?.length,
@@ -138,135 +199,373 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             throw new Error('Either pmcids or pmids must be provided');
         if (input.pmcids && input.pmids)
             throw new Error('Provide pmcids or pmids, not both');
-        let pmcIds;
-        let unavailablePmids;
+        // ── PMID path: resolve to PMC + collect unresolved PMIDs for Unpaywall fallback ──
+        let pmcIds = [];
+        let fallbackCandidates = [];
         if (input.pmids) {
-            const resolution = await resolvePmidsToPmcIds(input.pmids, ctx.signal);
-            if (resolution.resolved.size === 0) {
-                return { articles: [], totalReturned: 0, unavailablePmids: input.pmids };
+            const records = await getNcbiService().idConvert(input.pmids, 'pmid', ctx.signal ? { signal: ctx.signal } : undefined);
+            const seen = new Set();
+            for (const r of records) {
+                if (r.pmid === undefined)
+                    continue;
+                const pmid = String(r.pmid);
+                seen.add(pmid);
+                if (r.pmcid) {
+                    pmcIds.push(normalizePmcId(String(r.pmcid)));
+                }
+                else {
+                    fallbackCandidates.push({ pmid, ...(r.doi && { doi: r.doi }) });
+                }
+            }
+            // Any requested PMIDs the converter didn't return at all: treat as fallback candidates.
+            for (const requested of input.pmids) {
+                if (!seen.has(requested))
+                    fallbackCandidates.push({ pmid: requested });
             }
-            pmcIds = [...resolution.resolved.values()];
-            if (resolution.unavailable.length > 0)
-                unavailablePmids = resolution.unavailable;
         }
         else {
             pmcIds = (input.pmcids ?? []).map(normalizePmcId);
         }
-        const xmlData = await getNcbiService().eFetch({ db: 'pmc', id: pmcIds.join(','), retmode: 'xml' }, {
-            retmode: 'xml',
-            useOrderedParser: true,
-            usePost: pmcIds.length > 5,
-            signal: ctx.signal,
-        });
-        const articleSet = findOne(xmlData, 'pmc-articleset');
-        if (!articleSet) {
-            throw new Error('Invalid PMC EFetch response: missing pmc-articleset');
+        // ── PMC fetch ───────────────────────────────────────────────────────────
+        let pmcArticles = [];
+        let unavailablePmcIds;
+        if (pmcIds.length > 0) {
+            const xmlData = await getNcbiService().eFetch({ db: 'pmc', id: pmcIds.join(','), retmode: 'xml' }, {
+                retmode: 'xml',
+                useOrderedParser: true,
+                usePost: pmcIds.length > 5,
+                signal: ctx.signal,
+            });
+            const articleSet = findOne(xmlData, 'pmc-articleset');
+            if (!articleSet)
+                throw new Error('Invalid PMC EFetch response: missing pmc-articleset');
+            let parsed = findAll(articleSet, 'article').map(parsePmcArticle);
+            if (input.sections?.length) {
+                const sectionFilter = input.sections;
+                parsed = parsed.map((a) => ({ ...a, sections: filterSections(a.sections, sectionFilter) }));
+            }
+            if (input.maxSections !== undefined) {
+                parsed = parsed.map((a) => ({ ...a, sections: a.sections.slice(0, input.maxSections) }));
+            }
+            if (!input.includeReferences) {
+                parsed = parsed.map(({ references: _, ...rest }) => rest);
+            }
+            pmcArticles = parsed.map((a) => ({ source: 'pmc', ...a }));
+            const returnedPmcIds = new Set(pmcArticles.map((a) => a.pmcId));
+            const missing = pmcIds.map((id) => `PMC${id}`).filter((id) => !returnedPmcIds.has(id));
+            if (missing.length > 0)
+                unavailablePmcIds = missing;
         }
-        let articles = findAll(articleSet, 'article').map(parsePmcArticle);
-        if (input.sections?.length) {
-            const sectionFilter = input.sections;
-            articles = articles.map((a) => ({
-                ...a,
-                sections: filterSections(a.sections, sectionFilter),
-            }));
+        // ── Unpaywall fallback for PMIDs not in PMC ─────────────────────────────
+        const unpaywall = getUnpaywallService();
+        const unavailable = [];
+        const fallbackArticles = [];
+        if (fallbackCandidates.length > 0) {
+            if (!unpaywall) {
+                for (const c of fallbackCandidates) {
+                    unavailable.push({
+                        pmid: c.pmid,
+                        reason: 'no-pmc-fallback-disabled',
+                        detail: 'Article not in PMC and UNPAYWALL_EMAIL is not set',
+                    });
+                }
+            }
+            else {
+                // The PMC ID Converter only returns DOIs for articles it has in PMC, so
+                // candidates here are missing DOIs by default. Pull them from PubMed
+                // metadata (db=pubmed) before dispatching to Unpaywall.
+                const needDoi = fallbackCandidates.filter((c) => !c.doi).map((c) => c.pmid);
+                if (needDoi.length > 0) {
+                    try {
+                        const doiMap = await fetchPubmedDois(needDoi, ctx.signal);
+                        fallbackCandidates = fallbackCandidates.map((c) => {
+                            if (c.doi)
+                                return c;
+                            const doi = doiMap.get(c.pmid);
+                            return doi ? { ...c, doi } : c;
+                        });
+                    }
+                    catch (error) {
+                        ctx.log.warning('Failed to batch-fetch DOIs from PubMed for Unpaywall fallback', {
+                            error: error instanceof Error ? error.message : String(error),
+                            pmidCount: needDoi.length,
+                        });
+                    }
+                }
+                const outcomes = await Promise.allSettled(fallbackCandidates.map((c) => resolveViaUnpaywall(c, ctx)));
+                for (const outcome of outcomes) {
+                    if (outcome.status === 'fulfilled') {
+                        if ('article' in outcome.value)
+                            fallbackArticles.push(outcome.value.article);
+                        else
+                            unavailable.push(outcome.value.unavailable);
+                    }
+                    else {
+                        ctx.log.warning('Unpaywall fallback crashed unexpectedly', {
+                            error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason),
+                        });
+                    }
+                }
+            }
         }
-        if (input.maxSections !== undefined)
-            articles = articles.map((a) => ({ ...a, sections: a.sections.slice(0, input.maxSections) }));
-        if (!input.includeReferences)
-            articles = articles.map(({ references: _, ...rest }) => rest);
-        const returnedPmcIds = new Set(articles.map((a) => a.pmcId));
-        const missingPmcIds = pmcIds
-            .map((id) => (id.startsWith('PMC') ? id : `PMC${id}`))
-            .filter((id) => !returnedPmcIds.has(id));
-        ctx.log.info('pubmed_pmc_fetch completed', {
-            requested: pmcIds.length,
+        const articles = [...pmcArticles, ...fallbackArticles];
+        ctx.log.info('pubmed_fetch_fulltext completed', {
+            requested: (input.pmids ?? input.pmcids)?.length ?? 0,
             returned: articles.length,
+            pmcHits: pmcArticles.length,
+            unpaywallHits: fallbackArticles.length,
+            unavailable: unavailable.length,
         });
         return {
             articles,
             totalReturned: articles.length,
-            ...(unavailablePmids && { unavailablePmids }),
-            ...(missingPmcIds.length > 0 && { unavailablePmcIds: missingPmcIds }),
+            ...(unavailable.length > 0 && { unavailable }),
+            ...(unavailablePmcIds && { unavailablePmcIds }),
         };
     },
     format: (result) => {
-        const lines = [`## PMC Full-Text Articles`, `**Articles Returned:** ${result.totalReturned}`];
-        if (result.unavailablePmids?.length)
-            lines.push(`**Unavailable PMIDs:** ${result.unavailablePmids.join(', ')}`);
-        if (result.unavailablePmcIds?.length)
+        const lines = [`## Full-Text Articles`, `**Articles Returned:** ${result.totalReturned}`];
+        if (result.unavailable?.length) {
+            lines.push(`\n**Unavailable PMIDs (${result.unavailable.length}):**`);
+            for (const u of result.unavailable) {
+                lines.push(`- ${u.pmid} — ${u.reason}${u.detail ? `: ${u.detail}` : ''}`);
+            }
+        }
+        if (result.unavailablePmcIds?.length) {
             lines.push(`**Unavailable PMC IDs:** ${result.unavailablePmcIds.join(', ')}`);
+        }
         for (const a of result.articles) {
-            lines.push(`\n### ${a.title ?? a.pmcId}`);
-            if (a.authors?.length) {
-                lines.push(`\n**Authors (${a.authors.length}):**`);
-                for (const au of a.authors) {
-                    lines.push(`- ${formatPmcAuthor(au)}`);
-                }
-            }
-            if (a.affiliations?.length) {
-                lines.push(`\n**Affiliations:**`);
-                for (const [i, aff] of a.affiliations.entries()) {
-                    lines.push(`${i + 1}. ${aff}`);
-                }
-            }
-            if (a.journal) {
-                const parts = [];
-                if (a.journal.title)
-                    parts.push(a.journal.title);
-                if (a.journal.volume)
-                    parts.push(`**${a.journal.volume}**${a.journal.issue ? `(${a.journal.issue})` : ''}`);
-                if (a.journal.pages)
-                    parts.push(a.journal.pages);
-                if (a.journal.issn)
-                    parts.push(`ISSN ${a.journal.issn}`);
-                if (parts.length)
-                    lines.push(`\n**Journal:** ${parts.join(', ')}`);
-            }
-            if (a.articleType)
-                lines.push(`**Type:** ${a.articleType}`);
-            if (a.publicationDate) {
-                const d = a.publicationDate;
-                const dateParts = [d.year, d.month, d.day].filter(Boolean);
-                if (dateParts.length)
-                    lines.push(`**Published:** ${dateParts.join('-')}`);
-            }
-            lines.push(`**PMCID:** ${a.pmcId}`);
-            if (a.pmid)
-                lines.push(`**PMID:** ${a.pmid}`);
-            if (a.doi)
-                lines.push(`**DOI:** ${a.doi}`);
-            lines.push(`**PMC:** ${a.pmcUrl}`);
-            if (a.pubmedUrl)
-                lines.push(`**PubMed:** ${a.pubmedUrl}`);
-            if (a.keywords?.length)
-                lines.push(`**Keywords:** ${a.keywords.join(', ')}`);
-            if (a.abstract)
-                lines.push(`\n#### Abstract\n${a.abstract}`);
-            for (const sec of a.sections) {
-                if (sec.title)
-                    lines.push(`\n#### ${formatHeading(sec.label, sec.title)}`);
-                if (sec.text)
-                    lines.push(sec.text);
-                if (sec.subsections?.length) {
-                    for (const sub of sec.subsections) {
-                        if (sub.title)
-                            lines.push(`\n##### ${formatHeading(sub.label, sub.title)}`);
-                        if (sub.text)
-                            lines.push(sub.text);
-                    }
-                }
-            }
-            if (a.references?.length) {
-                lines.push(`\n#### References (${a.references.length})`);
-                for (const ref of a.references) {
-                    const tag = [ref.label, ref.id].filter(Boolean).join(' ');
-                    lines.push(`- ${tag ? `[${tag}] ` : ''}${ref.citation}`);
-                }
-            }
+            lines.push('');
+            if (a.source === 'pmc')
+                formatPmcArticle(a, lines);
+            else
+                formatUnpaywallArticle(a, lines);
         }
         return [{ type: 'text', text: lines.join('\n') }];
     },
 });
+/**
+ * Batch-fetch DOIs from PubMed metadata for PMIDs that lack one after the PMC
+ * ID Converter roundtrip. The Converter only returns DOIs for articles already
+ * in PMC, so non-PMC PMIDs arrive here with `doi: undefined` — yet the DOI is
+ * present in PubMed's own record (ELocationID / ArticleIdList) and is required
+ * to query Unpaywall. One eFetch call covers the whole batch.
+ */
+async function fetchPubmedDois(pmids, signal) {
+    const out = new Map();
+    if (pmids.length === 0)
+        return out;
+    const xmlData = await getNcbiService().eFetch({ db: 'pubmed', id: pmids.join(','), retmode: 'xml' }, { retmode: 'xml', usePost: pmids.length >= 100, ...(signal && { signal }) });
+    const articles = xmlData?.PubmedArticleSet?.PubmedArticle
+        ? ensureArray(xmlData.PubmedArticleSet.PubmedArticle)
+        : [];
+    for (const article of articles) {
+        if (!article?.MedlineCitation)
+            continue;
+        const pmid = extractPmid(article.MedlineCitation);
+        if (!pmid)
+            continue;
+        const doi = extractDoi(article.MedlineCitation.Article, article.PubmedData?.ArticleIdList);
+        if (doi)
+            out.set(pmid, doi);
+    }
+    return out;
+}
+async function resolveViaUnpaywall(candidate, ctx) {
+    const { pmid, doi } = candidate;
+    const service = getUnpaywallService();
+    if (!doi)
+        return { unavailable: { pmid, reason: 'no-doi' } };
+    if (!service)
+        return { unavailable: { pmid, reason: 'no-pmc-fallback-disabled' } };
+    let resolution;
+    try {
+        resolution = await service.resolve(doi, ctx.signal);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { unavailable: { pmid, reason: 'service-error', detail } };
+    }
+    if (resolution.kind === 'no-oa') {
+        return { unavailable: { pmid, reason: 'no-oa', detail: resolution.reason } };
+    }
+    let content;
+    try {
+        content = await service.fetchContent(resolution.location, ctx.signal);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { unavailable: { pmid, reason: 'fetch-failed', detail } };
+    }
+    try {
+        if (content.kind === 'html') {
+            const extracted = await htmlExtractor.extract(content.body, {
+                url: content.fetchedUrl,
+                format: 'markdown',
+            });
+            const body = extracted.content.trim();
+            if (!body) {
+                return {
+                    unavailable: {
+                        pmid,
+                        reason: 'parse-failed',
+                        detail: 'HTML extraction produced empty content',
+                    },
+                };
+            }
+            return {
+                article: buildUnpaywallArticle({
+                    pmid,
+                    doi,
+                    sourceUrl: content.fetchedUrl,
+                    location: resolution.location,
+                    contentFormat: 'html-markdown',
+                    content: body,
+                    title: extracted.title,
+                    wordCount: extracted.wordCount,
+                }),
+            };
+        }
+        const extracted = await pdfParser.extractText(content.body, { mergePages: true });
+        const text = typeof extracted.text === 'string' ? extracted.text.trim() : '';
+        if (!text) {
+            return {
+                unavailable: {
+                    pmid,
+                    reason: 'parse-failed',
+                    detail: 'PDF extraction produced empty text',
+                },
+            };
+        }
+        return {
+            article: buildUnpaywallArticle({
+                pmid,
+                doi,
+                sourceUrl: content.fetchedUrl,
+                location: resolution.location,
+                contentFormat: 'pdf-text',
+                content: text,
+                totalPages: extracted.totalPages,
+            }),
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        ctx.log.warning('Unpaywall content extraction failed', { pmid, doi, detail });
+        return { unavailable: { pmid, reason: 'parse-failed', detail } };
+    }
+}
+function buildUnpaywallArticle(args) {
+    const { location } = args;
+    return {
+        source: 'unpaywall',
+        contentFormat: args.contentFormat,
+        pmid: args.pmid,
+        pubmedUrl: `https://pubmed.ncbi.nlm.nih.gov/${args.pmid}/`,
+        doi: args.doi,
+        sourceUrl: args.sourceUrl,
+        content: args.content,
+        ...(args.title && { title: args.title }),
+        ...(args.wordCount !== undefined && { wordCount: args.wordCount }),
+        ...(args.totalPages !== undefined && { totalPages: args.totalPages }),
+        ...(location.license && { license: location.license }),
+        ...(location.host_type && { hostType: location.host_type }),
+        ...(location.version && { version: location.version }),
+    };
+}
+// ─── format() helpers ────────────────────────────────────────────────────────
+function formatPmcArticle(a, lines) {
+    lines.push(`### ${a.title ?? a.pmcId}`);
+    lines.push(`**Source:** PMC (structured JATS)`);
+    if (a.authors?.length) {
+        lines.push(`\n**Authors (${a.authors.length}):**`);
+        for (const au of a.authors)
+            lines.push(`- ${formatPmcAuthor(au)}`);
+    }
+    if (a.affiliations?.length) {
+        lines.push(`\n**Affiliations:**`);
+        for (const [i, aff] of a.affiliations.entries())
+            lines.push(`${i + 1}. ${aff}`);
+    }
+    if (a.journal) {
+        const parts = [];
+        if (a.journal.title)
+            parts.push(a.journal.title);
+        if (a.journal.volume)
+            parts.push(`**${a.journal.volume}**${a.journal.issue ? `(${a.journal.issue})` : ''}`);
+        if (a.journal.pages)
+            parts.push(a.journal.pages);
+        if (a.journal.issn)
+            parts.push(`ISSN ${a.journal.issn}`);
+        if (parts.length)
+            lines.push(`\n**Journal:** ${parts.join(', ')}`);
+    }
+    if (a.articleType)
+        lines.push(`**Type:** ${a.articleType}`);
+    if (a.publicationDate) {
+        const d = a.publicationDate;
+        const dateParts = [d.year, d.month, d.day].filter(Boolean);
+        if (dateParts.length)
+            lines.push(`**Published:** ${dateParts.join('-')}`);
+    }
+    lines.push(`**PMCID:** ${a.pmcId}`);
+    if (a.pmid)
+        lines.push(`**PMID:** ${a.pmid}`);
+    if (a.doi)
+        lines.push(`**DOI:** ${a.doi}`);
+    lines.push(`**PMC:** ${a.pmcUrl}`);
+    if (a.pubmedUrl)
+        lines.push(`**PubMed:** ${a.pubmedUrl}`);
+    if (a.keywords?.length)
+        lines.push(`**Keywords:** ${a.keywords.join(', ')}`);
+    if (a.abstract)
+        lines.push(`\n#### Abstract\n${a.abstract}`);
+    for (const sec of a.sections) {
+        if (sec.title)
+            lines.push(`\n#### ${formatHeading(sec.label, sec.title)}`);
+        if (sec.text)
+            lines.push(sec.text);
+        if (sec.subsections?.length) {
+            for (const sub of sec.subsections) {
+                if (sub.title)
+                    lines.push(`\n##### ${formatHeading(sub.label, sub.title)}`);
+                if (sub.text)
+                    lines.push(sub.text);
+            }
+        }
+    }
+    if (a.references?.length) {
+        lines.push(`\n#### References (${a.references.length})`);
+        for (const ref of a.references) {
+            const tag = [ref.label, ref.id].filter(Boolean).join(' ');
+            lines.push(`- ${tag ? `[${tag}] ` : ''}${ref.citation}`);
+        }
+    }
+}
+function formatUnpaywallArticle(a, lines) {
+    const heading = a.title ?? `PMID ${a.pmid}`;
+    const formatLabel = a.contentFormat === 'html-markdown'
+        ? 'Unpaywall (HTML → Markdown, best-effort)'
+        : 'Unpaywall (PDF → plain text)';
+    lines.push(`### ${heading}`);
+    lines.push(`**Source:** ${formatLabel}`);
+    lines.push(`**PMID:** ${a.pmid}`);
+    lines.push(`**DOI:** ${a.doi}`);
+    lines.push(`**PubMed:** ${a.pubmedUrl}`);
+    lines.push(`**OA Copy:** ${a.sourceUrl}`);
+    if (a.license)
+        lines.push(`**License:** ${a.license}`);
+    if (a.hostType)
+        lines.push(`**Host Type:** ${a.hostType}`);
+    if (a.version)
+        lines.push(`**Version:** ${a.version}`);
+    if (a.wordCount !== undefined)
+        lines.push(`**Word Count:** ${a.wordCount}`);
+    if (a.totalPages !== undefined)
+        lines.push(`**Pages:** ${a.totalPages}`);
+    lines.push(`\n> Section structure is not guaranteed for this source. Treat the content as best-effort raw text. OA location metadata courtesy of Unpaywall (https://unpaywall.org).`);
+    lines.push(`\n#### Full Text\n${a.content}`);
+}
 function formatPmcAuthor(au) {
     const parts = [];
     if (au.collectiveName)