mcp-cisco-support

Instructions

Implementation Reference

• src/apis/bug-api.ts:1235-1340 (handler)

  Main handler function that executes the tool logic: normalizes versions, performs multi-severity bug searches for both versions, computes differences (fixed, introduced, shared bugs), generates recommendations, and returns structured comparison results.
  private async executeCompareSoftwareVersions(args: ToolArgs, meta?: { progressToken?: string }): Promise<BugApiResponse> { const productId = args.product_id as string; const versionA = args.version_a as string; const versionB = args.version_b as string; const includeCveAnalysis = (args.include_cve_analysis as boolean) !== false; const includeEolStatus = (args.include_eol_status as boolean) !== false; const includeRecommendations = (args.include_recommendations as boolean) !== false; const maxSeverity = (args.max_severity as number) || 3; logger.info('Starting software version comparison', { productId, versionA, versionB, includeCveAnalysis, includeEolStatus, includeRecommendations, maxSeverity }); const comparison: any = { product_id: productId, version_a: versionA, version_b: versionB, analysis_timestamp: new Date().toISOString(), bug_comparison: null, cve_analysis: null, software_recommendations: null, eol_status: null, recommendations: [], summary: { version_a_issues: 0, version_b_issues: 0, shared_issues: 0, fixed_in_b: 0, introduced_in_b: 0, recommendation: null } }; const { sendProgress } = await import('../mcp-server.js'); const totalSteps = 6; try { // 1. Bug Analysis - Compare bugs between versions sendProgress(meta?.progressToken, 0, totalSteps); logger.info('Analyzing bugs for both versions'); const bugComparison = await this.compareBugsBetweenVersions(productId, versionA, versionB, maxSeverity); comparison.bug_comparison = bugComparison; // Update summary counts comparison.summary.version_a_issues = bugComparison.version_a_bugs?.length || 0; comparison.summary.version_b_issues = bugComparison.version_b_bugs?.length || 0; comparison.summary.shared_issues = bugComparison.shared_bugs?.length || 0; comparison.summary.fixed_in_b = bugComparison.fixed_in_version_b?.length || 0; comparison.summary.introduced_in_b = bugComparison.introduced_in_version_b?.length || 0; // 2. CVE Analysis (if requested) sendProgress(meta?.progressToken, 1, totalSteps); if (includeCveAnalysis) { logger.info('Analyzing CVEs and security advisories'); const cveAnalysis = await this.analyzeCvesBetweenVersions(productId, versionA, versionB); comparison.cve_analysis = cveAnalysis; } // 3. Software Recommendations (if requested and Software API available) sendProgress(meta?.progressToken, 2, totalSteps); if (includeRecommendations) { logger.info('Getting software recommendations'); const recommendations = await this.getSoftwareRecommendations(productId, versionA, versionB); comparison.software_recommendations = recommendations; } // 4. End-of-Life Status (if requested) sendProgress(meta?.progressToken, 3, totalSteps); if (includeEolStatus) { logger.info('Checking end-of-life status'); const eolStatus = await this.checkEolStatus(versionA, versionB); comparison.eol_status = eolStatus; } // 5. Generate Recommendations sendProgress(meta?.progressToken, 4, totalSteps); comparison.recommendations = this.generateVersionComparisonRecommendations(comparison); // 6. Determine overall recommendation sendProgress(meta?.progressToken, 5, totalSteps); comparison.summary.recommendation = this.determineOverallRecommendation(comparison); logger.info('Software version comparison completed successfully', { productId, versionA, versionB, bugDifferences: comparison.summary.fixed_in_b - comparison.summary.introduced_in_b, recommendation: comparison.summary.recommendation }); } catch (error) { logger.error('Error during software version comparison', { productId, versionA, versionB, error: error instanceof Error ? error.message : error }); comparison.error = `Software version comparison failed: ${error instanceof Error ? error.message : 'Unknown error'}`; comparison.recommendations.push('⚠️ Comparison failed - verify product ID and version formats'); } return { bugs: [], // No direct bugs in this response total_results: 1, page_index: 1, version_comparison: comparison }; }
• src/apis/bug-api.ts:564-607 (schema)

  Input schema definition for the tool, including required parameters (product_id, version_a, version_b) and optional flags for CVE analysis, EOL status, recommendations, and severity limit.
  { name: 'compare_software_versions', title: 'Compare Software Versions', description: 'Compare bugs, CVEs, and recommendations between two software versions on the same product. Analyzes differences in known issues, security vulnerabilities, and provides upgrade recommendations.', inputSchema: { type: 'object', properties: { product_id: { type: 'string', description: 'Product ID or series name (e.g., C9300-24P, ISR4431/K9, "Cisco 4000 Series Integrated Services Routers")' }, version_a: { type: 'string', description: 'First version to compare (e.g., 17.9.1, 15.1(4)M)' }, version_b: { type: 'string', description: 'Second version to compare (e.g., 17.12.3, 15.2(4)M)' }, include_cve_analysis: { type: 'boolean', description: 'Include CVE and security advisory analysis', default: true }, include_eol_status: { type: 'boolean', description: 'Include end-of-life status comparison', default: true }, include_recommendations: { type: 'boolean', description: 'Include software upgrade recommendations', default: true }, max_severity: { type: 'integer', description: 'Maximum bug severity level to include (1=highest, 6=lowest)', default: 3, minimum: 1, maximum: 6 } }, required: ['product_id', 'version_a', 'version_b'] }
• src/apis/enhanced-analysis-api.ts:13-27 (registration)

  Registers the tool by including it in the filtered list of exposed tools from BugApi in the EnhancedAnalysisApi.
  getTools(): Tool[] { // Get all tools from BugApi and filter to only enhanced analysis tools const allBugTools = super.getTools(); 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:100-110 (registration)

  Registers BugApi (containing the tool) and EnhancedAnalysisApi (exposing the tool) in the central ApiRegistry.
  private initializeApis(): void { // Initialize implemented APIs 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());
• src/apis/bug-api.ts:1384-1435 (helper)

  Key helper method that performs the core bug comparison between two versions by searching the bug database for each and categorizing bugs as shared, fixed, or newly introduced.
  private async compareBugsBetweenVersions(productId: string, versionA: string, versionB: string, maxSeverity: number): Promise<any> { try { // Normalize versions to Cisco API format const normalizedVersionA = this.normalizeVersionForComparison(versionA); const normalizedVersionB = this.normalizeVersionForComparison(versionB); // Search bugs for both versions const [bugsA, bugsB] = await Promise.all([ this.searchBugsForVersion(productId, normalizedVersionA, maxSeverity), this.searchBugsForVersion(productId, normalizedVersionB, maxSeverity) ]); // Analyze differences const versionABugIds = new Set(bugsA.bugs?.map((bug: any) => bug.bug_id) || []); const versionBBugIds = new Set(bugsB.bugs?.map((bug: any) => bug.bug_id) || []); // Find shared bugs const sharedBugIds = new Set([...versionABugIds].filter(id => versionBBugIds.has(id))); // Find bugs fixed in version B (present in A but not in B) const fixedInBIds = new Set([...versionABugIds].filter(id => !versionBBugIds.has(id))); // Find bugs introduced in version B (present in B but not in A) const introducedInBIds = new Set([...versionBBugIds].filter(id => !versionABugIds.has(id))); return { version_a_bugs: bugsA.bugs || [], version_b_bugs: bugsB.bugs || [], shared_bugs: (bugsA.bugs || []).filter((bug: any) => sharedBugIds.has(bug.bug_id)), fixed_in_version_b: (bugsA.bugs || []).filter((bug: any) => fixedInBIds.has(bug.bug_id)), introduced_in_version_b: (bugsB.bugs || []).filter((bug: any) => introducedInBIds.has(bug.bug_id)), analysis: { total_bugs_a: versionABugIds.size, total_bugs_b: versionBBugIds.size, shared_bugs: sharedBugIds.size, fixed_count: fixedInBIds.size, introduced_count: introducedInBIds.size, net_improvement: fixedInBIds.size - introducedInBIds.size } }; } catch (error) { logger.error('Bug comparison failed', { productId, versionA, versionB, error }); return { error: `Bug comparison failed: ${error instanceof Error ? error.message : 'Unknown error'}`, version_a_bugs: [], version_b_bugs: [], shared_bugs: [], fixed_in_version_b: [], introduced_in_version_b: [] }; } }