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
544 lines • 23.9 kB
JavaScript
/**
* AI Feedback Analytics Handler - Phase 2 MCP Tools
*
* Advanced analytics and intelligence tools for AI feedback analysis,
* real-time monitoring, and predictive insights.
*/
import { BaseHandler } from './base-handler.js';
import { UserFriendlyLogger } from '../utils/user-friendly-logger.js';
import { AIFeedbackCollector } from '../utils/ai-feedback-collector.js';
import { AIFeedbackAnalyticsEngine } from '../utils/ai-feedback-analytics-engine.js';
import { AIFeedbackRealtimeDashboard } from '../utils/ai-feedback-realtime-dashboard.js';
export class AIFeedbackAnalyticsHandler extends BaseHandler {
analyticsEngine;
realtimeDashboard;
feedbackCollector;
logger;
constructor() {
super();
this.analyticsEngine = new AIFeedbackAnalyticsEngine();
this.realtimeDashboard = new AIFeedbackRealtimeDashboard();
this.feedbackCollector = new AIFeedbackCollector({
persistenceMode: 'file',
enableAutoCollection: true,
analysisEnabled: true
});
this.logger = new UserFriendlyLogger('AIFeedbackAnalytics');
// Load persisted feedback
this.feedbackCollector.loadPersistedFeedback().catch(error => {
this.logger.warn(`Failed to load persisted feedback: ${error instanceof Error ? error.message : 'Unknown error'}`);
});
}
tools = [
{
name: 'generate_intelligence_report',
description: '🧠 GENERATE AI INTELLIGENCE REPORT: Create comprehensive analytics report with trends, anomalies, patterns, and predictions from AI feedback data.',
inputSchema: {
type: 'object',
properties: {
timeRange: {
type: 'object',
description: 'Time range for analysis',
properties: {
start: { type: 'number', description: 'Start timestamp (Unix milliseconds)' },
end: { type: 'number', description: 'End timestamp (Unix milliseconds)' }
}
},
includeDetails: {
type: 'boolean',
default: false,
description: 'Include detailed analysis (may be large)'
}
}
}
},
{
name: 'start_realtime_monitoring',
description: '📊 START REAL-TIME MONITORING: Begin real-time analytics dashboard with live trend detection and alert generation.',
inputSchema: {
type: 'object',
properties: {
refreshInterval: {
type: 'number',
default: 300000,
description: 'Refresh interval in milliseconds (default: 5 minutes)'
},
enableAlerts: {
type: 'boolean',
default: true,
description: 'Enable real-time alerts for anomalies'
}
}
}
},
{
name: 'get_dashboard_status',
description: '📈 GET DASHBOARD STATUS: Retrieve current real-time dashboard metrics, alerts, and system health status.',
inputSchema: {
type: 'object',
properties: {
includeSummary: {
type: 'boolean',
default: true,
description: 'Include executive summary and recommendations'
}
}
}
},
{
name: 'analyze_feedback_trends',
description: '📊 ANALYZE FEEDBACK TRENDS: Perform deep trend analysis on satisfaction, usage patterns, and performance metrics.',
inputSchema: {
type: 'object',
properties: {
metric: {
type: 'string',
enum: ['satisfaction', 'efficiency', 'usage', 'errors', 'all'],
default: 'all',
description: 'Specific metric to analyze'
},
period: {
type: 'string',
enum: ['24h', '7d', '30d', 'all'],
default: '7d',
description: 'Analysis period'
}
}
}
},
{
name: 'detect_anomalies',
description: '🚨 DETECT ANOMALIES: Identify unusual patterns, performance spikes, or satisfaction drops in feedback data.',
inputSchema: {
type: 'object',
properties: {
sensitivity: {
type: 'string',
enum: ['low', 'medium', 'high'],
default: 'medium',
description: 'Anomaly detection sensitivity'
},
focusArea: {
type: 'string',
enum: ['satisfaction', 'performance', 'usage', 'errors', 'all'],
default: 'all',
description: 'Focus area for anomaly detection'
}
}
}
},
{
name: 'get_predictive_insights',
description: '🔮 GET PREDICTIVE INSIGHTS: Generate predictive analysis and forecasts for feedback trends and user satisfaction.',
inputSchema: {
type: 'object',
properties: {
timeframe: {
type: 'string',
enum: ['1_week', '1_month', '3_months'],
default: '1_month',
description: 'Prediction timeframe'
},
confidence: {
type: 'string',
enum: ['conservative', 'balanced', 'aggressive'],
default: 'balanced',
description: 'Prediction confidence level'
}
}
}
},
{
name: 'generate_automated_report',
description: '📄 GENERATE AUTOMATED REPORT: Create formatted analytics report for stakeholders with key insights and recommendations.',
inputSchema: {
type: 'object',
properties: {
format: {
type: 'string',
enum: ['executive', 'technical', 'full'],
default: 'executive',
description: 'Report format and detail level'
},
includeCharts: {
type: 'boolean',
default: false,
description: 'Include chart data (text-based)'
}
}
}
},
{
name: 'configure_analytics',
description: '⚙️ CONFIGURE ANALYTICS: Adjust analytics engine settings, thresholds, and monitoring parameters.',
inputSchema: {
type: 'object',
properties: {
alertThresholds: {
type: 'object',
description: 'Alert threshold configuration',
properties: {
satisfactionDrop: { type: 'number', description: 'Satisfaction drop threshold' },
errorRateSpike: { type: 'number', description: 'Error rate spike threshold' },
usageDrop: { type: 'number', description: 'Usage drop threshold' }
}
},
refreshInterval: {
type: 'number',
description: 'Dashboard refresh interval (milliseconds)'
}
}
}
}
];
async handle(toolName, args) {
try {
switch (toolName) {
case 'generate_intelligence_report':
return await this.generateIntelligenceReport(args);
case 'start_realtime_monitoring':
return await this.startRealtimeMonitoring(args);
case 'get_dashboard_status':
return await this.getDashboardStatus(args);
case 'analyze_feedback_trends':
return await this.analyzeFeedbackTrends(args);
case 'detect_anomalies':
return await this.detectAnomalies(args);
case 'get_predictive_insights':
return await this.getPredictiveInsights(args);
case 'generate_automated_report':
return await this.generateAutomatedReport(args);
case 'configure_analytics':
return await this.configureAnalytics(args);
default:
throw new Error(`Unknown tool: ${toolName}`);
}
}
catch (error) {
this.logger.error(`Tool ${toolName} failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Generate comprehensive intelligence report
*/
async generateIntelligenceReport(args) {
this.logger.info('🧠 Generating AI intelligence report...');
try {
const feedbackData = this.feedbackCollector.getAllFeedback();
const timeRange = args.timeRange ? {
start: args.timeRange.start,
end: args.timeRange.end
} : undefined;
const report = await this.analyticsEngine.generateIntelligenceReport(feedbackData, timeRange);
this.logger.info(`✅ Intelligence report generated: ${report.summary.totalFeedback} entries analyzed`);
// Simplified response for Claude Code CLI compatibility
if (!args.includeDetails) {
return {
success: true,
summary: {
totalFeedback: report.summary.totalFeedback,
avgSatisfaction: Math.round(report.summary.avgSatisfaction * 10) / 10,
trendDirection: report.summary.trendDirection,
criticalInsights: report.summary.criticalInsights
},
insights: report.actionableInsights.slice(0, 3).map(i => i.insight),
reportId: `report_${Date.now()}`
};
}
return {
success: true,
report: {
summary: report.summary,
trendsCount: report.trends.length,
anomaliesCount: report.anomalies.length,
patternsCount: report.patterns.length,
predictionsCount: report.predictions.length,
insightsCount: report.actionableInsights.length
},
topInsights: report.actionableInsights.slice(0, 5).map(i => ({
priority: i.priority,
category: i.category,
insight: i.insight
}))
};
}
catch (error) {
this.logger.error(`Failed to generate intelligence report: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to generate report',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Start real-time monitoring dashboard
*/
async startRealtimeMonitoring(args) {
this.logger.info('📊 Starting real-time monitoring...');
try {
const configuration = {
refreshInterval: args.refreshInterval || 300000, // 5 minutes default
enableRealTimeAlerts: args.enableAlerts !== false
};
// Data source function for the dashboard
const feedbackDataSource = async () => {
return this.feedbackCollector.getAllFeedback();
};
await this.realtimeDashboard.startMonitoring(feedbackDataSource);
this.logger.info('✅ Real-time monitoring started successfully');
return {
success: true,
message: 'Real-time monitoring started',
refreshInterval: configuration.refreshInterval,
alertsEnabled: configuration.enableRealTimeAlerts
};
}
catch (error) {
this.logger.error(`Failed to start monitoring: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to start monitoring',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Get current dashboard status
*/
async getDashboardStatus(args) {
this.logger.info('📈 Getting dashboard status...');
try {
const dashboard = this.realtimeDashboard.getCurrentDashboard();
if (!args.includeSummary) {
return {
success: true,
isMonitoring: dashboard.isMonitoring,
hasMetrics: dashboard.latestMetrics !== null,
alertsCount: dashboard.recentAlerts.length
};
}
const summary = this.realtimeDashboard.generateDashboardSummary();
this.logger.info(`✅ Dashboard status: ${summary.status}`);
return {
success: true,
status: summary.status,
isMonitoring: dashboard.isMonitoring,
summary: summary.summary,
keyMetrics: summary.keyMetrics,
criticalAlerts: summary.criticalAlerts,
recommendations: summary.recommendations.slice(0, 3)
};
}
catch (error) {
this.logger.error(`Failed to get dashboard status: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to get status',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Analyze feedback trends
*/
async analyzeFeedbackTrends(args) {
this.logger.info(`📊 Analyzing ${args.metric || 'all'} trends for ${args.period || '7d'}...`);
try {
const feedbackData = this.feedbackCollector.getAllFeedback();
const now = Date.now();
// Calculate time range based on period
const periodMs = this.parsePeriod(args.period || '7d');
const timeRange = {
start: now - periodMs,
end: now
};
const filteredData = feedbackData.filter(f => f.timestamp >= timeRange.start && f.timestamp <= timeRange.end);
if (filteredData.length === 0) {
return {
success: true,
message: 'No data available for the specified period',
trend: 'stable',
dataPoints: 0
};
}
const report = await this.analyticsEngine.generateIntelligenceReport(filteredData, timeRange);
const relevantTrends = args.metric === 'all' ? report.trends :
report.trends.filter(t => t.timeframe.includes(args.metric));
this.logger.info(`✅ Trend analysis complete: ${relevantTrends.length} trends identified`);
return {
success: true,
trendsFound: relevantTrends.length,
overallDirection: report.summary.trendDirection,
avgSatisfaction: Math.round(report.summary.avgSatisfaction * 10) / 10,
dataPoints: filteredData.length,
keyInsights: relevantTrends.slice(0, 3).map(t => t.insights[0]).filter(Boolean)
};
}
catch (error) {
this.logger.error(`Failed to analyze trends: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to analyze trends',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Detect anomalies in feedback data
*/
async detectAnomalies(args) {
this.logger.info(`🚨 Detecting anomalies (${args.sensitivity || 'medium'} sensitivity)...`);
try {
const feedbackData = this.feedbackCollector.getAllFeedback();
const report = await this.analyticsEngine.generateIntelligenceReport(feedbackData);
// Filter anomalies based on focus area if specified
let anomalies = report.anomalies;
if (args.focusArea && args.focusArea !== 'all') {
anomalies = anomalies.filter(a => a.anomalyType.includes(args.focusArea) ||
a.description.toLowerCase().includes(args.focusArea));
}
// Adjust sensitivity (this is a simplified implementation)
if (args.sensitivity === 'low') {
anomalies = anomalies.filter(a => a.severity === 'critical' || a.severity === 'high');
}
else if (args.sensitivity === 'high') {
// Include all anomalies for high sensitivity
}
this.logger.info(`✅ Anomaly detection complete: ${anomalies.length} anomalies found`);
return {
success: true,
anomaliesFound: anomalies.length,
criticalAnomalies: anomalies.filter(a => a.severity === 'critical').length,
highSeverity: anomalies.filter(a => a.severity === 'high').length,
recentAnomalies: anomalies.slice(0, 3).map(a => ({
type: a.anomalyType,
severity: a.severity,
description: a.description
}))
};
}
catch (error) {
this.logger.error(`Failed to detect anomalies: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to detect anomalies',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Get predictive insights
*/
async getPredictiveInsights(args) {
this.logger.info(`🔮 Generating predictive insights for ${args.timeframe || '1_month'}...`);
try {
const feedbackData = this.feedbackCollector.getAllFeedback();
const report = await this.analyticsEngine.generateIntelligenceReport(feedbackData);
// Filter predictions by timeframe
const predictions = report.predictions.filter(p => !args.timeframe || p.prediction.timeframe === args.timeframe);
this.logger.info(`✅ Predictive insights generated: ${predictions.length} predictions`);
return {
success: true,
predictionsGenerated: predictions.length,
confidence: args.confidence || 'balanced',
timeframe: args.timeframe || '1_month',
keyPredictions: predictions.slice(0, 3).map(p => ({
metric: p.metric,
expectedValue: Math.round(p.prediction.expectedValue * 10) / 10,
confidence: Math.round(p.prediction.confidence * 100)
}))
};
}
catch (error) {
this.logger.error(`Failed to generate predictions: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to generate predictions',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Generate automated report
*/
async generateAutomatedReport(args) {
this.logger.info(`📄 Generating ${args.format || 'executive'} report...`);
try {
const feedbackData = this.feedbackCollector.getAllFeedback();
const report = await this.analyticsEngine.generateIntelligenceReport(feedbackData);
const dashboard = this.realtimeDashboard.generateDashboardSummary();
const reportContent = this.formatReport(report, dashboard, args.format || 'executive');
this.logger.info('✅ Automated report generated successfully');
return {
success: true,
format: args.format || 'executive',
reportLength: reportContent.length,
generatedAt: new Date().toISOString(),
summary: reportContent.substring(0, 200) + '...'
};
}
catch (error) {
this.logger.error(`Failed to generate report: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to generate report',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
/**
* Configure analytics settings
*/
async configureAnalytics(args) {
this.logger.info('⚙️ Configuring analytics settings...');
try {
// This would update configuration - simplified for now
const updates = [];
if (args.alertThresholds) {
updates.push('Alert thresholds updated');
}
if (args.refreshInterval) {
updates.push('Refresh interval updated');
}
this.logger.info('✅ Analytics configuration updated');
return {
success: true,
message: 'Configuration updated',
updatesApplied: updates.length,
changes: updates
};
}
catch (error) {
this.logger.error(`Failed to configure analytics: ${error instanceof Error ? error.message : 'Unknown error'}`);
return {
success: false,
message: 'Failed to update configuration',
error: error instanceof Error ? error.message : 'Unknown error'
};
}
}
// Helper methods
parsePeriod(period) {
switch (period) {
case '24h': return 24 * 60 * 60 * 1000;
case '7d': return 7 * 24 * 60 * 60 * 1000;
case '30d': return 30 * 24 * 60 * 60 * 1000;
default: return 7 * 24 * 60 * 60 * 1000;
}
}
formatReport(report, dashboard, format) {
// Simplified report formatting
return `AI Feedback Analytics Report (${format})\n` +
`Generated: ${new Date().toISOString()}\n` +
`Total Feedback: ${report.summary.totalFeedback}\n` +
`Average Satisfaction: ${report.summary.avgSatisfaction.toFixed(1)}/10\n` +
`Trend Direction: ${report.summary.trendDirection}\n` +
`Critical Insights: ${report.summary.criticalInsights}`;
}
}
//# sourceMappingURL=ai-feedback-analytics-handler.js.map