Unpaywall MCP Server

Instructions

Implementation Reference

• src/index.ts:275-319 (handler)

  Handler for TOOL_FETCH_PDF_TEXT: resolves PDF URL from DOI if provided, downloads the PDF buffer, extracts text using pdf-parse, applies truncation if specified, and returns structured JSON with text and metadata.
  if (tool === TOOL_FETCH_PDF_TEXT) { const args = (req.params.arguments ?? {}) as Partial<FetchPdfTextArgs>; const truncate = args.truncate_chars && Number.isFinite(args.truncate_chars) ? Math.max(1000, Math.floor(Number(args.truncate_chars))) : 20000; let pdfUrl = (args.pdf_url ?? "").toString().trim(); if (!pdfUrl) { const rawDoi = (args.doi ?? "").toString().trim(); if (!rawDoi) { return { content: [{ type: "text", text: "Provide either 'pdf_url' or 'doi'" }], isError: true }; } const email = (args.email || process.env.UNPAYWALL_EMAIL || "").toString().trim(); if (!email) { return { content: [{ type: "text", text: "Unpaywall requires an email. Set UNPAYWALL_EMAIL or pass 'email'." }], isError: true }; } const doi = normalizeDoi(rawDoi); const obj = await fetchUnpaywallByDoi(doi, email); const best = obj?.best_oa_location ?? null; const locations: any[] = Array.isArray(obj?.oa_locations) ? obj.oa_locations : []; const pickPdfFrom = (locs: any[]) => locs.find(l => l?.url_for_pdf) || locs.find(l => l?.url); pdfUrl = best?.url_for_pdf || (pickPdfFrom(locations)?.url_for_pdf || pickPdfFrom(locations)?.url) || ""; if (!pdfUrl) { return { content: [{ type: "text", text: "No OA PDF URL found for the provided DOI." }], isError: true }; } } // Download and parse PDF const pdfBuffer = await downloadPdfAsBuffer(pdfUrl); const parsed = await pdfParse(pdfBuffer); const text = parsed.text || ""; const truncated = text.length > truncate; const output = { pdf_url: pdfUrl, length_chars: text.length, truncated, text: truncated ? text.slice(0, truncate) : text, metadata: { n_pages: parsed.numpages ?? undefined, info: parsed.info ?? undefined, metadata: parsed.metadata ?? undefined, }, }; return { content: [{ type: "json", json: output }] }; }
• src/index.ts:178-192 (registration)

  Tool registration in the ListTools response, including name, description, and input schema.
  { name: TOOL_FETCH_PDF_TEXT, description: "Download and extract text from best OA PDF for a DOI, or from a provided PDF URL.", inputSchema: { type: "object", properties: { doi: { type: "string", description: "DOI string or DOI URL. Used if pdf_url is not provided." }, pdf_url: { type: "string", description: "Direct PDF URL to download and parse (takes precedence over DOI)." }, email: { type: "string", description: "Email to identify requests to Unpaywall (required when resolving via DOI)." }, truncate_chars: { type: "integer", minimum: 1000, description: "Max characters of extracted text to return (default 20000)." }, }, required: [], additionalProperties: false, }, },
• src/index.ts:31-36 (schema)

  TypeScript type definition matching the tool's input schema for type safety in the handler.
  type FetchPdfTextArgs = { doi?: string; // if provided, we will resolve best OA PDF via Unpaywall pdf_url?: string; // optional direct PDF URL (takes precedence if provided) email?: string; // required if using DOI truncate_chars?: number; // optional truncation to avoid massive outputs (default 20000) };
• src/index.ts:63-96 (helper)

  Helper function to download PDF as buffer with timeout, size limit (30MB), and streaming to prevent memory issues.
  async function downloadPdfAsBuffer(url: string, maxBytes = 30 * 1024 * 1024) { // Limit to 30MB by default to avoid extremely large downloads const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30_000); try { const resp = await fetch(url, { signal: controller.signal, headers: { "Accept": "application/pdf, application/octet-stream;q=0.9,*/*;q=0.8", }, redirect: "follow", }); if (!resp.ok) { const text = await resp.text().catch(() => ""); throw new Error(`PDF download HTTP ${resp.status}: ${text.slice(0, 400)}`); } const reader = resp.body?.getReader(); if (!reader) return Buffer.from(await resp.arrayBuffer()); const chunks: Uint8Array[] = []; let received = 0; while (true) { const { done, value } = await reader.read(); if (done) break; if (value) { received += value.byteLength; if (received > maxBytes) throw new Error(`PDF exceeds size limit of ${maxBytes} bytes`); chunks.push(value); } } return Buffer.concat(chunks); } finally { clearTimeout(timeout); } }
• src/index.ts:47-61 (helper)

  Helper to fetch Unpaywall metadata by DOI, used to resolve best OA PDF URL when DOI is provided.
  async function fetchUnpaywallByDoi(doi: string, email: string) { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 20_000); try { const url = `https://api.unpaywall.org/v2/${encodeURIComponent(doi)}?email=${encodeURIComponent(email)}`; const resp = await fetch(url, { signal: controller.signal, headers: { "Accept": "application/json" } }); if (!resp.ok) { const text = await resp.text().catch(() => ""); throw new Error(`Unpaywall HTTP ${resp.status}: ${text.slice(0, 400)}`); } return await resp.json(); } finally { clearTimeout(timeout); } }