ScholarScope MCP

Instructions

Implementation Reference

• src/server.py:351-390 (handler)

  The handler function for the 'related_works_of_paper' tool. It is decorated with @mcp.tool, which registers it in the FastMCP server. The function retrieves the 'related_works' array from the OpenAlex API for the specified paper_id and returns it wrapped in a ListResult object.

  @mcp.tool
  async def related_works_of_paper(
          paper_id: str,
  ) -> ListResult:
      """
      Gets related works used to the specified paper using the OpenAlex API.
      Note: May return empty if the paper's full text is inaccessible.
  
      Args:
          paper_id: An OpenAlex Work ID of the target paper. e.g., "https://openalex.org/W123456789"
  
      Returns:
          A JSON object containing a list of paper ids related to the work, or an error message if the fetch fails.
      """
  
      # Fetches search results from the OpenAlex API
      async with RequestAPI("https://api.openalex.org", default_params={"mailto": OPENALEX_MAILTO}) as api:
          logger.info(f"Fetching related_works works for paper_id={paper_id}")
          try:
              result = await api.aget(f"/works/{paper_id}")
  
              # Returns a message for when the search results are empty
              if result is None or len(result.get("related_works", []) or []) == 0:
                  error_message = f"No related_works works found for paper_id={paper_id}."
                  logger.info(error_message)
                  raise ToolError(error_message)
  
              # Successfully returns the searched papers
              works = result.get("related_works", []) or []
              success_message = f"Retrieved {len(works)} related_works works for paper_id={paper_id}."
              logger.info(success_message)
              return ListResult(data=works, count=len(works))
          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)