MCP Context Manager

Instructions

Implementation Reference

• src/index.ts:586-651 (handler)

  The 'get_usage_stats' tool implementation in the main switch statement of the tool handler. It calculates and reports the token usage statistics for the session.

  case 'get_usage_stats': {
    const resetAfter = (args as any)?.reset || false;
    const elapsed = Math.round((Date.now() - sessionStartTime) / 1000);
    const minutes = Math.floor(elapsed / 60);
    const seconds = elapsed % 60;
  
    let totalMcpTokens = 0;
    let totalFullReadTokens = 0;
    let totalCalls = 0;
    let totalFiles = 0;
  
    let report = `📊 MCP Token Usage Stats (session: ${minutes}m ${seconds}s)\n`;
    report += `${'─'.repeat(75)}\n`;
    report += `${'Tool'.padEnd(25)} ${'Calls'.padStart(6)} ${'Tokens'.padStart(8)} ${'Avg'.padStart(6)} ${'Files'.padStart(6)} ${'vs Read'.padStart(12)}\n`;
    report += `${'─'.repeat(75)}\n`;
  
    for (const [tool, stats] of Object.entries(usageStats)) {
      totalMcpTokens += stats.totalTokens;
      totalFullReadTokens += stats.estimatedFullReadTokens;
      totalCalls += stats.calls;
      const fileCount = stats.filesReferenced.size;
      totalFiles += fileCount;
  
      const savings = stats.estimatedFullReadTokens > 0
        ? `${Math.round((1 - stats.totalTokens / stats.estimatedFullReadTokens) * 100)}% saved`
        : 'n/a';
  
      report += `${tool.padEnd(25)} ${String(stats.calls).padStart(6)} ${String(stats.totalTokens).padStart(8)} ${String(stats.avgTokensPerCall).padStart(6)} ${String(fileCount).padStart(6)} ${savings.padStart(12)}\n`;
    }
  
    report += `${'─'.repeat(75)}\n`;
    report += `${'TOTAL'.padEnd(25)} ${String(totalCalls).padStart(6)} ${String(totalMcpTokens).padStart(8)} ${''.padStart(6)} ${String(allFilesReferenced.size).padStart(6)}\n`;
  
    report += `\n📁 Unique files touched: ${allFilesReferenced.size}\n`;
  
    if (totalFullReadTokens > 0) {
      const overallSavings = Math.round((1 - totalMcpTokens / totalFullReadTokens) * 100);
      report += `\n📖 If you Read those ${allFilesReferenced.size} files fully: ~${totalFullReadTokens.toLocaleString()} tokens\n`;
      report += `🔍 MCP returned only relevant parts: ~${totalMcpTokens.toLocaleString()} tokens\n`;
      report += `💡 Saved: ~${(totalFullReadTokens - totalMcpTokens).toLocaleString()} tokens (${overallSavings}%)\n`;
    }
  
    // List the actual files that were referenced
    if (allFilesReferenced.size > 0 && allFilesReferenced.size <= 30) {
      report += `\n📂 Files referenced:\n`;
      for (const file of allFilesReferenced) {
        const tokens = getFileTokenCount(file);
        report += `   ${file} (${tokens > 0 ? tokens.toLocaleString() + ' tokens' : 'unknown size'})\n`;
      }
    } else if (allFilesReferenced.size > 30) {
      report += `\n📂 Files referenced: ${allFilesReferenced.size} files (too many to list)\n`;
    }
  
    if (resetAfter) {
      for (const key of Object.keys(usageStats)) {
        delete usageStats[key];
      }
      allFilesReferenced.clear();
      sessionStartTime = Date.now();
      report += `\n🔄 Stats reset.`;
    }
  
    return {
      content: [{ type: 'text', text: report }],
    };
  }