ai-debug-local-mcp
Version:
🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh
464 lines • 22 kB
JavaScript
/**
* Value Tracking Handler
*
* MCP tools for tracking and displaying the real value delivered by AI-Debug:
* context preservation, time savings, automation benefits, and debugging efficiency.
*/
import { BaseHandler } from './base-handler.js';
import { DebuggingValueTracker } from '../utils/debugging-value-tracker.js';
import { UserFriendlyLogger } from '../utils/user-friendly-logger.js';
export class ValueTrackingHandler extends BaseHandler {
valueTracker;
logger;
constructor() {
super();
this.valueTracker = new DebuggingValueTracker();
this.logger = new UserFriendlyLogger('ValueTracking');
}
tools = [
{
name: 'track_debugging_value',
description: '📊 TRACK DEBUGGING VALUE: Record the real value delivered in a debugging session - context preservation, time savings, and automation benefits.',
inputSchema: {
type: 'object',
properties: {
sessionId: {
type: 'string',
description: 'Debugging session ID'
},
valueType: {
type: 'string',
enum: ['context_preservation', 'time_savings', 'efficiency', 'automation'],
description: 'Type of value to track'
},
contextData: {
type: 'object',
description: 'Context preservation data',
properties: {
mainConversationLines: { type: 'number' },
subAgentOutput: {
type: 'object',
properties: {
agentType: { type: 'string' },
taskDescription: { type: 'string' },
outputLines: { type: 'number' },
executionTime: { type: 'number' }
}
}
}
},
timeData: {
type: 'object',
description: 'Time savings data',
properties: {
taskType: { type: 'string' },
automatedSteps: {
type: 'array',
items: { type: 'string' }
},
actualExecutionTimeMs: { type: 'number' }
}
},
efficiencyData: {
type: 'object',
description: 'Debugging efficiency data',
properties: {
issuesIdentified: { type: 'number' },
issuesResolved: { type: 'number' },
toolsUsed: {
type: 'array',
items: { type: 'string' }
},
automatedActions: { type: 'number' },
debuggingDepth: {
type: 'string',
enum: ['surface', 'moderate', 'deep']
},
outcomes: {
type: 'array',
items: {
type: 'object',
properties: {
type: { type: 'string' },
severity: {
type: 'string',
enum: ['critical', 'high', 'medium', 'low']
},
resolutionTime: { type: 'number' },
automated: { type: 'boolean' }
}
}
}
}
},
automationData: {
type: 'object',
description: 'Workflow automation data',
properties: {
workflowType: { type: 'string' },
manualStepsEliminated: {
type: 'array',
items: { type: 'string' }
},
professionalCapabilities: {
type: 'array',
items: { type: 'string' }
}
}
}
},
required: ['sessionId', 'valueType']
}
},
{
name: 'get_value_summary',
description: '💰 GET VALUE SUMMARY: See the total value delivered by AI-Debug across all sessions - time saved, quality improvements, and productivity gains.',
inputSchema: {
type: 'object',
properties: {
format: {
type: 'string',
enum: ['detailed', 'summary', 'report'],
default: 'summary',
description: 'Output format for value summary'
}
}
}
},
{
name: 'get_session_value',
description: '📈 GET SESSION VALUE: Get the specific value delivered in a particular debugging session.',
inputSchema: {
type: 'object',
properties: {
sessionId: {
type: 'string',
description: 'Session ID to analyze'
}
},
required: ['sessionId']
}
},
{
name: 'show_value_metrics',
description: '📊 SHOW VALUE METRICS: Display real-time value metrics during debugging - NOT token savings but actual productivity gains.',
inputSchema: {
type: 'object',
properties: {
includeExplanation: {
type: 'boolean',
default: true,
description: 'Include explanation of what these metrics mean'
}
}
}
},
{
name: 'compare_workflow_efficiency',
description: 'âš¡ COMPARE WORKFLOW EFFICIENCY: Compare AI-Debug automated workflow vs manual debugging approach.',
inputSchema: {
type: 'object',
properties: {
workflowType: {
type: 'string',
description: 'Type of debugging workflow to compare',
enum: [
'simple-bug-fix',
'ui-debugging',
'performance-analysis',
'accessibility-audit',
'cross-browser-testing',
'integration-debugging',
'complex-state-debugging'
]
},
stepsAutomated: {
type: 'array',
items: { type: 'string' },
description: 'List of steps that were automated'
}
},
required: ['workflowType']
}
},
{
name: 'suggest_premium_features',
description: '✨ SUGGEST PREMIUM FEATURES: Based on usage patterns, suggest premium features that could add more value.',
inputSchema: {
type: 'object',
properties: {
currentUsagePattern: {
type: 'string',
description: 'Description of current debugging patterns',
default: 'general'
}
}
}
}
];
async handle(toolName, args) {
try {
switch (toolName) {
case 'track_debugging_value':
return await this.trackDebuggingValue(args);
case 'get_value_summary':
return await this.getValueSummary(args);
case 'get_session_value':
return await this.getSessionValue(args);
case 'show_value_metrics':
return await this.showValueMetrics(args);
case 'compare_workflow_efficiency':
return await this.compareWorkflowEfficiency(args);
case 'suggest_premium_features':
return await this.suggestPremiumFeatures(args);
default:
throw new Error(`Unknown tool: ${toolName}`);
}
}
catch (error) {
this.logger.error(`Value tracking tool failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
async trackDebuggingValue(args) {
const { sessionId, valueType } = args;
this.logger.info(`📊 Tracking ${valueType} value for session ${sessionId}`);
try {
switch (valueType) {
case 'context_preservation':
if (args.contextData) {
this.valueTracker.trackContextPreservation(sessionId, args.contextData.mainConversationLines, args.contextData.subAgentOutput);
}
break;
case 'time_savings':
if (args.timeData) {
this.valueTracker.trackTimeSavings(sessionId, args.timeData.taskType, args.timeData.automatedSteps, args.timeData.actualExecutionTimeMs);
}
break;
case 'efficiency':
if (args.efficiencyData) {
this.valueTracker.trackDebuggingEfficiency(sessionId, args.efficiencyData);
}
break;
case 'automation':
if (args.automationData) {
this.valueTracker.trackWorkflowAutomation(sessionId, args.automationData.workflowType, args.automationData.manualStepsEliminated, args.automationData.professionalCapabilities);
}
break;
}
const sessionValue = this.valueTracker.getSessionValue(sessionId);
return {
success: true,
message: `Tracked ${valueType} value`,
currentSessionValue: {
contextPreserved: `${sessionValue.contextPreserved} lines`,
timeSaved: `${sessionValue.timeSaved.toFixed(2)} hours`,
efficiencyScore: `${(sessionValue.efficiencyScore * 100).toFixed(1)}%`,
automationLevel: `${sessionValue.automationLevel}%`,
estimatedValue: `$${sessionValue.estimatedValue.toFixed(2)}`
}
};
}
catch (error) {
return {
success: false,
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
async getValueSummary(args) {
const { format = 'summary' } = args;
this.logger.info(`💰 Generating value summary (${format} format)`);
const summary = this.valueTracker.getValueDeliveredSummary();
if (format === 'report') {
return {
success: true,
report: this.valueTracker.generateValueReport()
};
}
if (format === 'detailed') {
return {
success: true,
...summary
};
}
// Summary format
return {
success: true,
summary: {
totalValue: `$${summary.estimatedValueDelivered.dollarValue.toFixed(2)}`,
timeSaved: `${summary.timeEfficiency.totalTimeSavedHours.toFixed(1)} hours`,
productivityBoost: `${summary.timeEfficiency.averageSpeedupFactor.toFixed(1)}x`,
contextPreserved: `${summary.contextPreserved.totalLinesKeptFromMain} lines`,
issuesResolved: summary.debuggingQuality.totalIssuesResolved,
criticalBugsCaught: summary.debuggingQuality.criticalBugsCaught,
automationLevel: `${Math.round(summary.automationValue.totalStepsAutomated / Math.max(1, summary.totalSessions))} steps/session`
},
insight: this.generateValueInsight(summary)
};
}
async getSessionValue(args) {
const { sessionId } = args;
this.logger.info(`📈 Getting value for session ${sessionId}`);
const sessionValue = this.valueTracker.getSessionValue(sessionId);
return {
success: true,
sessionId,
value: {
contextPreserved: `${sessionValue.contextPreserved} lines kept from main chat`,
timeSaved: `${sessionValue.timeSaved.toFixed(2)} hours`,
efficiencyScore: `${(sessionValue.efficiencyScore * 100).toFixed(1)}% success rate`,
automationLevel: `${sessionValue.automationLevel}% automated`,
estimatedValue: `$${sessionValue.estimatedValue.toFixed(2)}`
},
explanation: `This session saved approximately ${sessionValue.timeSaved.toFixed(2)} hours of manual debugging time, worth $${sessionValue.estimatedValue.toFixed(2)} in developer productivity.`
};
}
async showValueMetrics(args) {
const { includeExplanation = true } = args;
this.logger.info('📊 Showing real-time value metrics');
const summary = this.valueTracker.getValueDeliveredSummary();
const metrics = {
success: true,
realTimeMetrics: {
contextCleanliness: `${summary.contextPreserved.cleanConversationScore.toFixed(0)}/100`,
debuggingSpeed: `${summary.timeEfficiency.averageSpeedupFactor.toFixed(1)}x faster`,
successRate: `${(summary.debuggingQuality.overallSuccessRate * 100).toFixed(1)}%`,
automationLevel: `${Math.round(summary.automationValue.totalStepsAutomated / Math.max(1, summary.totalSessions))} steps automated per session`
}
};
if (includeExplanation) {
metrics.explanation = {
contextCleanliness: "How much debugging noise is kept out of your main conversation",
debuggingSpeed: "How much faster you debug with AI-Debug vs manual approach",
successRate: "Percentage of identified issues that were successfully resolved",
automationLevel: "Average number of manual steps eliminated per debugging session"
};
metrics.note = "These are REAL productivity metrics, not token savings. Sub-agents still use tokens, but they preserve your context and accelerate debugging.";
}
return metrics;
}
async compareWorkflowEfficiency(args) {
const { workflowType, stepsAutomated = [] } = args;
this.logger.info(`âš¡ Comparing ${workflowType} workflow efficiency`);
// Manual workflow estimates
const manualWorkflows = {
'simple-bug-fix': {
steps: ['Reproduce bug', 'Inspect elements', 'Check console', 'Identify cause', 'Test fix'],
timeMinutes: 15
},
'ui-debugging': {
steps: ['Open browser', 'Navigate to page', 'Open DevTools', 'Inspect elements', 'Check styles', 'Test interactions', 'Verify responsive'],
timeMinutes: 30
},
'performance-analysis': {
steps: ['Setup profiling', 'Record performance', 'Analyze timeline', 'Identify bottlenecks', 'Test optimizations', 'Measure improvements'],
timeMinutes: 45
},
'accessibility-audit': {
steps: ['Install tools', 'Run audit', 'Review issues', 'Test with screen reader', 'Fix violations', 'Retest'],
timeMinutes: 60
},
'cross-browser-testing': {
steps: ['Setup browsers', 'Test Chrome', 'Test Firefox', 'Test Safari', 'Test Edge', 'Document issues', 'Apply fixes', 'Retest all'],
timeMinutes: 90
}
};
const manual = manualWorkflows[workflowType] || {
steps: ['Generic steps'],
timeMinutes: 30
};
const automatedStepsCount = stepsAutomated.length || manual.steps.length;
const timeSavedMinutes = (automatedStepsCount / manual.steps.length) * manual.timeMinutes;
const efficiencyGain = (timeSavedMinutes / manual.timeMinutes) * 100;
return {
success: true,
comparison: {
workflow: workflowType,
manual: {
steps: manual.steps,
estimatedTime: `${manual.timeMinutes} minutes`,
cognitiveLoad: 'high'
},
automated: {
stepsEliminated: stepsAutomated.length > 0 ? stepsAutomated : manual.steps,
actualTime: `~${Math.round(manual.timeMinutes * 0.2)} minutes`,
cognitiveLoad: 'low'
},
efficiency: {
timeSaved: `${Math.round(timeSavedMinutes)} minutes`,
speedup: `${(manual.timeMinutes / (manual.timeMinutes * 0.2)).toFixed(1)}x faster`,
efficiencyGain: `${efficiencyGain.toFixed(0)}%`
}
},
insight: `AI-Debug automates ${automatedStepsCount} manual steps, saving ~${Math.round(timeSavedMinutes)} minutes and reducing cognitive load so you can focus on solving problems, not debugging mechanics.`
};
}
async suggestPremiumFeatures(args) {
const { currentUsagePattern = 'general' } = args;
this.logger.info('✨ Suggesting premium features based on usage');
const premiumFeatures = {
cloud_analytics: {
name: 'Cloud Analytics Dashboard',
description: 'Aggregate debugging patterns across all sessions with insights',
value: 'See trends, identify recurring issues, optimize debugging workflows',
pricing: '$19/month'
},
team_collaboration: {
name: 'Team Debugging Sessions',
description: 'Share debugging sessions with team members in real-time',
value: 'Collaborative problem solving, knowledge sharing, faster resolution',
pricing: '$49/month per team'
},
ai_insights: {
name: 'AI-Powered Insights',
description: 'Advanced AI analysis of debugging patterns with recommendations',
value: 'Predictive issue detection, automated fix suggestions',
pricing: '$29/month'
},
workflow_automation: {
name: 'Custom Workflow Automation',
description: 'Create and save custom debugging workflows for your stack',
value: 'One-click complex debugging sequences, team standardization',
pricing: '$39/month'
},
enterprise_compliance: {
name: 'Enterprise Compliance Suite',
description: 'SOC2, HIPAA compliant debugging with audit trails',
value: 'Secure debugging for regulated industries',
pricing: 'Custom pricing'
}
};
// Suggest based on usage pattern
const suggestions = currentUsagePattern === 'general'
? ['cloud_analytics', 'workflow_automation']
: ['ai_insights', 'team_collaboration'];
return {
success: true,
currentPlan: 'Free (Local Debugging)',
suggestedUpgrades: suggestions.map(key => premiumFeatures[key]),
valueProposition: `Based on your debugging patterns, these premium features could save an additional ${suggestions.length * 10} hours per month.`,
callToAction: 'Try any premium feature free for 14 days'
};
}
generateValueInsight(summary) {
const hoursSaved = summary.timeEfficiency.totalTimeSavedHours;
const dollarValue = summary.estimatedValueDelivered.dollarValue;
if (hoursSaved > 40) {
return `You've saved over a full work week of debugging time! That's ${dollarValue.toFixed(0)} worth of productivity gains.`;
}
else if (hoursSaved > 10) {
return `AI-Debug has saved you ${hoursSaved.toFixed(1)} hours - enough time to build a new feature instead of debugging!`;
}
else if (summary.totalSessions > 5) {
return `Your debugging is ${summary.timeEfficiency.averageSpeedupFactor.toFixed(1)}x faster with AI-Debug. Keep using it to compound these gains!`;
}
else {
return 'Just getting started? Each debugging session with AI-Debug saves 30-90 minutes vs manual debugging.';
}
}
}
//# sourceMappingURL=value-tracking-handler.js.map