Claude Telemetry MCP

Instructions

Implementation Reference

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

  Core handler function that implements the check_usage_limits tool logic by comparing current usage metrics against provided limits and generating appropriate warnings.

  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:72-104 (registration)

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

  {
    name: 'check_usage_limits',
    description: 'Check current usage against specified limits and get warnings',
    inputSchema: {
      type: 'object',
      properties: {
        daily_token_limit: {
          type: 'number',
          description: 'Daily token limit to check against',
        },
        weekly_token_limit: {
          type: 'number',
          description: 'Weekly token limit to check against',
        },
        session_token_limit: {
          type: 'number',
          description: 'Session token limit to check against',
        },
        daily_cost_limit: {
          type: 'number',
          description: 'Daily cost limit in USD to check against',
        },
        weekly_cost_limit: {
          type: 'number',
          description: 'Weekly cost limit in USD to check against',
        },
        session_cost_limit: {
          type: 'number',
          description: 'Session cost limit in USD to check against',
        },
      },
    },
  },

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

  TypeScript interface defining the input parameters (UsageLimits) for the checkUsageLimits function.

  export interface UsageLimits {
    dailyTokenLimit?: number;
    weeklyTokenLimit?: number;
    sessionTokenLimit?: number;
    dailyCostLimit?: number;
    weeklyCostLimit?: number;
    sessionCostLimit?: number;
  }

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

  TypeScript interface defining the output structure (UsageWarnings) returned by the handler.

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

• src/index.ts:247-266 (handler)

  MCP dispatch handler case that parses tool arguments, calls the telemetry service handler, and formats the response.

  case 'check_usage_limits': {
    const limits: UsageLimits = {
      dailyTokenLimit: typeof args?.daily_token_limit === 'number' ? args.daily_token_limit : undefined,
      weeklyTokenLimit: typeof args?.weekly_token_limit === 'number' ? args.weekly_token_limit : undefined,
      sessionTokenLimit: typeof args?.session_token_limit === 'number' ? args.session_token_limit : undefined,
      dailyCostLimit: typeof args?.daily_cost_limit === 'number' ? args.daily_cost_limit : undefined,
      weeklyCostLimit: typeof args?.weekly_cost_limit === 'number' ? args.weekly_cost_limit : undefined,
      sessionCostLimit: typeof args?.session_cost_limit === 'number' ? args.session_cost_limit : undefined,
    };
  
    const warnings = await this.telemetryService.checkUsageLimits(limits);
    return {
      content: [
        {
          type: 'text',
          text: this.formatUsageWarnings(warnings),
        },
      ],
    };
  }