Claude Telemetry MCP

Instructions

Implementation Reference

• src/index.ts:357-374 (handler)

  The main execution handler for the 'compare_usage_periods' tool. It extracts period parameters from input arguments, fetches usage trends for both periods using TelemetryService, and returns a formatted comparison text response.

  case 'compare_usage_periods': {
    const period1Days = typeof args?.period1_days === 'number' ? args.period1_days : 7;
    const period2Days = typeof args?.period2_days === 'number' ? args.period2_days : 14;
    
    const [trends1, trends2] = await Promise.all([
      this.telemetryService.getUsageTrends(period1Days),
      this.telemetryService.getUsageTrends(period2Days)
    ]);
  
    return {
      content: [
        {
          type: 'text',
          text: this.formatPeriodComparison(trends1, trends2, period1Days, period2Days),
        },
      ],
    };
  }

• src/index.ts:166-180 (schema)

  Input schema definition for the 'compare_usage_periods' tool, specifying optional parameters for the two comparison periods with defaults.

  inputSchema: {
    type: 'object',
    properties: {
      period1_days: {
        type: 'number',
        description: 'Days back for first period (default: 7)',
        default: 7,
      },
      period2_days: {
        type: 'number',
        description: 'Days back for second period (default: 14)',
        default: 14,
      },
    },
  },

• src/index.ts:163-181 (registration)

  Tool registration entry in the ListTools response, including name, description, and input schema.

  {
    name: 'compare_usage_periods',
    description: 'Compare usage between different time periods',
    inputSchema: {
      type: 'object',
      properties: {
        period1_days: {
          type: 'number',
          description: 'Days back for first period (default: 7)',
          default: 7,
        },
        period2_days: {
          type: 'number',
          description: 'Days back for second period (default: 14)',
          default: 14,
        },
      },
    },
  },

• src/index.ts:492-503 (helper)

  Helper method to format the comparison results between two usage periods, calculating totals, change, and percentage difference.

  private formatPeriodComparison(trends1: UsageTrend[], trends2: UsageTrend[], period1: number, period2: number): string {
    const total1 = trends1.reduce((sum, t) => sum + t.tokens, 0);
    const total2 = trends2.reduce((sum, t) => sum + t.tokens, 0);
    
    const change = total1 - total2;
    const changePercent = total2 > 0 ? ((change / total2) * 100) : 0;
  
    return `## Usage Comparison\n\n` +
      `**Last ${period1} days**: ${total1.toLocaleString()} tokens\n` +
      `**Previous ${period2} days**: ${total2.toLocaleString()} tokens\n` +
      `**Change**: ${change > 0 ? '+' : ''}${change.toLocaleString()} tokens (${changePercent > 0 ? '+' : ''}${changePercent.toFixed(1)}%)`;
  }

• src/telemetry-service.ts:103-129 (helper)

  Supporting method in TelemetryService that queries Prometheus for usage trends over a specified number of days, used by the tool handler for both periods.

  async getUsageTrends(daysBack: number = 7): Promise<UsageTrend[]> {
    const endTime = new Date();
    const startTime = new Date(endTime.getTime() - (daysBack * 24 * 60 * 60 * 1000));
  
    const [tokensResult, costResult, sessionsResult] = await Promise.all([
      this.prometheus.queryRange('claude_code_token_usage_tokens_total', startTime, endTime, '1h'),
      this.prometheus.queryRange('claude_code_cost_usage_USD_total', startTime, endTime, '1h'),
      this.prometheus.queryRange('claude_code_session_count_total', startTime, endTime, '1h')
    ]);
  
    const tokensSeries = this.prometheus.getTimeSeries(tokensResult);
    const costSeries = this.prometheus.getTimeSeries(costResult);
    const sessionsSeries = this.prometheus.getTimeSeries(sessionsResult);
  
    // Combine the series data
    const trends: UsageTrend[] = [];
    for (let i = 0; i < tokensSeries.length; i++) {
      trends.push({
        timestamp: tokensSeries[i].timestamp.toISOString(),
        tokens: tokensSeries[i].value,
        cost: costSeries[i]?.value || 0,
        sessions: sessionsSeries[i]?.value || 0
      });
    }
  
    return trends;
  }