search_papers

Instructions

Implementation Reference

• src/nasa_ads_mcp/server.py:317-366 (handler)

  The handler function that executes the search_papers tool. It queries the NASA ADS using the ads library, formats the results with titles, authors, years, citations, and bibcodes, and returns them as TextContent.

  async def search_papers(query: str, max_results: int, sort: str) -> list[TextContent]:
      """Search ADS for papers."""
      try:
          # Prepare sort parameter for ADS
          sort_map = {
              "date": "date desc",
              "citation_count": "citation_count desc",
              "relevance": "score desc",
          }
          
          # Perform search
          papers = ads.SearchQuery(
              q=query,
              fl=["bibcode", "title", "author", "year", "citation_count", "pubdate"],
              rows=min(max_results, 50),
              sort=sort_map.get(sort, "date desc"),
          )
          
          # Format results
          results = []
          for i, paper in enumerate(papers, 1):
              authors = paper.author[:3] if paper.author else ["Unknown"]
              author_str = ", ".join(authors)
              if paper.author and len(paper.author) > 3:
                  author_str += f" et al. ({len(paper.author)} authors)"
              
              results.append(
                  f"{i}. {paper.title[0] if paper.title else 'No title'}\n"
                  f"   Authors: {author_str}\n"
                  f"   Year: {paper.year}\n"
                  f"   Citations: {paper.citation_count or 0}\n"
                  f"   Bibcode: {paper.bibcode}\n"
              )
          
          if not results:
              return [TextContent(
                  type="text",
                  text=f"No papers found for query: {query}"
              )]
          
          response = f"Found {len(results)} papers for '{query}':\n\n" + "\n".join(results)
          return [TextContent(type="text", text=response)]
      
      except Exception as e:
          logger.error(f"Error searching papers: {e}")
          return [TextContent(
              type="text",
              text=f"Error searching papers: {str(e)}"
          )]

• src/nasa_ads_mcp/server.py:56-76 (schema)

  Pydantic-like input schema defining parameters for the search_papers tool: query (required string), max_results (int, default 10), sort (enum: date, citation_count, relevance, default date).

  inputSchema={
      "type": "object",
      "properties": {
          "query": {
              "type": "string",
              "description": "Search query (e.g., 'stellar populations in elliptical galaxies')",
          },
          "max_results": {
              "type": "integer",
              "description": "Maximum number of results to return (default: 10, max: 50)",
              "default": 10,
          },
          "sort": {
              "type": "string",
              "description": "Sort order: 'date' (newest first), 'citation_count' (most cited), or 'relevance'",
              "enum": ["date", "citation_count", "relevance"],
              "default": "date",
          },
      },
      "required": ["query"],
  },

• src/nasa_ads_mcp/server.py:48-77 (registration)

  Registers the search_papers tool in the MCP server's list_tools() function, providing name, description, and input schema.

  Tool(
      name="search_papers",
      description=(
          "Search NASA ADS for astronomy/astrophysics papers. "
          "Returns bibcodes, titles, authors, years, and citation counts. "
          "Use natural language queries or specific field searches. "
          "Examples: 'stellar populations', 'author:Coelho', 'year:2020-2024'"
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Search query (e.g., 'stellar populations in elliptical galaxies')",
              },
              "max_results": {
                  "type": "integer",
                  "description": "Maximum number of results to return (default: 10, max: 50)",
                  "default": 10,
              },
              "sort": {
                  "type": "string",
                  "description": "Sort order: 'date' (newest first), 'citation_count' (most cited), or 'relevance'",
                  "enum": ["date", "citation_count", "relevance"],
                  "default": "date",
              },
          },
          "required": ["query"],
      },
  ),

• src/nasa_ads_mcp/server.py:265-270 (handler)

  Tool dispatching logic in the call_tool handler that routes search_papers calls to the implementation function with parsed arguments.

  if name == "search_papers":
      return await search_papers(
          query=arguments["query"],
          max_results=arguments.get("max_results", 10),
          sort=arguments.get("sort", "date"),
      )