get_citation_stats

Instructions

Implementation Reference

• src/tools/citations/index.js:240-272 (handler)

  The main handler function for the 'get_citation_stats' tool. It extracts the paperId from args, calls the API endpoint /citations/{paperId}/stats, and formats the response with detailed citation statistics including counts, impact metrics, temporal analysis, and field comparison.

  async getCitationStats(args) {
    const { paperId } = args;
    
    try {
      const response = await this.baseUtils.makeApiRequest(`/citations/${paperId}/stats`, 'GET', null, false);
      const stats = response.data;
      
      return this.baseUtils.formatResponse(
        `📊 **Citation Statistics for Paper ${paperId}**\n\n` +
        `**Citation Counts:**\n` +
        `• Total Citations: ${stats.totalCitations || 0}\n` +
        `• Direct Citations: ${stats.directCitations || 0}\n` +
        `• Self Citations: ${stats.selfCitations || 0}\n` +
        `• References Made: ${stats.referencesCount || 0}\n\n` +
        `**Impact Metrics:**\n` +
        `• H-Index Contribution: ${stats.hIndexContribution || 0}\n` +
        `• Citation Velocity: ${stats.citationVelocity || 0} citations/month\n` +
        `• Peak Citation Year: ${stats.peakYear || 'N/A'}\n\n` +
        `**Temporal Analysis:**\n` +
        `• First Citation: ${stats.firstCitation ? new Date(stats.firstCitation).toLocaleDateString() : 'None'}\n` +
        `• Latest Citation: ${stats.latestCitation ? new Date(stats.latestCitation).toLocaleDateString() : 'None'}\n` +
        `• Citation Half-Life: ${stats.halfLife || 'N/A'} months\n\n` +
        `**Comparison:**\n` +
        `• Percentile in Field: ${stats.fieldPercentile || 'N/A'}%\n` +
        `• Above Average: ${stats.aboveAverage ? 'Yes' : 'No'}`
      );
    } catch (error) {
      if (error.response?.status === 404) {
        throw new McpError(ErrorCode.InvalidRequest, `Paper ${paperId} not found`);
      }
      throw new McpError(ErrorCode.InternalError, `Failed to get citation stats: ${error.message}`);
    }
  }

• src/tools/citations/index.js:79-89 (schema)

  The input schema definition for the 'get_citation_stats' tool, registered in getToolDefinitions(). Defines a single required parameter 'paperId' (string) for identifying the paper to get stats for.

  {
    name: "get_citation_stats",
    description: "Get detailed citation statistics for a paper",
    inputSchema: {
      type: "object",
      properties: {
        paperId: { type: "string", description: "ID of paper to get citation stats for" }
      },
      required: ["paperId"]
    }
  }

• src/tools/citations/index.js:94-101 (registration)

  Registration of the 'get_citation_stats' tool handler in getToolHandlers(), mapping the tool name to the getCitationStats method bound to the instance.

  getToolHandlers() {
    return {
      "get_citations": this.getCitations.bind(this),
      "get_citing_papers": this.getCitingPapers.bind(this),
      "get_paper_references": this.getPaperReferences.bind(this),
      "get_citation_graph": this.getCitationGraph.bind(this),
      "get_citation_stats": this.getCitationStats.bind(this)
    };