feat: implement granular per-hook/per-action/per-MCP-server token analytics

[ooples]

Problem

Currently, token-optimizer-mcp tracks aggregate token savings at the session level, but lacks granular visibility into:

• Token usage per hook (PreToolUse, PostToolUse, etc.)
• Token usage per action (Read, Write, Grep, etc.)
• Token usage per MCP server (token-optimizer, filesystem, github, etc.)

This makes it impossible to identify optimization opportunities and pinpoint which hooks/actions/servers are consuming the most tokens.

Proposed Solution

Implement server-level analytics that track token usage with fine-grained breakdowns:

1. Per-Hook Analytics

Track tokens for each hook phase:

interface HookAnalytics {
  hookPhase: 'PreToolUse' | 'PostToolUse' | 'SessionStart' | 'PreCompact' | 'UserPromptSubmit'
  toolName: string
  originalTokens: number
  optimizedTokens: number
  tokensSaved: number
  timestamp: number
  duration: number  // execution time in ms
}

2. Per-Action Analytics

Group by Claude Code action (Read, Write, Grep, etc.):

interface ActionAnalytics {
  action: string  // 'Read', 'Write', 'Grep', 'Bash', etc.
  totalCalls: number
  totalOriginalTokens: number
  totalOptimizedTokens: number
  totalTokensSaved: number
  averageReduction: number  // percentage
  cacheHitRate: number
}

3. Per-MCP-Server Analytics

Track token usage across different MCP servers:

interface MCPServerAnalytics {
  serverName: string  // 'token-optimizer', 'filesystem', 'github', etc.
  toolCalls: Map<string, number>  // tool name -> call count
  totalTokensSaved: number
  mostUsedTool: string
  leastOptimizedTool: string  // tool with lowest savings percentage
}

Implementation Details

Data Collection

1. Hook Level: PowerShell dispatcher logs each hook invocation with hook phase, tool name, input tokens, output tokens, duration
2. Action Level: Server-side aggregation groups by action type
3. MCP Server Level: Track MCP protocol tools/call by server

Storage

• Real-time: In-memory aggregation for current session
• Persistent: SQLite tables for historical analysis

API

Add new MCP tools for querying analytics:

• get_hook_analytics()
• get_action_analytics()
• get_mcp_server_analytics()
• export_analytics()

Success Criteria

• Track token usage per hook phase with <5ms overhead
• Aggregate analytics by action type
• Track analytics per MCP server
• Provide CLI tools to query analytics
• Export analytics to CSV/JSON
• Dashboard showing top token consumers
• Historical trending

Benefits

1. Identify optimization opportunities
2. Measure hook performance
3. Compare MCP server efficiency
4. Validate optimization efforts
5. Focus development on high-impact areas

[github-actions]

This issue has been resolved in version 4.2.0. 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀