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
636 lines • 28 kB
JavaScript
/**
* Tool Dependency Manager
* Addresses Flutter feedback: "Tool interdependencies aren't clearly documented"
* Provides clear prerequisites, workflow guidance, and dependency validation
*/
export class ToolDependencyManager {
dependencies = new Map();
constructor() {
this.initializeToolDependencies();
}
/**
* Validate if a tool can be used given current session state
* Addresses: "Tools seem to expect specific Flutter app states that weren't documented"
*/
validateToolUsage(toolName, sessionState, completedTools = []) {
const dependency = this.dependencies.get(toolName);
if (!dependency) {
return {
isValid: true,
missingDependencies: [],
missingPrerequisites: [],
warnings: [`Tool ${toolName} not found in dependency registry`],
recommendations: [],
estimatedSetupTime: 0
};
}
const result = {
isValid: true,
missingDependencies: [],
missingPrerequisites: [],
warnings: [],
recommendations: [],
estimatedSetupTime: 0
};
// Check required dependencies
for (const requiredTool of dependency.dependencies.required) {
if (!completedTools.includes(requiredTool)) {
result.missingDependencies.push(requiredTool);
result.isValid = false;
}
}
// Check session state prerequisites
for (const sessionReq of dependency.prerequisites.sessionState) {
const currentValue = this.getNestedProperty(sessionState, sessionReq.property);
if (currentValue !== sessionReq.value) {
result.missingPrerequisites.push({
type: 'session',
requirement: sessionReq.description,
current: currentValue,
expected: sessionReq.value,
howToFix: `Ensure ${sessionReq.property} is ${sessionReq.value}`
});
result.isValid = false;
}
}
// Check framework prerequisites
if (dependency.prerequisites.framework.length > 0) {
const currentFramework = sessionState?.framework;
if (!dependency.prerequisites.framework.includes(currentFramework)) {
result.missingPrerequisites.push({
type: 'framework',
requirement: `Framework must be one of: ${dependency.prerequisites.framework.join(', ')}`,
current: currentFramework,
expected: dependency.prerequisites.framework,
howToFix: `This tool only works with ${dependency.prerequisites.framework.join(' or ')} applications`
});
result.isValid = false;
}
}
// Check configuration prerequisites
for (const configReq of dependency.prerequisites.configuration) {
result.missingPrerequisites.push({
type: 'configuration',
requirement: configReq.description,
current: 'unknown',
expected: configReq.value,
howToFix: configReq.command || `Set ${configReq.setting} to ${configReq.value}`
});
}
// Add optional dependency recommendations
for (const optionalTool of dependency.dependencies.optional) {
if (!completedTools.includes(optionalTool)) {
result.recommendations.push(`Consider running ${optionalTool} first for better results`);
}
}
// Check for conflicting tools
for (const conflictingTool of dependency.dependencies.conflicting) {
if (completedTools.includes(conflictingTool)) {
result.warnings.push(`${conflictingTool} may conflict with ${toolName}`);
}
}
// Calculate estimated setup time
result.estimatedSetupTime = result.missingDependencies.length * 30 + // 30s per missing tool
result.missingPrerequisites.length * 60; // 60s per missing prerequisite
return result;
}
/**
* Get recommended workflow for a specific debugging goal
* Addresses: "Suggest logical tool sequences"
*/
getWorkflowForGoal(goal, framework) {
const workflows = this.getWorkflowTemplates();
const key = `${goal}_${framework || 'general'}`;
return workflows[key] || workflows[goal] || this.getDefaultWorkflow();
}
/**
* Generate tool usage documentation with dependencies
* Addresses: "Clear indication of which tools require others to work"
*/
generateToolDocumentation(toolName) {
const dependency = this.dependencies.get(toolName);
if (!dependency)
return null;
return {
overview: `${dependency.workflow.description} (${dependency.workflow.phase})`,
dependencies: {
required: dependency.dependencies.required.map(tool => ({
tool,
reason: this.getDependencyReason(toolName, tool)
})),
optional: dependency.dependencies.optional.map(tool => ({
tool,
benefit: this.getOptionalBenefit(toolName, tool)
})),
conflicting: dependency.dependencies.conflicting.map(tool => ({
tool,
reason: this.getConflictReason(toolName, tool)
}))
},
prerequisites: {
session: dependency.prerequisites.sessionState.map(req => ({
requirement: req.description,
howToCheck: `Check session.${req.property} === ${req.value}`,
howToFix: `Ensure ${req.property} is properly set to ${req.value}`
})),
framework: dependency.prerequisites.framework.map(fw => ({
framework: fw,
notes: `Tool is optimized for ${fw} applications`
})),
configuration: dependency.prerequisites.configuration.map(config => ({
setting: config.setting,
value: config.value,
command: config.command || `Set ${config.setting} = ${config.value}`,
why: config.description
}))
},
workflow: {
phase: dependency.workflow.phase,
beforeThis: dependency.dependencies.required,
afterThis: dependency.workflow.nextSuggestedTools,
timeToRun: dependency.workflow.estimatedTime
},
troubleshooting: dependency.commonIssues.map(issue => ({
problem: issue.issue,
likelyCause: issue.cause,
solution: issue.solution,
prevention: issue.preventionTip
}))
};
}
/**
* Initialize comprehensive tool dependencies based on user feedback
*/
initializeToolDependencies() {
// Flutter Enable Accessibility
this.dependencies.set('flutter_enable_accessibility', {
toolName: 'flutter_enable_accessibility',
dependencies: {
required: ['inject_debugging'],
optional: ['flutter_health_check'],
conflicting: []
},
prerequisites: {
sessionState: [
{ property: 'browserConnected', value: true, description: 'Browser connection must be active' },
{ property: 'framework', value: 'flutter', description: 'Flutter framework must be detected' }
],
framework: ['flutter'],
configuration: [
{
setting: 'flutter.engine.semanticsEnabled',
value: true,
description: 'Flutter semantics must be enabled',
command: 'flutter.engine.semanticsEnabled = true'
},
{
setting: 'semantics_widgets',
value: 'present',
description: 'App should use Semantics() widgets',
command: 'Add Semantics() widgets to your Flutter components'
}
]
},
workflow: {
phase: 'Flutter Setup',
description: 'Enable accessibility features required for Flutter UI analysis',
estimatedTime: 10000,
nextSuggestedTools: ['flutter_quantum_analyze', 'take_screenshot']
},
commonIssues: [
{
issue: 'Timeout after 30 seconds',
cause: 'Flutter app does not have semantics enabled or configured properly',
solution: 'Add flutter.engine.semanticsEnabled = true and use Semantics() widgets',
preventionTip: 'Always run flutter_health_check first to verify app configuration'
},
{
issue: 'Target page, context or browser has been closed',
cause: 'Browser connection lost during accessibility initialization',
solution: 'Restart debugging session and ensure browser stays open',
preventionTip: 'Keep browser tab active and avoid navigation during tool execution'
}
]
});
// Flutter Quantum Analyze
this.dependencies.set('flutter_quantum_analyze', {
toolName: 'flutter_quantum_analyze',
dependencies: {
required: ['inject_debugging', 'flutter_enable_accessibility'],
optional: ['flutter_health_check'],
conflicting: []
},
prerequisites: {
sessionState: [
{ property: 'accessibility.enabled', value: true, description: 'Accessibility must be enabled first' },
{ property: 'browserConnected', value: true, description: 'Browser connection must be active' }
],
framework: ['flutter'],
configuration: [
{
setting: 'semantics_tree',
value: 'available',
description: 'Semantics tree must be accessible',
command: 'Ensure flutter_enable_accessibility completed successfully'
}
]
},
workflow: {
phase: 'Flutter Analysis',
description: 'Initialize quantum debugging for advanced Flutter UI analysis',
estimatedTime: 8000,
nextSuggestedTools: ['flutter_quantum_interact', 'analyze_flutter_performance']
},
commonIssues: [
{
issue: 'Quantum debugging session not initialized',
cause: 'flutter_enable_accessibility was not run first or failed',
solution: 'Run flutter_enable_accessibility and ensure it succeeds before quantum analysis',
preventionTip: 'Always follow the Flutter debugging workflow: health check → accessibility → quantum'
}
]
});
// Inject Debugging (Base requirement)
this.dependencies.set('inject_debugging', {
toolName: 'inject_debugging',
dependencies: {
required: [],
optional: [],
conflicting: []
},
prerequisites: {
sessionState: [],
framework: [],
configuration: [
{
setting: 'application_running',
value: true,
description: 'Target application must be running and accessible',
command: 'Start your application server (e.g., flutter run -d web, npm start)'
}
]
},
workflow: {
phase: 'Session Creation',
description: 'Establish debugging connection to your application',
estimatedTime: 5000,
nextSuggestedTools: ['get_session_info', 'flutter_health_check', 'take_screenshot']
},
commonIssues: [
{
issue: 'Connection refused',
cause: 'Application is not running or not accessible at the specified URL',
solution: 'Start your application and verify it\'s accessible in a browser',
preventionTip: 'Always verify your app loads in a browser before starting debugging'
}
]
});
// Flutter Health Check
this.dependencies.set('flutter_health_check', {
toolName: 'flutter_health_check',
dependencies: {
required: ['inject_debugging'],
optional: [],
conflicting: []
},
prerequisites: {
sessionState: [
{ property: 'browserConnected', value: true, description: 'Browser connection must be active' }
],
framework: ['flutter'],
configuration: []
},
workflow: {
phase: 'Flutter Diagnosis',
description: 'Check Flutter app health and configuration before other tools',
estimatedTime: 3000,
nextSuggestedTools: ['flutter_enable_accessibility', 'take_screenshot']
},
commonIssues: []
});
// Python Backend Tools
this.dependencies.set('analyze_python_tests', {
toolName: 'analyze_python_tests',
dependencies: {
required: [],
optional: ['debug_python_imports'],
conflicting: []
},
prerequisites: {
sessionState: [],
framework: [],
configuration: [
{
setting: 'python_environment',
value: 'available',
description: 'Python interpreter and test files must be accessible',
command: 'Ensure Python is installed and test files exist'
}
]
},
workflow: {
phase: 'Python Testing Analysis',
description: 'Analyze Python test failures and structure',
estimatedTime: 15000,
nextSuggestedTools: ['validate_pydantic_models', 'debug_database_schema']
},
commonIssues: [
{
issue: 'Test file not found',
cause: 'Specified test file or directory does not exist',
solution: 'Verify the test file path and ensure it exists',
preventionTip: 'Use absolute paths or verify current working directory'
}
]
});
this.dependencies.set('validate_pydantic_models', {
toolName: 'validate_pydantic_models',
dependencies: {
required: [],
optional: ['analyze_python_tests'],
conflicting: []
},
prerequisites: {
sessionState: [],
framework: [],
configuration: [
{
setting: 'pydantic_installed',
value: true,
description: 'Pydantic library must be installed',
command: 'pip install pydantic'
}
]
},
workflow: {
phase: 'Data Validation Analysis',
description: 'Debug Pydantic model validation errors and schema conflicts',
estimatedTime: 10000,
nextSuggestedTools: ['debug_database_schema', 'analyze_api_integration']
},
commonIssues: [
{
issue: 'ValidationError in model parsing',
cause: 'Input data does not match model schema or field constraints',
solution: 'Check field types, required fields, and validation constraints',
preventionTip: 'Use Pydantic\'s parse_obj() method for debugging validation issues'
}
]
});
// Monitor Realtime (for active debugging)
this.dependencies.set('monitor_realtime', {
toolName: 'monitor_realtime',
dependencies: {
required: ['inject_debugging'],
optional: [],
conflicting: []
},
prerequisites: {
sessionState: [
{ property: 'browserConnected', value: true, description: 'Browser connection must be active' }
],
framework: [],
configuration: []
},
workflow: {
phase: 'Active Debugging',
description: 'Start real-time monitoring for debugging and issue reproduction',
estimatedTime: 2000,
nextSuggestedTools: ['simulate_user_action', 'take_screenshot']
},
commonIssues: []
});
// Simulate User Action (for reproduction)
this.dependencies.set('simulate_user_action', {
toolName: 'simulate_user_action',
dependencies: {
required: ['inject_debugging'],
optional: ['monitor_realtime'],
conflicting: []
},
prerequisites: {
sessionState: [
{ property: 'browserConnected', value: true, description: 'Browser connection must be active' }
],
framework: [],
configuration: []
},
workflow: {
phase: 'Issue Reproduction',
description: 'Simulate user interactions to reproduce issues and test fixes',
estimatedTime: 5000,
nextSuggestedTools: ['take_screenshot', 'get_console_logs']
},
commonIssues: [
{
issue: 'Element not found',
cause: 'Specified selector does not match any elements on the page',
solution: 'Verify the selector and ensure the element exists and is visible',
preventionTip: 'Use take_screenshot first to see current page state'
}
]
});
}
/**
* Get workflow templates for different debugging goals
*/
getWorkflowTemplates() {
return {
'flutter_ui_debugging': {
title: 'Flutter UI Debugging Workflow',
description: 'Complete workflow for debugging Flutter web applications',
steps: [
{
step: 1,
tool: 'inject_debugging',
purpose: 'Establish debugging connection',
estimatedTime: 5000,
prerequisites: ['Application running'],
validations: ['Browser connected', 'Session created']
},
{
step: 2,
tool: 'flutter_health_check',
purpose: 'Verify Flutter app configuration',
estimatedTime: 3000,
prerequisites: ['Debugging session active'],
validations: ['Flutter detected', 'App responsive']
},
{
step: 3,
tool: 'flutter_enable_accessibility',
purpose: 'Enable accessibility for UI analysis',
estimatedTime: 10000,
prerequisites: ['Flutter app has semantics enabled'],
validations: ['Accessibility tree available']
},
{
step: 4,
tool: 'flutter_quantum_analyze',
purpose: 'Initialize advanced UI analysis',
estimatedTime: 8000,
prerequisites: ['Accessibility enabled'],
validations: ['Quantum debugging active']
},
{
step: 5,
tool: 'take_screenshot',
purpose: 'Capture current UI state',
estimatedTime: 3000,
prerequisites: ['UI fully loaded'],
validations: ['Screenshot captured']
}
],
totalEstimatedTime: 29000,
alternatives: [
{
condition: 'If accessibility fails',
alternativeSteps: ['Check flutter.engine.semanticsEnabled', 'Add Semantics() widgets', 'Restart debugging session']
}
]
},
'python_backend_debugging': {
title: 'Python Backend Debugging Workflow',
description: 'Complete workflow for debugging Python backend applications',
steps: [
{
step: 1,
tool: 'analyze_python_tests',
purpose: 'Analyze test failures and structure',
estimatedTime: 15000,
prerequisites: ['Python environment available'],
validations: ['Test analysis complete']
},
{
step: 2,
tool: 'validate_pydantic_models',
purpose: 'Check data validation issues',
estimatedTime: 10000,
prerequisites: ['Pydantic models exist'],
validations: ['Model validation analyzed']
},
{
step: 3,
tool: 'debug_database_schema',
purpose: 'Analyze database-related issues',
estimatedTime: 12000,
prerequisites: ['Database schema files available'],
validations: ['Schema analysis complete']
},
{
step: 4,
tool: 'analyze_api_integration',
purpose: 'Debug API endpoint issues',
estimatedTime: 15000,
prerequisites: ['API code available'],
validations: ['API analysis complete']
}
],
totalEstimatedTime: 52000,
alternatives: [
{
condition: 'If module imports fail',
alternativeSteps: ['debug_python_imports', 'Fix import issues', 'Retry analysis']
}
]
},
'active_issue_reproduction': {
title: 'Active Issue Reproduction Workflow',
description: 'Workflow for reproducing and debugging specific issues',
steps: [
{
step: 1,
tool: 'inject_debugging',
purpose: 'Start debugging session',
estimatedTime: 5000,
prerequisites: ['Application running'],
validations: ['Session active']
},
{
step: 2,
tool: 'monitor_realtime',
purpose: 'Start real-time monitoring',
estimatedTime: 2000,
prerequisites: ['Session established'],
validations: ['Monitoring active']
},
{
step: 3,
tool: 'take_screenshot',
purpose: 'Capture initial state',
estimatedTime: 3000,
prerequisites: ['UI loaded'],
validations: ['Baseline captured']
},
{
step: 4,
tool: 'simulate_user_action',
purpose: 'Reproduce the issue',
estimatedTime: 5000,
prerequisites: ['Know reproduction steps'],
validations: ['Issue reproduced']
},
{
step: 5,
tool: 'take_screenshot',
purpose: 'Capture error state',
estimatedTime: 3000,
prerequisites: ['Issue occurred'],
validations: ['Error state documented']
},
{
step: 6,
tool: 'get_console_logs',
purpose: 'Collect error information',
estimatedTime: 2000,
prerequisites: ['Errors present'],
validations: ['Logs collected']
}
],
totalEstimatedTime: 20000,
alternatives: []
}
};
}
getDefaultWorkflow() {
return {
title: 'General Debugging Workflow',
description: 'Basic debugging workflow for any application',
steps: [
{
step: 1,
tool: 'inject_debugging',
purpose: 'Start debugging session',
estimatedTime: 5000,
prerequisites: ['Application accessible'],
validations: ['Session created']
}
],
totalEstimatedTime: 5000,
alternatives: []
};
}
getNestedProperty(obj, path) {
return path.split('.').reduce((current, key) => current?.[key], obj);
}
getDependencyReason(toolName, dependency) {
const reasons = {
'inject_debugging': 'Required to establish debugging session',
'flutter_enable_accessibility': 'Required for Flutter UI analysis and quantum debugging',
'flutter_health_check': 'Recommended to verify app configuration before other tools'
};
return reasons[dependency] || 'Required for proper tool operation';
}
getOptionalBenefit(toolName, optional) {
const benefits = {
'flutter_health_check': 'Provides valuable configuration information and issue prevention',
'monitor_realtime': 'Enables real-time monitoring during operations'
};
return benefits[optional] || 'Provides additional debugging information';
}
getConflictReason(toolName, conflicting) {
// Most tools don't conflict, but this would handle special cases
return `May interfere with ${toolName} operation`;
}
}
//# sourceMappingURL=tool-dependency-manager.js.map