Claude Telemetry MCP

Instructions

Implementation Reference

• src/index.ts:268-285 (handler)

  The MCP tool handler for 'get_usage_warnings'. Uses default token limits, calls checkUsageLimits on TelemetryService, and formats warnings for response.

  case 'get_usage_warnings': {
    // Use default thresholds
    const defaultLimits: UsageLimits = {
      dailyTokenLimit: 100000, // Example default
      weeklyTokenLimit: 500000, // Example default
      sessionTokenLimit: 50000, // Example default
    };
  
    const warnings = await this.telemetryService.checkUsageLimits(defaultLimits);
    return {
      content: [
        {
          type: 'text',
          text: this.formatUsageWarnings(warnings, true),
        },
      ],
    };
  }

• src/index.ts:105-112 (registration)

  Tool registration in ListTools response, specifying name, description, and empty input schema.

  {
    name: 'get_usage_warnings',
    description: 'Get usage warnings with default thresholds (80% and 90% of typical limits)',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/telemetry-service.ts:177-232 (helper)

  Core helper function that computes usage warnings by comparing current metrics against provided limits at 80% and 90% thresholds.

  async checkUsageLimits(limits: UsageLimits): Promise<UsageWarnings> {
    const summary = await this.getUsageSummary();
    const warnings: string[] = [];
    const percentages: any = {};
  
    // Check daily limits
    if (limits.dailyTokenLimit) {
      const dailyPercent = (summary.today.tokens / limits.dailyTokenLimit) * 100;
      percentages.dailyTokens = dailyPercent;
      if (dailyPercent > 90) {
        warnings.push(`Daily token usage at ${dailyPercent.toFixed(1)}% of limit`);
      } else if (dailyPercent > 80) {
        warnings.push(`Daily token usage approaching limit (${dailyPercent.toFixed(1)}%)`);
      }
    }
  
    // Check weekly limits
    if (limits.weeklyTokenLimit) {
      const weeklyPercent = (summary.thisWeek.tokens / limits.weeklyTokenLimit) * 100;
      percentages.weeklyTokens = weeklyPercent;
      if (weeklyPercent > 90) {
        warnings.push(`Weekly token usage at ${weeklyPercent.toFixed(1)}% of limit`);
      } else if (weeklyPercent > 80) {
        warnings.push(`Weekly token usage approaching limit (${weeklyPercent.toFixed(1)}%)`);
      }
    }
  
    // Check session limits
    if (limits.sessionTokenLimit) {
      const sessionPercent = (summary.currentSession.tokens / limits.sessionTokenLimit) * 100;
      percentages.sessionTokens = sessionPercent;
      if (sessionPercent > 90) {
        warnings.push(`Session token usage at ${sessionPercent.toFixed(1)}% of limit`);
      } else if (sessionPercent > 80) {
        warnings.push(`Session token usage approaching limit (${sessionPercent.toFixed(1)}%)`);
      }
    }
  
    // Similar checks for cost limits...
    if (limits.dailyCostLimit) {
      const dailyCostPercent = (summary.today.cost / limits.dailyCostLimit) * 100;
      percentages.dailyCost = dailyCostPercent;
      if (dailyCostPercent > 80) {
        warnings.push(`Daily cost approaching limit (${dailyCostPercent.toFixed(1)}%)`);
      }
    }
  
    return {
      warnings,
      usage: {
        current: summary.today,
        limits,
        percentages
      }
    };
  }

• src/index.ts:428-451 (helper)

  Helper method to format UsageWarnings into a user-friendly markdown response.

  private formatUsageWarnings(warnings: UsageWarnings, isDefault: boolean = false): string {
    let result = '## Usage Warnings\n\n';
    
    if (warnings.warnings.length === 0) {
      result += '✅ No usage warnings - you\'re within safe limits\n\n';
    } else {
      result += '⚠️ **Warnings**:\n';
      warnings.warnings.forEach((warning: string) => {
        result += `- ${warning}\n`;
      });
      result += '\n';
    }
  
    if (isDefault) {
      result += '_Note: Using default limit thresholds. Use check_usage_limits with custom limits for precise tracking._\n\n';
    }
  
    result += '**Current Usage**:\n';
    result += `- Tokens: ${warnings.usage.current.tokens.toLocaleString()}\n`;
    result += `- Cost: $${warnings.usage.current.cost.toFixed(4)}\n`;
    result += `- Sessions: ${warnings.usage.current.sessions}\n`;
  
    return result;
  }

• src/types.ts:75-98 (schema)

  TypeScript interfaces defining UsageLimits (input-like for limits) and UsageWarnings (output structure) used by the tool.

  export interface UsageLimits {
    dailyTokenLimit?: number;
    weeklyTokenLimit?: number;
    sessionTokenLimit?: number;
    dailyCostLimit?: number;
    weeklyCostLimit?: number;
    sessionCostLimit?: number;
  }
  
  export interface UsageWarnings {
    warnings: string[];
    usage: {
      current: UsageData;
      limits: UsageLimits;
      percentages: {
        dailyTokens?: number;
        weeklyTokens?: number;
        sessionTokens?: number;
        dailyCost?: number;
        weeklyCost?: number;
        sessionCost?: number;
      };
    };
  }