arXiv MCP Server

Instructions

Implementation Reference

• src/arxiv_server/server.py:175-214 (handler)

  The primary handler for the download_article tool. Resolves the article by title or arXiv ID, downloads the PDF with retries using httpx, saves to local file, returns success JSON with path or error.

  @mcp.tool()
  async def download_article(
      title: Optional[str] = None,
      arxiv_id: Optional[str] = None,
  ) -> str:
      """
      Download the article as a PDF file. Resolve by arXiv ID or title.
  
      Args:
          title: Article title.
          arxiv_id: arXiv ID.
  
      Returns:
          Success message or structured error JSON.
      """
      result = await resolve_article(title=title, arxiv_id=arxiv_id)
      if isinstance(result, str):
          return result
      article_url, resolved_id = result
      headers = {"User-Agent": USER_AGENT, "Accept": "application/pdf"}
      file_path = os.path.join(DOWNLOAD_PATH, f"{resolved_id}.pdf")
      async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT, limits=HTTP_LIMITS) as client:
          for attempt in range(RETRY_ATTEMPTS):
              try:
                  async with client.stream("GET", article_url, headers=headers) as resp:
                      resp.raise_for_status()
                      with open(file_path, "wb") as f:
                          async for chunk in resp.aiter_bytes():
                              if chunk:
                                  f.write(chunk)
                  return json.dumps({
                      "status": "ok",
                      "message": "Download successful.",
                      "path": file_path,
                  })
              except Exception as e:
                  if attempt < RETRY_ATTEMPTS - 1:
                      await _retry_sleep(attempt)
                      continue
                  return _error("DOWNLOAD_FAILED", f"Unable to retrieve or save the article: {e}")

• src/arxiv_server/server.py:123-142 (helper)

  Helper function to resolve article title or arXiv ID to PDF URL and ID. Used by download_article and other tools.

  async def resolve_article(title: Optional[str] = None, arxiv_id: Optional[str] = None) -> Tuple[str, str] | str:
      """
      Resolve to a direct PDF URL and arXiv ID using either a title or an arXiv ID.
      Preference order: arxiv_id > title.
      """
      if arxiv_id:
          m = ARXIV_ID_RE.match(arxiv_id.strip())
          if not m:
              return _error("INVALID_ID", f"Not a valid arXiv ID: {arxiv_id}")
          vid = m.group("id")
          return (f"https://arxiv.org/pdf/{vid}", vid)
      if not title:
          return _error("MISSING_PARAM", "Provide either 'arxiv_id' or 'title'.")
      info = await fetch_information(title)
      if isinstance(info, str):
          return _error("NOT_FOUND", str(info))
      resolved_id = info.id.split("/abs/")[-1]
      direct_pdf_url = f"https://arxiv.org/pdf/{resolved_id}"
      return (direct_pdf_url, resolved_id)