Scholar MCP

Instructions

Implementation Reference

• scholar_mcp/scholar_client.py:150-195 (handler)

  Core implementation of get_author_papers tool. Contains the ScholarClient method that queries Google Scholar for papers by author, parses results, and returns an AuthorPapersResponse with papers, author info, and pagination cursor.

  def get_author_papers(
      self,
      author_query: str,
      page_size: int,
      start: int,
  ) -> AuthorPapersResponse:
      author_query = author_query.strip()
      if not author_query:
          raise ScholarClientError(
              code="invalid_request",
              message="Author query cannot be empty.",
              retryable=False,
          )
  
      html = self._request(
          SEARCH_URL,
          params={
              "hl": "en",
              "q": author_query,
              "as_sauthors": author_query,
              "start": start,
          },
      )
  
      papers = [
          item
          for item in parse_topic_results(html=html, page_size=page_size + 3)
          if not item.title.lower().startswith("user profiles for")
      ][:page_size]
  
      if not papers:
          raise ScholarClientError(
              code="author_not_found",
              message=f"No papers found for author '{author_query}'.",
              retryable=False,
          )
  
      next_cursor = str(start + page_size) if len(papers) >= page_size else None
  
      return AuthorPapersResponse(
          author_name=author_query,
          author_id=None,
          affiliation=None,
          papers=papers,
          next_cursor=next_cursor,
      )

• scholar_mcp/server.py:85-121 (registration)

  Tool registration and MCP handler for get_author_papers. Decorated with @mcp.tool(), this function validates inputs, calls the ScholarClient, and formats the response using the ok() helper. Defines the tool interface with type hints (author, page_size, cursor).

  @mcp.tool()
  def get_author_papers(
      author: str,
      page_size: int = 10,
      cursor: str | None = None,
  ) -> dict[str, Any]:
      """Get papers filtered by author name from Google Scholar search."""
      author = author.strip()
      if not author:
          return fail("invalid_request", "author cannot be empty", retryable=False)
  
      try:
          start = _parse_cursor(cursor)
          size = _normalize_page_size(page_size)
      except ValueError as exc:
          return fail("invalid_request", str(exc), retryable=False)
  
      try:
          response = client.get_author_papers(author_query=author, page_size=size, start=start)
      except ScholarClientError as exc:
          return fail(exc.code, exc.message, retryable=exc.retryable, details=exc.details)
  
      return ok(
          {
              "author": {
                  "name": response.author_name,
                  "id": response.author_id,
                  "affiliation": response.affiliation,
              },
              "page_size": size,
              "cursor": str(start),
              "next_cursor": response.next_cursor,
              "source": "google_scholar",
              "results": [paper.to_dict() for paper in response.papers],
              "fetched_at": __import__("datetime").datetime.utcnow().isoformat() + "Z",
          }
      )

• scholar_mcp/scholar_client.py:18-24 (schema)

  Response schema definition for get_author_papers. Dataclass defining the structure of the author papers response including author metadata, paper list, and pagination cursor.

  @dataclass
  class AuthorPapersResponse:
      author_name: str
      author_id: str | None
      affiliation: str | None
      papers: list[PaperResult]
      next_cursor: str | None