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), }, ], }; }