get_paper_metrics

Instructions

Implementation Reference

• src/nasa_ads_mcp/server.py:509-562 (handler)

  The handler function that executes the tool: makes API request to ADS /metrics endpoint with bibcodes, parses citation stats, reads, and indicators, formats into TextContent.

  async def get_paper_metrics(bibcodes: list[str]) -> list[TextContent]:
      """Get metrics for specific papers."""
      try:
          # Prepare request payload
          payload = {"bibcodes": bibcodes}
          
          # Make API request
          response = requests.post(
              f"{ADS_API_BASE}/metrics",
              headers=HEADERS,
              json=payload,
              timeout=30
          )
          response.raise_for_status()
          
          data = response.json()
          
          # Format response
          if "citation stats" in data:
              stats = data["citation stats"]
              metrics_lines = [
                  "Paper Metrics:",
                  f"Total Citations: {stats.get('total number of citations', 0)}",
                  f"Total Refereed Citations: {stats.get('total number of refereed citations', 0)}",
                  f"Average Citations per Paper: {stats.get('average number of citations', 0):.1f}",
                  f"Median Citations: {stats.get('median number of citations', 0)}",
                  f"Normalized Citations: {stats.get('normalized number of citations', 0):.1f}",
                  f"Total Reads: {stats.get('total number of reads', 0)}",
                  f"Average Reads per Paper: {stats.get('average number of reads', 0):.1f}",
              ]
              
              # Add indicator metrics if available
              if "indicators" in data:
                  indicators = data["indicators"]
                  metrics_lines.extend([
                      "",
                      "Indicators:",
                      f"h-index: {indicators.get('h', 0)}",
                      f"m-index: {indicators.get('m', 0):.2f}",
                      f"i10-index: {indicators.get('i10', 0)}",
                      f"g-index: {indicators.get('g', 0)}",
                  ])
              
              return [TextContent(type="text", text="\n".join(metrics_lines))]
          else:
              return [TextContent(type="text", text="No metrics available for these papers")]
      
      except requests.exceptions.RequestException as e:
          logger.error(f"Error getting paper metrics: {e}")
          return [TextContent(
              type="text",
              text=f"Error getting paper metrics: {str(e)}"
          )]

• src/nasa_ads_mcp/server.py:141-159 (registration)

  Registers the 'get_paper_metrics' tool with the MCP server in list_tools(), including description and input schema.

  Tool(
      name="get_paper_metrics",
      description=(
          "Get detailed metrics for specific papers including citation count, "
          "reference count, reads, and citation history. "
          "Useful for tracking paper impact over time."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "bibcodes": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of ADS bibcodes (e.g., ['2019ApJ...878...98S'])",
              },
          },
          "required": ["bibcodes"],
      },
  ),

• src/nasa_ads_mcp/server.py:148-158 (schema)

  Input schema definition for the tool, specifying bibcodes as required array of strings.

  inputSchema={
      "type": "object",
      "properties": {
          "bibcodes": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of ADS bibcodes (e.g., ['2019ApJ...878...98S'])",
          },
      },
      "required": ["bibcodes"],
  },