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
528 lines • 24.6 kB
JavaScript
/**
* Clean Tool Discovery - AI-Optimized Tool Definitions
*
* SOLUTIONS IMPLEMENTED:
* 1. ✅ Remove tool duplication - keep only base tools (445 → ~44 unique)
* 2. ✅ Write specific, differentiated descriptions for each tool
* 3. ✅ Add context scoping for project-specific tools
* 4. ✅ Implement AI-discoverable usage guidance metadata
*/
const CLEAN_TOOLS = [
// CORE DEBUGGING TOOLS
{
name: 'inject_debugging',
description: 'Launch debugging session for web applications - starts browser automation and captures baseline state',
inputSchema: {
type: 'object',
properties: {
url: { type: 'string', description: 'URL to debug (required)' },
sessionId: { type: 'string', description: 'Optional session ID for tracking' },
framework: { type: 'string', description: 'Optional framework hint (react, vue, angular)' }
},
required: ['url']
},
contexts: ['web', 'spa', 'pwa'],
projectTypes: ['web'],
category: 'core',
complexity: 'basic',
usageGuidance: {
whenToUse: 'Start ANY debugging session for web applications. This is the entry point for all browser-based debugging.',
whenNotToUse: 'Do not use for API-only debugging, mobile apps, or desktop applications.',
commonMistakes: [
'Using for non-web applications',
'Calling without a valid URL',
'Not following up with specific debugging tools'
],
alternatives: [
'For APIs: use trace_api_calls',
'For mobile: use debug_flutter_app',
'For backends: use attach_to_process'
]
}
},
{
name: 'take_screenshot',
description: 'Capture visual state of web application - essential for documenting bugs and verifying fixes',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
selector: { type: 'string', description: 'CSS selector to focus on specific element' },
fullPage: { type: 'boolean', description: 'Capture entire page (default: viewport only)' }
},
required: ['sessionId']
},
contexts: ['web'],
projectTypes: ['web'],
category: 'core',
complexity: 'basic',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Document visual bugs, capture before/after states, verify UI changes, create visual regression tests.',
whenNotToUse: 'Do not use for API testing, performance analysis, or when no visual validation is needed.',
commonMistakes: [
'Taking screenshots before inject_debugging',
'Not specifying sessionId',
'Using for non-visual debugging tasks'
],
alternatives: [
'For performance: use analyze_performance',
'For accessibility: use run_audit',
'For console errors: use get_console_logs'
]
}
},
{
name: 'simulate_user_action',
description: 'Automate user interactions - click, type, scroll, submit forms to reproduce bugs or test workflows',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
action: { type: 'string', enum: ['click', 'type', 'scroll', 'hover', 'submit'] },
selector: { type: 'string', description: 'CSS selector for target element' },
value: { type: 'string', description: 'Text to type (for type action)' }
},
required: ['sessionId', 'action', 'selector']
},
contexts: ['web'],
projectTypes: ['web'],
category: 'core',
complexity: 'basic',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Reproduce user interactions that cause bugs, test form submissions, navigate through app workflows.',
whenNotToUse: 'Do not use for API testing, static analysis, or when no user interaction is needed.',
commonMistakes: [
'Using invalid CSS selectors',
'Not waiting for elements to load',
'Simulating actions without debugging session'
],
alternatives: [
'For form validation: use validate_forms',
'For accessibility testing: use run_audit',
'For performance testing: use analyze_performance'
]
}
},
{
name: 'monitor_realtime',
description: 'Watch for live changes in web application - network requests, DOM mutations, console logs, errors',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
duration: { type: 'number', description: 'Monitor duration in seconds (default: 30)' },
events: { type: 'array', items: { type: 'string' }, description: 'Event types to monitor' }
},
required: ['sessionId']
},
contexts: ['web', 'spa'],
projectTypes: ['web'],
category: 'core',
complexity: 'intermediate',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Debug real-time issues, monitor API calls, track state changes, investigate intermittent bugs.',
whenNotToUse: 'Do not use for static analysis, one-time screenshots, or when specific targeted debugging is better.',
commonMistakes: [
'Monitoring too long and getting overwhelmed with data',
'Not specifying which events to monitor',
'Using for simple issues that need targeted tools'
],
alternatives: [
'For specific network issues: use trace_network_requests',
'For performance: use analyze_performance',
'For errors: use get_console_logs'
]
}
},
// ANALYSIS TOOLS
{
name: 'run_audit',
description: 'Comprehensive quality analysis - performance, accessibility, SEO, best practices with actionable scores',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
categories: { type: 'array', items: { type: 'string' }, description: 'Audit categories to run' },
threshold: { type: 'number', description: 'Minimum score threshold (0-100)' }
},
required: ['sessionId']
},
contexts: ['web', 'spa', 'pwa'],
projectTypes: ['web'],
category: 'analysis',
complexity: 'intermediate',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Quality assurance, performance optimization, accessibility compliance, SEO validation, pre-deployment checks.',
whenNotToUse: 'Do not use for debugging specific functionality bugs or when you need targeted analysis.',
commonMistakes: [
'Running full audit for specific bug investigation',
'Not specifying which categories are relevant',
'Using for non-web applications'
],
alternatives: [
'For specific performance issues: use analyze_performance',
'For accessibility only: use check_accessibility',
'For debugging: use get_console_logs'
]
}
},
{
name: 'analyze_performance',
description: 'Detailed performance metrics - Core Web Vitals, bundle analysis, resource loading with optimization suggestions',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
metrics: { type: 'array', items: { type: 'string' }, description: 'Specific metrics to analyze' },
includeRecommendations: { type: 'boolean', description: 'Include optimization suggestions' }
},
required: ['sessionId']
},
contexts: ['web', 'spa', 'pwa'],
projectTypes: ['web'],
category: 'analysis',
complexity: 'advanced',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Optimize loading speed, investigate slow performance, meet Core Web Vitals requirements, analyze bundle size.',
whenNotToUse: 'Do not use for functional bugs, accessibility issues, or when performance is not the concern.',
commonMistakes: [
'Using for functionality debugging',
'Not loading the page properly before analysis',
'Confusing with run_audit which includes performance'
],
alternatives: [
'For comprehensive analysis: use run_audit',
'For accessibility: use check_accessibility',
'For functionality: use get_console_logs'
]
}
},
{
name: 'get_console_logs',
description: 'Extract JavaScript errors and console output - essential for debugging runtime issues and exceptions',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
level: { type: 'string', enum: ['error', 'warn', 'log', 'all'], description: 'Log level filter' },
since: { type: 'string', description: 'Get logs since timestamp' }
},
required: ['sessionId']
},
contexts: ['web', 'spa'],
projectTypes: ['web'],
category: 'analysis',
complexity: 'basic',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Debug JavaScript errors, investigate console warnings, understand runtime behavior, find error stack traces.',
whenNotToUse: 'Do not use for performance analysis, visual issues, or when errors are not console-related.',
commonMistakes: [
'Using for performance or visual debugging',
'Not filtering log levels appropriately',
'Looking for console logs before user interactions'
],
alternatives: [
'For visual issues: use take_screenshot',
'For performance: use analyze_performance',
'For network issues: use trace_network_requests'
]
}
},
// FRAMEWORK-SPECIFIC TOOLS
{
name: 'debug_react_state',
description: 'React DevTools integration - inspect component state, props, hooks, and re-render patterns',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
component: { type: 'string', description: 'Component name or selector to focus on' },
includeHooks: { type: 'boolean', description: 'Include hooks debugging' }
},
required: ['sessionId']
},
contexts: ['react', 'nextjs', 'gatsby'],
projectTypes: ['web'],
category: 'framework',
complexity: 'advanced',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Debug React component issues, inspect state problems, understand prop flow, optimize re-renders.',
whenNotToUse: 'Do not use for non-React applications, Vue components, or general JavaScript debugging.',
commonMistakes: [
'Using on non-React applications',
'Trying to debug before React DevTools are available',
'Using for general JavaScript errors'
],
alternatives: [
'For Vue: use debug_vue_state',
'For general JS: use get_console_logs',
'For Angular: use debug_angular_state'
]
}
},
{
name: 'debug_vue_state',
description: 'Vue DevTools integration - inspect component data, computed properties, events, and Vuex store',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
component: { type: 'string', description: 'Component name or selector to focus on' },
includeStore: { type: 'boolean', description: 'Include Vuex/Pinia store debugging' }
},
required: ['sessionId']
},
contexts: ['vue', 'nuxt'],
projectTypes: ['web'],
category: 'framework',
complexity: 'advanced',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Debug Vue component issues, inspect reactive data, understand event flow, debug Vuex store.',
whenNotToUse: 'Do not use for non-Vue applications, React components, or general JavaScript debugging.',
commonMistakes: [
'Using on non-Vue applications',
'Trying to debug before Vue DevTools are available',
'Using for general JavaScript errors'
],
alternatives: [
'For React: use debug_react_state',
'For general JS: use get_console_logs',
'For Angular: use debug_angular_state'
]
}
},
{
name: 'debug_flutter_app',
description: 'Flutter debugging - inspect widget tree, debug layout issues, monitor performance in Flutter web apps',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
widget: { type: 'string', description: 'Widget class name to focus on' },
includeLayout: { type: 'boolean', description: 'Include layout debugging' }
},
required: ['sessionId']
},
contexts: ['flutter'],
projectTypes: ['web', 'mobile'],
category: 'framework',
complexity: 'advanced',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Debug Flutter web applications, inspect widget trees, resolve layout issues, optimize Flutter performance.',
whenNotToUse: 'Do not use for native mobile Flutter (not web), other frameworks, or general web debugging.',
commonMistakes: [
'Using for native Flutter mobile apps',
'Using on non-Flutter applications',
'Trying to debug before Flutter tools are loaded'
],
alternatives: [
'For React: use debug_react_state',
'For Vue: use debug_vue_state',
'For general web: use get_console_logs'
]
}
},
// TESTING & TDD TOOLS
{
name: 'enable_tdd_mode',
description: 'Start Test-Driven Development session - runtime-bridged testing with automatic validation and coverage tracking',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
testFramework: { type: 'string', description: 'Testing framework (jest, vitest, cypress)' },
enableRuntimeBridging: { type: 'boolean', description: 'Enable runtime behavior validation' }
},
required: ['sessionId']
},
contexts: ['web', 'spa', 'api'],
projectTypes: ['web', 'api'],
category: 'testing',
complexity: 'advanced',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Start TDD workflows, validate tests against runtime behavior, ensure comprehensive test coverage.',
whenNotToUse: 'Do not use for debugging existing functionality or when tests are not the primary concern.',
commonMistakes: [
'Using for debugging instead of testing',
'Not specifying the correct test framework',
'Using without proper test setup'
],
alternatives: [
'For debugging: use get_console_logs',
'For analysis: use run_audit',
'For performance: use analyze_performance'
]
}
},
{
name: 'run_tests_with_coverage',
description: 'Execute test suite with coverage analysis - comprehensive validation with visual proof and impact analysis',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
testPattern: { type: 'string', description: 'Test file pattern to run' },
captureVisualProof: { type: 'boolean', description: 'Capture screenshots during tests' }
},
required: ['sessionId']
},
contexts: ['web', 'spa', 'api'],
projectTypes: ['web', 'api'],
category: 'testing',
complexity: 'intermediate',
prerequisites: ['enable_tdd_mode'],
usageGuidance: {
whenToUse: 'Validate code changes, ensure test coverage, run automated testing with coverage reporting.',
whenNotToUse: 'Do not use for debugging functionality issues or when tests are not ready.',
commonMistakes: [
'Running tests without enable_tdd_mode first',
'Using for debugging instead of testing',
'Not specifying appropriate test patterns'
],
alternatives: [
'For debugging: use get_console_logs',
'For setup: use enable_tdd_mode',
'For analysis: use run_audit'
]
}
},
// SPECIALIZED TOOLS
{
name: 'trace_network_requests',
description: 'Monitor HTTP requests and responses - track API calls, debug CORS issues, analyze request/response patterns',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
urlPattern: { type: 'string', description: 'URL pattern to filter requests' },
includeHeaders: { type: 'boolean', description: 'Include request/response headers' }
},
required: ['sessionId']
},
contexts: ['web', 'spa', 'api'],
projectTypes: ['web', 'api'],
category: 'specialized',
complexity: 'intermediate',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Debug API integration issues, investigate CORS problems, analyze network performance, monitor real-time requests.',
whenNotToUse: 'Do not use for frontend-only debugging, visual issues, or when network is not the concern.',
commonMistakes: [
'Using for frontend-only issues',
'Not filtering requests appropriately',
'Using when UI debugging is needed'
],
alternatives: [
'For UI issues: use take_screenshot',
'For console errors: use get_console_logs',
'For performance: use analyze_performance'
]
}
},
{
name: 'mock_network_responses',
description: 'Intercept and mock API responses - test error conditions, simulate slow networks, mock unavailable APIs',
inputSchema: {
type: 'object',
properties: {
sessionId: { type: 'string', description: 'Active debugging session ID' },
urlPattern: { type: 'string', description: 'URL pattern to mock' },
mockResponse: { type: 'object', description: 'Mock response data' },
delay: { type: 'number', description: 'Response delay in ms' }
},
required: ['sessionId', 'urlPattern', 'mockResponse']
},
contexts: ['web', 'spa', 'api'],
projectTypes: ['web'],
category: 'specialized',
complexity: 'advanced',
prerequisites: ['inject_debugging'],
usageGuidance: {
whenToUse: 'Test error handling, simulate API failures, test with different data, debug offline scenarios.',
whenNotToUse: 'Do not use for production debugging, when real API behavior is needed, or for non-network issues.',
commonMistakes: [
'Using in production environments',
'Mocking when real API testing is needed',
'Using for non-API related debugging'
],
alternatives: [
'For real API debugging: use trace_network_requests',
'For performance: use analyze_performance',
'For UI testing: use simulate_user_action'
]
}
},
// SUB-AGENT DELEGATION TOOLS
{
name: 'delegate_to_debug_agent',
description: 'Hand off complex debugging to specialized sub-agent - saves context, provides expert analysis and recommendations',
inputSchema: {
type: 'object',
properties: {
task: { type: 'string', description: 'Debugging task description' },
context: { type: 'object', description: 'Current debugging context' },
urgency: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Task urgency level' }
},
required: ['task']
},
contexts: ['any'],
projectTypes: ['web', 'mobile', 'api'],
category: 'specialized',
complexity: 'advanced',
usageGuidance: {
whenToUse: 'Complex debugging requiring expert analysis, when main conversation context should be preserved, multi-step debugging workflows.',
whenNotToUse: 'Do not use for simple debugging tasks, when direct tool usage is more appropriate, or for immediate results.',
commonMistakes: [
'Using for simple tasks that direct tools can handle',
'Not providing enough context for effective delegation',
'Using when immediate results are needed'
],
alternatives: [
'For simple debugging: use get_console_logs',
'For performance: use analyze_performance',
'For immediate results: use appropriate direct tool'
]
}
},
{
name: 'explain_sub_agent_usage',
description: 'Get comprehensive guide on sub-agent delegation - learn when and how to use AI Debug sub-agents effectively',
inputSchema: {
type: 'object',
properties: {
context: { type: 'string', description: 'Current debugging context for tailored guidance' },
includeExamples: { type: 'boolean', description: 'Include practical usage examples' }
}
},
contexts: ['any'],
projectTypes: ['any'],
category: 'specialized',
complexity: 'basic',
usageGuidance: {
whenToUse: 'Learn about sub-agent capabilities, understand delegation patterns, get context-specific guidance.',
whenNotToUse: 'Do not use when you need actual debugging - this is educational only.',
commonMistakes: [
'Using when actual debugging is needed',
'Expecting this to perform debugging tasks',
'Using repeatedly instead of learning the patterns'
],
alternatives: [
'For actual debugging: use delegate_to_debug_agent',
'For direct debugging: use appropriate debugging tools',
'For examples: use get_sub_agent_examples'
]
}
}
];
export { CLEAN_TOOLS };
//# sourceMappingURL=clean-tool-discovery.js.map