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
259 lines • 12.1 kB
JavaScript
/**
* Enhanced Error Context & Suggestions
* Provides contextual error messages and actionable remediation steps
* Based on comprehensive real-world feedback from production usage
*/
export class EnhancedErrorContextProvider {
static instance;
static getInstance() {
if (!EnhancedErrorContextProvider.instance) {
EnhancedErrorContextProvider.instance = new EnhancedErrorContextProvider();
}
return EnhancedErrorContextProvider.instance;
}
/**
* Analyze error and provide enhanced context with actionable remediation
*/
analyzeError(error, sessionContext) {
const errorMessage = typeof error === 'string' ? error : error.message;
const errorType = this.categorizeError(errorMessage);
const context = {
originalError: errorMessage,
errorType,
contextualMessage: this.generateContextualMessage(errorType, sessionContext),
remediationSteps: this.generateRemediationSteps(errorType, sessionContext),
suggestedTools: this.getSuggestedTools(errorType, sessionContext),
frameworkSpecific: this.getFrameworkSpecificSuggestions(errorType, sessionContext),
severity: this.assessSeverity(errorType, errorMessage)
};
return context;
}
/**
* Categorize error based on common patterns from real-world usage
*/
categorizeError(errorMessage) {
const lowerError = errorMessage.toLowerCase();
// Session/Browser issues (most common from feedback)
if (lowerError.includes('target page') && lowerError.includes('closed')) {
return 'session_lost';
}
if (lowerError.includes('browser has been closed') || lowerError.includes('session closed')) {
return 'session_lost';
}
if (lowerError.includes('browser crashed') || lowerError.includes('unexpected exit')) {
return 'browser_crashed';
}
// Network issues
if (lowerError.includes('net::err') || lowerError.includes('connection refused')) {
return 'network_failure';
}
if (lowerError.includes('cors') || lowerError.includes('cross-origin')) {
return 'network_failure';
}
// Permission issues
if (lowerError.includes('permission denied') || lowerError.includes('access denied')) {
return 'permission_denied';
}
// Timeout issues
if (lowerError.includes('timeout') || lowerError.includes('timed out')) {
return 'timeout';
}
return 'unknown';
}
/**
* Generate contextual message based on error type and session context
*/
generateContextualMessage(errorType, context) {
const port = context?.port || 'unknown';
const url = context?.url || `localhost:${port}`;
const framework = context?.framework || 'application';
switch (errorType) {
case 'session_lost':
return `Browser session lost while debugging ${framework} at ${url}. This commonly occurs when the development server restarts or the browser tab is manually closed.`;
case 'network_failure':
return `Network connection failed to ${url}. This suggests the development server may not be running or there's a configuration issue.`;
case 'browser_crashed':
return `Browser process crashed unexpectedly. This can happen due to memory issues or system resource constraints.`;
case 'permission_denied':
return `Permission denied while accessing debugging features. This may be due to browser security settings or system permissions.`;
case 'timeout':
return `Operation timed out while communicating with ${url}. The ${framework} application may be unresponsive or overloaded.`;
default:
return `An unexpected error occurred while debugging your ${framework} application. See detailed steps below for resolution.`;
}
}
/**
* Generate specific remediation steps based on error type and context
*/
generateRemediationSteps(errorType, context) {
const port = context?.port || 'your-port';
const url = context?.url || `localhost:${port}`;
const framework = context?.framework || 'application';
switch (errorType) {
case 'session_lost':
return [
`1. Verify ${framework} server is running: Check if ${url} loads in your browser`,
`2. Use session recovery: Try 'inject_debugging' to establish a new session`,
`3. Check server logs: Look for restart messages or errors in your development server`,
`4. Verify port availability: Ensure port ${port} isn't blocked or in use by another process`,
`5. Clear browser cache: Sometimes stale debugging sessions cause conflicts`
];
case 'network_failure':
return [
`1. Start development server: Ensure your ${framework} server is running on ${url}`,
`2. Check port binding: Verify the server is listening on port ${port}`,
`3. Test manual access: Try opening ${url} directly in your browser`,
`4. Check firewall/proxy: Ensure no network restrictions are blocking the connection`,
`5. Verify CORS settings: For API calls, ensure proper cross-origin configuration`
];
case 'browser_crashed':
return [
`1. Restart browser: Close all browser instances and restart`,
`2. Check system resources: Ensure sufficient RAM and CPU available`,
`3. Clear browser data: Remove cache, cookies, and temporary files`,
`4. Update browser: Ensure you're using a recent version of Chrome/Edge`,
`5. Try incognito mode: Test if extensions or settings are causing issues`
];
case 'permission_denied':
return [
`1. Enable developer mode: Ensure browser developer tools are accessible`,
`2. Check macOS permissions: Allow terminal/Node.js to control other applications`,
`3. Run as administrator: Try running your terminal with elevated permissions`,
`4. Disable security software: Temporarily disable antivirus/firewall if applicable`,
`5. Reset browser settings: Clear security-related browser configurations`
];
case 'timeout':
return [
`1. Increase timeout settings: Your ${framework} app may need more time to respond`,
`2. Check application performance: Monitor CPU/memory usage during debugging`,
`3. Simplify test scenario: Try debugging a simpler page or component first`,
`4. Restart development server: Fresh server instance may resolve performance issues`,
`5. Check network latency: Ensure stable connection between browser and server`
];
default:
return [
`1. Restart debugging session: Use 'inject_debugging' to establish fresh session`,
`2. Check browser console: Look for additional error details in developer tools`,
`3. Verify application state: Ensure your ${framework} app is functioning normally`,
`4. Try different browser: Test with Chrome, Firefox, or Safari`,
`5. Contact support: If issue persists, provide error details for further assistance`
];
}
}
/**
* Suggest specific tools to help resolve the error
*/
getSuggestedTools(errorType, context) {
switch (errorType) {
case 'session_lost':
return [
'inject_debugging',
'get_debug_report',
'monitor_realtime'
];
case 'network_failure':
return [
'inject_debugging',
'get_network_activity',
'get_console_logs'
];
case 'browser_crashed':
return [
'inject_debugging',
'get_performance_metrics',
'take_screenshot'
];
case 'timeout':
return [
'get_performance_metrics',
'monitor_realtime',
'get_network_activity'
];
default:
return [
'inject_debugging',
'get_debug_report',
'take_screenshot'
];
}
}
/**
* Get framework-specific suggestions based on detected framework
*/
getFrameworkSpecificSuggestions(errorType, context) {
if (!context?.framework)
return undefined;
const suggestions = {
'react': [
'Check React DevTools for component errors',
'Verify React version compatibility',
'Look for hydration mismatches in SSR apps',
'Check for infinite re-render loops in useEffect'
],
'nextjs': [
'Check Next.js build logs for compilation errors',
'Verify API routes are responding correctly',
'Check for hydration errors in browser console',
'Ensure proper getServerSideProps/getStaticProps implementation'
],
'fastapi': [
'Check FastAPI server logs for uncaught exceptions',
'Verify CORS middleware configuration',
'Test API endpoints directly with curl or Postman',
'Check for database connection issues'
]
};
return suggestions[context.framework] || [];
}
/**
* Assess error severity for prioritization
*/
assessSeverity(errorType, errorMessage) {
// Critical errors that completely block debugging
if (errorType === 'browser_crashed' || errorType === 'permission_denied') {
return 'critical';
}
// High priority errors that lose session state
if (errorType === 'session_lost') {
return 'high';
}
// Medium priority errors that can be worked around
if (errorType === 'network_failure' || errorType === 'timeout') {
return 'medium';
}
// Low priority for unknown or minor errors
return 'low';
}
/**
* Format error context for display to user
*/
formatErrorForUser(errorContext) {
const { contextualMessage, remediationSteps, suggestedTools, frameworkSpecific, severity } = errorContext;
let formatted = `🚨 ${severity.toUpperCase()} PRIORITY ERROR\n\n`;
formatted += `${contextualMessage}\n\n`;
formatted += `🛠️ REMEDIATION STEPS:\n`;
remediationSteps.forEach(step => {
formatted += `${step}\n`;
});
formatted += `\n🔧 SUGGESTED TOOLS:\n`;
suggestedTools.forEach(tool => {
formatted += `• ${tool}\n`;
});
if (frameworkSpecific && frameworkSpecific.length > 0) {
formatted += `\n🎯 FRAMEWORK-SPECIFIC TIPS:\n`;
frameworkSpecific.forEach(tip => {
formatted += `• ${tip}\n`;
});
}
return formatted;
}
/**
* Update session context for better error analysis
*/
updateSessionContext(context) {
// Store context for future error analysis
// This would integrate with session management
}
}
export default EnhancedErrorContextProvider;
//# sourceMappingURL=enhanced-error-context.js.map