ScholarScope MCP

Instructions

Implementation Reference

• src/server.py:112-178 (handler)

  The main handler function for the 'search_authors' tool. It constructs a query to the OpenAlex API /authors endpoint, processes the results into Author objects wrapped in a PageResult, handles pagination, sorting, filtering by institution, and raises appropriate errors.

  @mcp.tool
  async def search_authors(
          query: str,
          sort_by: Literal["relevance_score", "cited_by_count"] = "relevance_score",
          institution_id: Optional[str] = None,
          page: int = 1,
  ) -> PageResult:
      """
      Searches for authors using the OpenAlex API.
  
      Args:
          query: The search name to look for the authors.
          sort_by: The sorting criteria ("relevance_score" or "cited_by_count").
          institution_id: An optional institution id to filter search results. e.g., "https://openalex.org/I123456789"
          page: The page number of the results to retrieve (default: 1).
  
      Returns:
          A JSON object containing a list of authors+ids, or an error message if the search fails.
      """
      query = sanitize_search_text(query)
  
      params = {
          "filter": f"default.search:\"{query}\"",
          "sort": f"{sort_by}:desc",
          "page": page,
          "per_page": 10,
      }
      if institution_id:
          params["filter"] += f",affiliations.institution.id:\"{institution_id}\""
  
      # Fetches search results from the OpenAlex API
      async with RequestAPI("https://api.openalex.org", default_params={"mailto": OPENALEX_MAILTO}) as api:
          logger.info(f"Searching for authors using: query={query}, sort_by={sort_by}, page={page}, institution_id={institution_id}")
          try:
              result = await api.aget("/authors", params=params)
  
              # Returns a message for when the search results are empty
              if result is None or len(result.get("results", []) or []) == 0:
                  error_message = "No authors found with the query."
                  logger.info(error_message)
                  raise ToolError(error_message)
  
              # Successfully returns the searched authors
              authors = Author.from_list(result.get("results", []) or [])
              success_message = f"Found {len(authors)} authors."
              logger.info(success_message)
  
              total_count = (result.get("meta", {}) or {}).get("count")
              if total_count and total_count > params["per_page"] * params["page"]:
                  has_next = True
              else:
                  has_next = None
              return PageResult(
                  data=Author.list_to_json(authors),
                  total_count=total_count,
                  per_page=params["per_page"],
                  page=params["page"],
                  has_next=has_next
              )
          except httpx.HTTPStatusError as e:
              error_message = f"Request failed with status: {e.response.status_code}"
              logger.error(error_message)
              raise ToolError(error_message)
          except httpx.RequestError as e:
              error_message = f"Network error: {str(e)}"
              logger.error(error_message)
              raise ToolError(error_message)