search_arxiv

Instructions

Implementation Reference

• src/arxiv_server/server.py:345-412 (handler)

  The core handler for the 'search_arxiv' tool. Decorated with @mcp.tool() for registration in FastMCP. Handles search queries across arXiv fields, calls API, parses results, and returns title-mapped metadata.

  @mcp.tool()
  async def search_arxiv(
      ctx: Context,
      all_fields: Optional[str] = None,
      title: Optional[str] = None,
      author: Optional[str] = None,
      abstract: Optional[str] = None,
      start: int = 0,
      max_results: int = 10,
  ) -> Any:
      """
      Performs a search query on the arXiv API based on specified parameters and returns matching article metadata.
      This function allows for flexible querying of the arXiv database. Only parameters that are explicitly provided
      will be included in the final search query. Results are returned in a JSON-formatted string with article titles
      as keys and their corresponding arXiv IDs as values.
  
      Args:
          all_fields: General keyword search across all metadata fields including title, abstract, authors, comments, and categories.
          title: Keyword(s) to search for within the titles of articles.
          author: Author name(s) to filter results by.
          abstract: Keyword(s) to search for within article abstracts.
          start: Index of the first result to return; used for paginating through search results. Defaults to 0.
          max_results: Maximum number of results to return (1-50).
  
      Returns:
          A JSON-formatted string containing article titles and their associated arXiv IDs;
          otherwise, a structured error JSON string.
      """
      prefixed_params = []
      if author:
          author = format_text(author)
          prefixed_params.append(f"au:{author}")
      if all_fields:
          all_fields = format_text(all_fields)
          prefixed_params.append(f"all:{all_fields}")
      if title:
          title = format_text(title)
          prefixed_params.append(f"ti:{title}")
      if abstract:
          abstract = format_text(abstract)
          prefixed_params.append(f"abs:{abstract}")
      # Construct search query
      search_query = " AND ".join(prefixed_params)
      params = {
          "search_query": search_query,
          "start": start,
          "max_results": max(1, min(max_results, 50)),
      }
      await ctx.info("Calling the API")
      response = await make_api_call(f"{ARXIV_API_BASE}/query", params=params)
      if response is None:
          return _error("API_ERROR", "Unable to retrieve data from arXiv.org.")
      feed = feedparser.parse(response)
      error_msg = (
          "Unable to extract information for your query. "
          "This issue may stem from an incorrect search query."
      )
      if not feed.entries:
          return _error("NOT_FOUND", error_msg)
      entries: Dict[str, Dict[str, Any]] = {}
      await ctx.info("Extracting information")
      for entry in feed.entries:
          id = entry.id
          article_title = entry.title
          arxiv_id = id.split("/abs/")[-1]
          authors = [author['name'] for author in entry.authors]
          entries[article_title] = {"arXiv ID": arxiv_id, "Authors": authors}
      return entries

• src/arxiv_server/server.py:53-67 (helper)

  Helper function used by search_arxiv to make HTTP requests to arXiv API with retry logic.

  async def make_api_call(url: str, params: Dict[str, str]) -> Optional[str]:
      """Make a request to the arXiv API with retries."""
      headers = {"User-Agent": USER_AGENT, "Accept": "application/atom+xml"}
      async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT, limits=HTTP_LIMITS) as client:
          for attempt in range(RETRY_ATTEMPTS):
              try:
                  resp = await client.get(url, params=params, headers=headers)
                  resp.raise_for_status()
                  return resp.text
              except Exception:
                  if attempt < RETRY_ATTEMPTS - 1:
                      await _retry_sleep(attempt)
                      continue
                  return None

• src/arxiv_server/server.py:143-155 (helper)

  Utility function to format/clean search terms used in search_arxiv queries.

  def format_text(text: str) -> str:
      """Clean a given text string by removing escape sequences and leading and trailing whitespaces."""
      # Remove common escape sequences
      text_without_escapes = re.sub(r"\\[ntr]", " ", text)
      # Replace colon with space
      text_without_colon = text_without_escapes.replace(":", " ")
      # Remove both single quotes and double quotes
      text_without_quotes = re.sub(r"['\"]", "", text_without_colon)
      # Collapse multiple spaces into one
      text_single_spaced = re.sub(r"\s+", " ", text_without_quotes)
      # Trim leading and trailing spaces
      cleaned_text = text_single_spaced.strip()
      return cleaned_text