Claude Telemetry MCP

Instructions

Implementation Reference

• src/telemetry-service.ts:131-159 (handler)

  Core handler function that executes the tool logic by querying Prometheus for aggregate session metrics and computing averages, totals, and session extremes.

  async getSessionAnalytics(): Promise<SessionAnalytics> {
    const queries = {
      totalSessions: 'sum(claude_code_session_count_total)',
      totalTokens: 'sum(claude_code_token_usage_tokens_total)',
      totalActiveTime: 'sum(claude_code_active_time_seconds_total)',
      totalCost: 'sum(claude_code_cost_usage_USD_total)',
      totalLines: 'sum(claude_code_lines_of_code_count_total)',
      totalCommits: 'sum(claude_code_commit_count_total)'
    };
  
    const results = await this.executeQueries(queries);
  
    const totalSessions = results.totalSessions || 1; // Avoid division by zero
    
    return {
      totalSessions,
      averageTokensPerSession: (results.totalTokens || 0) / totalSessions,
      averageActiveTimePerSession: (results.totalActiveTime || 0) / totalSessions,
      averageCostPerSession: (results.totalCost || 0) / totalSessions,
      longestSession: {
        tokens: results.totalTokens || 0, // This would need more sophisticated querying for actual longest session
        activeTime: results.totalActiveTime || 0
      },
      mostProductiveSession: {
        linesOfCode: results.totalLines || 0,
        commits: results.totalCommits || 0
      }
    };
  }

• src/index.ts:333-343 (handler)

  MCP server handler that dispatches the tool call to the TelemetryService and returns formatted response.

  case 'get_session_analytics': {
    const analytics = await this.telemetryService.getSessionAnalytics();
    return {
      content: [
        {
          type: 'text',
          text: this.formatSessionAnalytics(analytics),
        },
      ],
    };
  }

• src/index.ts:147-154 (registration)

  Tool registration in the list of tools provided to ListToolsRequest, including name, description, and input schema.

  {
    name: 'get_session_analytics',
    description: 'Get analytics about session patterns (averages, totals, productivity metrics)',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/types.ts:54-67 (schema)

  TypeScript interface defining the structure of the SessionAnalytics return type.

  export interface SessionAnalytics {
    totalSessions: number;
    averageTokensPerSession: number;
    averageActiveTimePerSession: number;
    averageCostPerSession: number;
    longestSession: {
      tokens: number;
      activeTime: number;
    };
    mostProductiveSession: {
      linesOfCode: number;
      commits: number;
    };
  }

• src/index.ts:471-483 (helper)

  Helper function that formats the SessionAnalytics data into a human-readable markdown string for the tool response.

  private formatSessionAnalytics(analytics: SessionAnalytics): string {
    return `## Session Analytics\n\n` +
      `**Total Sessions**: ${analytics.totalSessions}\n` +
      `**Average Tokens/Session**: ${Math.round(analytics.averageTokensPerSession).toLocaleString()}\n` +
      `**Average Active Time/Session**: ${Math.round(analytics.averageActiveTimePerSession / 60)}m\n` +
      `**Average Cost/Session**: $${analytics.averageCostPerSession.toFixed(4)}\n\n` +
      `**Peak Session**:\n` +
      `- Tokens: ${analytics.longestSession.tokens.toLocaleString()}\n` +
      `- Active Time: ${Math.round(analytics.longestSession.activeTime / 60)}m\n\n` +
      `**Most Productive Session**:\n` +
      `- Lines of Code: ${analytics.mostProductiveSession.linesOfCode.toLocaleString()}\n` +
      `- Commits: ${analytics.mostProductiveSession.commits}`;
  }