mcp-cisco-support

Instructions

Implementation Reference

• src/apis/bug-api.ts:1011-1233 (handler)

  Main handler function that orchestrates the comprehensive_analysis tool: resolves product names, performs multiple bug search strategies (progressive, product series, multi-severity), generates web search guidance, compiles recommendations.
  private async executeComprehensiveAnalysis(args: ToolArgs, meta?: { progressToken?: string }): Promise<BugApiResponse> { const productIdentifier = args.product_identifier as string; const softwareVersion = args.software_version as string; const analysisFocus = (args.analysis_focus as string) || 'comprehensive'; const includeWebSearchGuidance = (args.include_web_search_guidance as boolean) !== false; logger.info('Starting comprehensive analysis', { productIdentifier, softwareVersion, analysisFocus }); // Convert full product names to searchable terms for bug database let searchableProductTerm = productIdentifier; let productSeries = null; // Check if we can get the product series for this identifier productSeries = WebSearchHelper.getProductSeries(productIdentifier); if (productIdentifier.toLowerCase().includes('cisco') && productIdentifier.length > 20) { // This looks like a full product name, try to extract the series if (productIdentifier.toLowerCase().includes('4000 series') || productIdentifier.toLowerCase().includes('4431') || productIdentifier.toLowerCase().includes('4451')) { productSeries = 'Cisco 4000 Series Integrated Services Routers'; searchableProductTerm = 'ISR4431'; } else if (productIdentifier.toLowerCase().includes('catalyst 9200') || productIdentifier.toLowerCase().includes('9200 series')) { productSeries = 'Cisco Catalyst 9200 Series'; searchableProductTerm = 'C9200'; } else if (productIdentifier.toLowerCase().includes('asr 1000') || productIdentifier.toLowerCase().includes('1000 series')) { productSeries = 'Cisco ASR 1000 Series'; searchableProductTerm = 'ASR1000'; } else { // Extract model numbers or use keyword search approach const modelMatch = productIdentifier.match(/(\w+\d+)/); if (modelMatch) { searchableProductTerm = modelMatch[1]; } } logger.info('Processed product identifier', { original: productIdentifier, searchable: searchableProductTerm, productSeries: productSeries }); } const analysis = { product: productIdentifier, searchable_product_term: searchableProductTerm, version: softwareVersion, focus: analysisFocus, bug_analysis: null as any, product_resolution: null as any, web_search_guidance: null as any, recommendations: [] as string[], search_strategy_used: [] as string[] }; // Step 1: Product name resolution const { sendProgress } = await import('../mcp-server.js'); const totalSteps = 5; sendProgress(meta?.progressToken, 0, totalSteps); try { analysis.product_resolution = await WebSearchHelper.resolveProductName(productIdentifier); analysis.search_strategy_used.push('Product ID resolution via known mappings and patterns'); } catch (error) { logger.error('Product resolution failed', { error }); } // Step 2: Bug database analysis sendProgress(meta?.progressToken, 1, totalSteps); try { let searchQuery = searchableProductTerm; if (softwareVersion) { searchQuery += ` ${softwareVersion}`; } analysis.search_strategy_used.push('Progressive bug search with version normalization and product name conversion'); analysis.bug_analysis = await this.executeProgressiveSearch({ primary_search_term: searchableProductTerm, version: softwareVersion, severity_range: analysisFocus === 'security' ? 'high' : 'medium' }); // Add product series search if we have that information and a software version sendProgress(meta?.progressToken, 2, totalSteps); if (productSeries && softwareVersion) { analysis.search_strategy_used.push('Product series search with full product name and Cisco API version format'); try { // Convert version to Cisco API format (17.09.06 -> 17.9.6) const ciscoFormattedVersion = WebSearchHelper.formatVersionForCiscoAPI(softwareVersion); const productSeriesResult = await this.executeTool('search_bugs_by_product_series_affected', { product_series: productSeries, affected_releases: ciscoFormattedVersion }); if (productSeriesResult.bugs && analysis.bug_analysis.bugs) { const combinedBugs = [...analysis.bug_analysis.bugs, ...productSeriesResult.bugs]; const uniqueBugs = combinedBugs.filter((bug, index, self) => index === self.findIndex(b => b.bug_id === bug.bug_id) ); analysis.bug_analysis.bugs = uniqueBugs; analysis.bug_analysis.total_results = uniqueBugs.length; logger.info('Combined product series search results', { addedBugs: productSeriesResult.bugs.length, totalUnique: uniqueBugs.length }); } } catch (error) { logger.warn('Product series search failed', { productSeries, softwareVersion, error }); } } // Add multi-severity search for critical analysis sendProgress(meta?.progressToken, 3, totalSteps); if (analysisFocus === 'security' || analysisFocus === 'comprehensive') { analysis.search_strategy_used.push('Multi-severity search for complete coverage'); const multiSevResult = await this.executeMultiSeveritySearch({ search_term: searchQuery, search_type: 'keyword', max_severity: 3 }); // Combine results if (multiSevResult.bugs && analysis.bug_analysis.bugs) { const combinedBugs = [...analysis.bug_analysis.bugs, ...multiSevResult.bugs]; const uniqueBugs = combinedBugs.filter((bug, index, self) => index === self.findIndex(b => b.bug_id === bug.bug_id) ); analysis.bug_analysis.bugs = uniqueBugs; analysis.bug_analysis.total_results = uniqueBugs.length; } } } catch (error) { logger.error('Bug analysis failed in comprehensive analysis', { error }); analysis.bug_analysis = { error: error instanceof Error ? error.message : 'Unknown error' }; } // Step 3: Generate web search guidance sendProgress(meta?.progressToken, 4, totalSteps); if (includeWebSearchGuidance) { try { analysis.web_search_guidance = { lifecycle_queries: WebSearchHelper.generateLifecycleSearchQueries(productIdentifier, softwareVersion), product_info: analysis.product_resolution, recommended_searches: [] }; // Add context-specific web search guidance if (analysisFocus === 'incident_response') { const incidentStrategy = WebSearchHelper.generateIncidentSearchStrategy( productIdentifier, softwareVersion ); analysis.web_search_guidance.incident_strategy = incidentStrategy; } // Add general research recommendations analysis.web_search_guidance.recommended_searches = [ `"${productIdentifier}" release notes site:cisco.com`, `"${productIdentifier}" field notices site:cisco.com`, `"${productIdentifier}" security advisories site:cisco.com` ]; if (softwareVersion) { analysis.web_search_guidance.recommended_searches.push( `"${softwareVersion}" bugs fixes site:cisco.com`, `"${softwareVersion}" known issues site:cisco.com` ); } analysis.search_strategy_used.push('Web search guidance generation for external research'); } catch (error) { logger.error('Web search guidance generation failed', { error }); } } // Step 4: Generate recommendations based on findings if (analysis.bug_analysis && analysis.bug_analysis.bugs) { const bugCount = analysis.bug_analysis.bugs.length; const openBugs = analysis.bug_analysis.bugs.filter((b: any) => b.status === 'O').length; const criticalBugs = analysis.bug_analysis.bugs.filter((b: any) => ['1', '2'].includes(b.severity)).length; if (criticalBugs > 0) { analysis.recommendations.push(`⚠️ Found ${criticalBugs} critical/high severity bugs - review immediately`); } if (openBugs > 0) { analysis.recommendations.push(`📋 ${openBugs} open bugs found - check for workarounds and fixes`); } if (bugCount === 0) { analysis.recommendations.push('✅ No bugs found with current search criteria - consider broader search'); } // Product resolution recommendations if (analysis.product_resolution?.fullName) { analysis.recommendations.push(`🔗 Product resolved: ${analysis.product_resolution.fullName}`); if (analysis.product_resolution.modelUrl) { analysis.recommendations.push(`📖 Official documentation: ${analysis.product_resolution.modelUrl}`); } } // Web search recommendations if (includeWebSearchGuidance && analysis.web_search_guidance) { analysis.recommendations.push('🌐 Use provided web search queries for additional research'); analysis.recommendations.push('🔍 Check Cisco.com for latest field notices and security advisories'); } // Version-specific recommendations if (softwareVersion) { analysis.recommendations.push('📅 Verify end-of-life status using provided lifecycle search queries'); analysis.recommendations.push('⬆️ Review newer software versions for bug fixes and security updates'); } } // Return the analysis as a bug response with metadata return { bugs: analysis.bug_analysis?.bugs || [], total_results: analysis.bug_analysis?.bugs?.length || 0, page_index: 1, comprehensive_analysis: analysis }; }
• src/apis/bug-api.ts:535-562 (schema)

  Input schema and tool metadata definition for comprehensive_analysis in BugApi.getTools().
  name: 'comprehensive_analysis', title: 'Comprehensive Bug and Lifecycle Analysis', description: 'BEST FOR DETAILED ANALYSIS: Combines bug database search with web search guidance for EoL information. Provides complete product analysis including known issues, lifecycle status, and actionable recommendations. Ideal for failover issues, configuration problems, and product reliability concerns.', inputSchema: { type: 'object', properties: { product_identifier: { type: 'string', description: 'Product name, model, or ID to analyze (e.g., ISR4431/K9, Cisco ASR 1000)' }, software_version: { type: 'string', description: 'Software version to analyze (e.g., 17.09.06, 15.1(4)M)' }, analysis_focus: { type: 'string', description: 'Focus of the analysis', enum: ['security', 'stability', 'lifecycle', 'upgrade_planning', 'incident_response', 'comprehensive'], default: 'comprehensive' }, include_web_search_guidance: { type: 'boolean', description: 'Include web search queries and strategies for additional research', default: true } }, required: ['product_identifier'] }
• src/apis/index.ts:102-111 (registration)

  Instantiates BugApi and EnhancedAnalysisApi (which exposes comprehensive_analysis) in ApiRegistry for MCP tool registration.
  this.apis.set('bug', new BugApi()); this.apis.set('case', new CaseApi()); this.apis.set('eox', new EoxApi()); this.apis.set('psirt', new PsirtApi()); this.apis.set('product', new ProductApi()); this.apis.set('software', new SoftwareApi()); this.apis.set('serial', new SerialApi()); this.apis.set('rma', new RmaApi()); this.apis.set('enhanced_analysis', new EnhancedAnalysisApi()); this.apis.set('smart_bonding', new SmartBondingApi() as any); // Cast needed due to different base class
• src/apis/enhanced-analysis-api.ts:17-26 (registration)

  EnhancedAnalysisApi explicitly includes 'comprehensive_analysis' in its exposed tools list.
  const enhancedAnalysisToolNames = [ 'smart_search_strategy', 'progressive_bug_search', 'multi_severity_search', 'comprehensive_analysis', 'compare_software_versions', 'product_name_resolver' ]; return allBugTools.filter(tool => enhancedAnalysisToolNames.includes(tool.name));
• src/apis/bug-api.ts:813-907 (helper)

  Supporting helper method used by comprehensive_analysis for progressive bug searching with version/product variations.
  private async executeProgressiveSearch(args: ToolArgs, meta?: { progressToken?: string }): Promise<BugApiResponse> { const primaryTerm = args.primary_search_term as string; const version = args.version as string; const severityRange = (args.severity_range as string) || 'high'; const status = args.status as string; logger.info('Starting progressive search', { primaryTerm, version, severityRange }); // Send initial progress const { sendProgress } = await import('../mcp-server.js'); // Build search variations const searchVariations = []; // Try product ID approach first const productVariations = this.normalizeProductId(primaryTerm); for (const product of productVariations) { if (version) { const versionVariations = this.normalizeVersion(version); for (const v of versionVariations) { searchVariations.push({ type: 'keyword', args: { keyword: `${product} ${v}`, status } }); } } searchVariations.push({ type: 'product_id', args: { base_pid: product, status } }); searchVariations.push({ type: 'keyword', args: { keyword: product, status } }); } // Try searches with different severity levels based on range const severityLevels = severityRange === 'high' ? ['1', '2', '3'] : severityRange === 'medium' ? ['3', '4'] : ['1', '2', '3', '4', '5', '6']; const totalAttempts = searchVariations.length * severityLevels.length; let currentAttempt = 0; let bestResult: BugApiResponse = { bugs: [], total_results: 0, page_index: 1 }; sendProgress(meta?.progressToken, 0, totalAttempts); for (const variation of searchVariations) { for (const severity of severityLevels) { currentAttempt++; sendProgress(meta?.progressToken, currentAttempt, totalAttempts); try { const searchArgs = { ...variation.args, severity }; let result: BugApiResponse; if (variation.type === 'keyword') { result = await this.executeTool('search_bugs_by_keyword', searchArgs); } else { result = await this.executeTool('search_bugs_by_product_id', searchArgs); } if (result.bugs && result.bugs.length > bestResult.bugs!.length) { bestResult = result; logger.info('Found better result in progressive search', { variation: variation.type, args: searchArgs, resultCount: result.bugs.length }); } // If we found results, we can be less aggressive about continuing if (result.bugs && result.bugs.length >= 5) { break; } } catch (error) { logger.warn('Progressive search variation failed', { variation, severity, error: error instanceof Error ? error.message : error }); } } if (bestResult.bugs && bestResult.bugs.length >= 10) { // Send completion progress before breaking sendProgress(meta?.progressToken, totalAttempts, totalAttempts); break; // Good enough result found } } // Ensure final progress is sent sendProgress(meta?.progressToken, totalAttempts, totalAttempts); return bestResult;