mcp-cisco-support

# Cisco Support MCP Server - API Implementation Roadmap ## Overview This document outlines the implementation status and roadmap for the Cisco Support MCP Server's modular API architecture. The server is designed to support all 8 Cisco Support APIs through a configurable, extensible system. ## Architecture Overview ### Modular Design Benefits - **Scalability**: Each API is developed independently in its own module - **User Control**: Fine-grained control over which APIs are enabled - **Performance**: Smaller tool sets lead to faster initialization - **Security**: Only authorized APIs are exposed to users - **Maintainability**: Clean separation by API functionality - **Extensibility**: Easy to add new APIs following established patterns ### Project Structure ``` src/ ├── apis/ # Modular API implementations │ ├── base-api.ts # Common API functionality (auth, HTTP, validation) │ ├── bug-api.ts # Bug API v2.0 implementation (✅ COMPLETE) │ ├── case-api.ts # Case API v3.0 implementation (✅ COMPLETE) │ └── index.ts # API registry and configuration ├── utils/ # Shared utilities │ ├── auth.ts # OAuth2 authentication management │ ├── formatting.ts # Response formatting (Bug/Case/Generic) │ ├── logger.ts # Centralized logging │ └── validation.ts # Input validation and defaults └── mcp-server.ts # Main MCP server with modular API integration ``` ## Implementation Status Matrix | API | Status | Version | Tools | Priority | Notes | |-----|--------|---------|-------|----------|-------| | **Bug** | ✅ **COMPLETE** | v2.0 | 8 tools | Critical | Production ready with all endpoints | | **Case** | ✅ **COMPLETE** | v3.0 | 4 tools | High | Full Case Management API support | | **EoX** | ✅ **COMPLETE** | v1.7.0 | 4 tools | High | End of Life/Sale information | | **Product** | ✅ **COMPLETE** | v1.8.2 | 3 tools | High | Product details and specifications | | **Software** | ✅ **COMPLETE** | v1.8.5 | 6 tools | Medium | Software suggestions and recommendations | | **Serial** | 🔄 **PLANNED** | v1.0 | 0 tools | Medium | Serial number to product mapping | | **RMA** | 🔄 **PLANNED** | v1.0 | 0 tools | Medium | Return Merchandise Authorization | | **PSIRT** | ✅ **COMPLETE** | v1.8.1 | 8 tools | Medium | Product Security Incident Response Team vulnerability data | ### Implementation Summary - **✅ Implemented**: 6/8 APIs (75% complete) - **🔄 Planned**: 2/8 APIs (25% remaining) - **Total Tools Available**: 33 tools (8 Bug + 4 Case + 4 EoX + 8 PSIRT + 3 Product + 6 Software) - **Target Tools**: ~40-50 tools when all APIs implemented ## API Details ### ✅ Bug API (v2.0) - COMPLETE **Status**: Production Ready **Base URL**: `https://apix.cisco.com/bug/v2.0` **Tools**: 8 comprehensive bug search and retrieval tools **Implemented Tools**: 1. `get_bug_details` - Get details for up to 5 specific bug IDs 2. `search_bugs_by_keyword` - Search by keywords in descriptions/headlines 3. `search_bugs_by_product_id` - Search by base product ID (e.g., "C9200-24P") 4. `search_bugs_by_product_and_release` - Search by product ID + software releases 5. `search_bugs_by_product_series_affected` - Search by product series + affected releases 6. `search_bugs_by_product_series_fixed` - Search by product series + fixed releases 7. `search_bugs_by_product_name_affected` - Search by exact product name + affected releases 8. `search_bugs_by_product_name_fixed` - Search by exact product name + fixed releases **Key Features**: - ✅ Full OAuth2 authentication with automatic token refresh - ✅ Comprehensive parameter validation (single severity/status values) - ✅ Rich markdown formatting with clickable bug links - ✅ Pagination support (10 results per page) - ✅ Complete error handling with detailed messages - ✅ Integration with all existing prompts ### ✅ Case API (v3.0) - COMPLETE **Status**: Production Ready **Base URL**: `https://apix.cisco.com/case/v3` **Tools**: 4 comprehensive case management tools **Implemented Tools**: 1. `get_case_details` - Get detailed information for a specific case ID 2. `get_cases_by_case_ids` - Get brief information for multiple case IDs (up to 10) 3. `get_cases_by_contract_id` - Get cases associated with a specific contract ID 4. `get_cases_by_user_id` - Get cases associated with specific user ID(s) **Key Features**: - ✅ Full Case Management API v3.0 implementation - ✅ Pagination support for contract and user-based searches - ✅ Rich markdown formatting with clickable case links - ✅ Status and severity filtering capabilities - ✅ Comprehensive error handling - ✅ New Case Investigation prompt for guided workflows ### ✅ EoX API (v5.0) - COMPLETE **Status**: Production Ready **Base URL**: `https://apix.cisco.com/product-intelligence/v1/` **Tools**: 4 comprehensive End of Life/Sale information tools **Implemented Tools**: 1. `get_eox_by_product_id` - Get EoX information for specific product IDs 2. `get_eox_by_serial_number` - Get EoX information by device serial numbers 3. `get_eox_by_dates` - Get EoX announcements within date ranges 4. `get_eox_by_software_release` - Get EoX information for software releases **Key Features**: - ✅ Full EoX API v5.0 implementation with lifecycle planning - ✅ Multiple search methods (product ID, serial, date, software) - ✅ Rich formatting with clickable product links - ✅ Date-based filtering for lifecycle planning - ✅ Comprehensive error handling and validation ### ✅ PSIRT API (v2.0) - COMPLETE **Status**: Production Ready **Base URL**: `https://apix.cisco.com/security/advisories/v2` **Tools**: 8 comprehensive security vulnerability tools **Implemented Tools**: 1. `get_all_security_advisories` - Get all published security advisories with pagination 2. `get_security_advisory_by_id` - Get specific advisory by ID (cisco-sa-YYYYMMDD-xxxx) 3. `get_security_advisory_by_cve` - Get advisory by CVE identifier (CVE-YYYY-NNNN) 4. `get_security_advisories_by_severity` - Get advisories by severity (**text**: critical/high/medium/low/informational) 5. `get_security_advisory_by_bug_id` - Get advisory by Cisco bug ID 6. `get_latest_security_advisories` - Get the latest N security advisories 7. `get_security_advisories_by_year` - Get all advisories published in a specific year 8. `get_security_advisories_by_first_published` - Get advisories by publication date range **Key Features**: - ✅ Full PSIRT openVuln API v2.0 implementation - ✅ Multiple search methods (ID, CVE, severity, bug ID, date) - ✅ **Text-based severity levels** (critical, high, medium, low, informational) vs Bug API's numeric severity (1-6) - ✅ Rich formatting with clickable advisory links to Cisco Security Center - ✅ Pagination support for large result sets - ✅ Optional summary details and product name inclusion - ✅ Comprehensive security vulnerability management ### ✅ Product API (v1.0) - COMPLETE **Status**: Production Ready **Base URL**: `https://apix.cisco.com/product/v1/information` **Tools**: 3 comprehensive product information tools **Implemented Tools**: 1. `get_product_info_by_serial_numbers` - Get product details by device serial numbers (up to 5) 2. `get_product_info_by_product_ids` - Get product details by product identifiers/PIDs (up to 5) 3. `get_product_mdf_info_by_product_ids` - Get Manufacturing Data Format (MDF) information by product IDs (up to 5, hardware only) **Key Features**: - ✅ Full Product Information API v1.0 implementation - ✅ Multiple lookup methods (serial numbers, product IDs, MDF) - ✅ Batch processing support (up to 5 items per request) - ✅ Rich product details including specifications, pricing, lifecycle status - ✅ Manufacturing Data Format (MDF) support for hardware products - ✅ Direct links to Cisco product pages - ✅ Comprehensive technical specifications and orderable information - ✅ Pagination support for large result sets (up to 500 records per page for MDF) ### ✅ Software API (v2.0) - COMPLETE **Status**: Production Ready **Base URL**: `https://apix.cisco.com/software/suggestion/v2` **Tools**: 6 comprehensive software suggestion tools **Implemented Tools**: 1. `get_software_suggestions_by_product_ids` - Complete software suggestions including releases and images for Product IDs 2. `get_software_releases_by_product_ids` - Software releases only (no image details) for Product IDs 3. `get_compatible_software_by_product_id` - Compatible and suggested releases for specific Product ID with upgrade path support 4. `get_software_suggestions_by_mdf_ids` - Complete software suggestions including releases and images for MDF IDs 5. `get_software_releases_by_mdf_ids` - Software releases only (no image details) for MDF IDs 6. `get_compatible_software_by_mdf_id` - Compatible and suggested releases for specific MDF ID with upgrade path support **Key Features**: - ✅ Full Software Suggestion API v2.0 implementation - ✅ Multiple suggestion types (complete, releases-only, compatible upgrades) - ✅ Comprehensive software recommendations for upgrade planning - ✅ Release version tracking and recommendations - ✅ Software image details including download URLs - ✅ Direct links to Cisco software download portal - ✅ Pagination support for large result sets - ✅ Modern v2 API endpoints with enhanced functionality ## Configuration System ### Environment Variables ```bash # Single API SUPPORT_API=bug # Bug API only (default) SUPPORT_API=case # Case API only # Multiple APIs SUPPORT_API=bug,case # Bug and Case APIs SUPPORT_API=bug,case,eox # Bug, Case, and EoX APIs # All APIs (when implemented) SUPPORT_API=all # All available APIs ``` ### Configuration Examples **Development/Testing** (minimal footprint): ```bash SUPPORT_API=bug ``` **Support Engineer** (case management focus): ```bash SUPPORT_API=bug,case,rma ``` **Product Manager** (lifecycle management): ```bash SUPPORT_API=bug,eox,product,software ``` **Administrator** (full capabilities): ```bash SUPPORT_API=all ``` ## Next Implementation Priorities ### Phase 1: Core Support APIs (High Priority) #### 1. **EoX API** (End of Life/Sale) - Priority: HIGH - **Business Impact**: Critical for lifecycle management and planning - **Estimated Tools**: 6-8 tools - **Key Features**: Product lifecycle information, end-of-sale notifications - **Implementation Effort**: Medium (similar to Bug API complexity) #### 2. **Product API** (Product Information) - Priority: HIGH - **Business Impact**: Essential for product research and specifications - **Estimated Tools**: 4-6 tools - **Key Features**: Product details, family information, documentation links - **Implementation Effort**: Medium ### Phase 2: Operational APIs (Medium Priority) #### 3. **Serial API** (Serial Number Lookup) - Priority: MEDIUM - **Business Impact**: Important for asset tracking and warranty lookup - **Estimated Tools**: 3-4 tools - **Key Features**: Serial to product mapping, warranty information - **Implementation Effort**: Low-Medium #### 4. **Software API** (Software Suggestions) - Priority: MEDIUM - **Business Impact**: Valuable for software updates and recommendations - **Estimated Tools**: 4-5 tools - **Key Features**: Software recommendations, compatibility information - **Implementation Effort**: Medium ### Phase 3: Specialized APIs (Lower Priority) #### 5. **RMA API** (Return Merchandise Authorization) - Priority: MEDIUM - **Business Impact**: Support for return processes - **Estimated Tools**: 5-6 tools - **Key Features**: RMA creation, status tracking, authorization management - **Implementation Effort**: Medium-High #### 6. **PSIRT API** (Product Security Incident Response Team) - Priority: MEDIUM - **Business Impact**: Critical for security vulnerability management - **Estimated Tools**: 6-8 tools - **Key Features**: Security advisories, CVE searches, vulnerability severity filtering, product security notifications - **Implementation Effort**: Medium ## Implementation Framework Each new API implementation follows this established pattern: ### 1. API Module Creation (`src/apis/{api-name}-api.ts`) ```typescript export class {ApiName}Api extends BaseApi { protected baseUrl = 'https://apix.cisco.com/{api}/{version}'; protected apiName = '{ApiName}'; getTools(): Tool[] { /* API-specific tools */ } async executeTool(name: string, args: ToolArgs): Promise<ApiResponse> { /* Implementation */ } } ``` ### 2. Response Formatting (`src/utils/formatting.ts`) - Add API-specific response interfaces - Implement formatting functions for rich markdown output - Include hyperlinks to relevant Cisco portals ### 3. Registry Integration (`src/apis/index.ts`) - Register new API in the ApiRegistry - Add to SUPPORTED_APIS array - Update configuration examples ### 4. Testing Framework - Create comprehensive test suite following existing patterns - Add mock data for all endpoints - Include integration tests with real API validation ### 5. Documentation Updates - Update CLAUDE.md with new API capabilities - Add configuration examples - Document new tools and prompts ## Testing Strategy ### Current Test Coverage - **✅ Simple Tests**: 3/3 passing - Basic functionality validation - **✅ MCP Server Tests**: 17/17 passing - Server and prompt functionality - **✅ Bug API Tests**: 17/17 passing - All Bug API tools validated - **⚠️ Error Handling Tests**: Needs updates for modular structure - **✅ Integration Tests**: 7/7 passing with real API credentials ### Test Framework for New APIs 1. **Unit Tests**: Mock-based testing of all tools and edge cases 2. **Integration Tests**: Real API validation with live credentials 3. **Error Handling**: Comprehensive error scenario validation 4. **Schema Validation**: JSON Schema compliance for all tools 5. **Performance**: Response time and pagination testing ## Benefits of Modular Architecture ### For Users - **Reduced Tool Complexity**: Only relevant tools are exposed - **Faster Initialization**: Smaller tool sets load quicker - **Better Security**: Principle of least privilege - **Customizable Experience**: Choose exactly what you need ### For Developers - **Independent Development**: APIs can be implemented in parallel - **Easier Testing**: Isolated testing of individual APIs - **Better Maintainability**: Clear separation of concerns - **Code Reusability**: Common patterns across all APIs ### For Operations - **Scalable Deployment**: Deploy only needed functionality - **Resource Optimization**: Lower memory and network usage - **Monitoring**: API-specific metrics and logging - **Troubleshooting**: Isolated error tracking ## Version Compatibility ### Cisco API Versions Supported - **Bug API**: v2.0 (current, stable) - **Case API**: v3.0 (current, stable) - **Other APIs**: Latest stable versions when implemented ### MCP Protocol Compatibility - **MCP Version**: 2024-11-05 (latest) - **Transport**: Both stdio and HTTP/SSE supported - **Features**: Tools, prompts, ping, session management ## Future Enhancements ### Planned Features 1. **Cross-API Integration**: Link bugs to cases, cases to RMAs, etc. 2. **Advanced Filtering**: Multi-API searches and correlation 3. **Caching Layer**: Reduce API calls with intelligent caching 4. **Batch Operations**: Multi-tool execution for complex workflows 5. **Custom Prompts**: User-defined prompt templates 6. **Analytics**: Usage metrics and performance monitoring ### API Evolution - Monitor Cisco API updates and deprecations - Implement new endpoints as they become available - Maintain backward compatibility with configuration changes - Support multiple API versions when necessary ## Getting Started with New APIs ### For Contributors 1. Review existing Bug and Case API implementations 2. Follow the established patterns in `base-api.ts` 3. Create comprehensive tests following existing test structure 4. Update documentation and configuration examples 5. Submit PR with complete implementation ### For Users 1. Check API availability in Cisco Developer portal 2. Ensure proper access permissions in Cisco Services Access Manager 3. Update `SUPPORT_API` environment variable 4. Test with new tools and prompts 5. Provide feedback on functionality and usability --- *This roadmap is a living document that will be updated as APIs are implemented and requirements evolve.*