mcp-cisco-support

Instructions

Implementation Reference

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

  Primary handler function that executes the comprehensive_analysis tool. Orchestrates multiple internal tool calls (progressive_bug_search, multi_severity_search, product series searches), performs product name resolution, generates web search guidance for lifecycle info, and compiles recommendations based on findings.

  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:534-562 (schema)

  Input schema and metadata definition for the comprehensive_analysis tool within 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/enhanced-analysis-api.ts:17-26 (registration)

  EnhancedAnalysisApi explicitly registers comprehensive_analysis as one of its exposed tools by filtering from parent BugApi tools.

  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/index.ts:110-111 (registration)

  ApiRegistry instantiates EnhancedAnalysisApi, which exposes the comprehensive_analysis tool to the MCP server.

  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/bug-api.ts:708-709 (handler)

  Dispatch in BugApi.executeTool that routes comprehensive_analysis calls to the main handler method.

  case 'comprehensive_analysis':
    return this.executeComprehensiveAnalysis(processedArgs, meta);