mcp-cisco-support

# Product Autocomplete Implementation - Option 2 ## Summary Implemented MCP Resources with user-provided cookies to access Cisco's internal product autocomplete API at `https://bst.cloudapps.cisco.com/api/productAutocomplete`. ## Implementation Date 2025-10-28 ## Solution Chosen **Option 2: MCP Resources with User-Provided Cookies** from [PRODUCT_AUTOCOMPLETE_SOLUTIONS.md](./PRODUCT_AUTOCOMPLETE_SOLUTIONS.md) This approach: - ✅ User controls their own authentication - ✅ Respects Cisco's security model - ✅ Works immediately with any valid session - ✅ No proxy or server infrastructure needed ## Changes Made ### 1. MCP Server Resources ([src/mcp-server.ts](../src/mcp-server.ts)) #### Resource Templates (Lines 630-646) Added new resource template for product autocomplete: ```typescript { uriTemplate: 'cisco://products/autocomplete/{search_term}', name: 'Cisco Product Autocomplete', description: 'Search Cisco product catalog by name or model (requires CISCO_WEB_COOKIE)', mimeType: 'application/json' } ``` #### Static Resources (Lines 693-709) Added help resource for setup instructions: ```typescript { uri: 'cisco://products/autocomplete-help', name: 'Product Autocomplete Setup', description: 'How to configure and use Cisco product autocomplete', mimeType: 'text/markdown' } ``` #### Resource Handlers (Lines 808-979) **Help Resource Handler (Lines 808-914)** - Returns comprehensive markdown documentation - Setup instructions with 5 steps - Cookie lifecycle information (24-hour validity) - Security best practices - Troubleshooting guide - Example responses **Autocomplete Resource Handler (Lines 915-979)** - Checks for `CISCO_WEB_COOKIE` environment variable - Fetches from Cisco's internal API with proper headers: - `Cookie`: User's session cookie - `User-Agent`: Mozilla browser UA string - `Referer`: https://bst.cloudapps.cisco.com/ - `Accept`: application/json - Handles authentication errors gracefully: - No cookie configured → setup instructions - 401/403 → cookie expired, refresh instructions - Other errors → network/API error messages - URL encodes search terms properly ### 2. Documentation Updates #### README.md Added new section: **"🔍 MCP Resources - Product Autocomplete"** - Available product resources - Setup instructions (4 steps) - Cookie lifecycle details - Example response - Security best practices - Usage examples for Claude Desktop - References to detailed documentation Updated Claude Desktop configuration section: - Added `CISCO_WEB_COOKIE` example - Changed default `SUPPORT_API` to include `product` - Added reference to product autocomplete section #### .env.example Added comprehensive documentation for `CISCO_WEB_COOKIE`: - Purpose and requirement - Cookie validity (24 hours) - Step-by-step extraction instructions - Security warnings - Example format ### 3. Testing Created validation test suite: [/private/tmp/test-autocomplete-resource.js](/private/tmp/test-autocomplete-resource.js) **Test Results: 7/7 Passed ✅** 1. Resource Templates Include Autocomplete ✅ 2. Static Resources Include Help ✅ 3. Resource Handler for Autocomplete ✅ 4. Resource Handler for Help ✅ 5. Error Handling - No Cookie ✅ 6. Error Handling - Expired Cookie ✅ 7. Security Considerations ✅ ## Environment Variable ### CISCO_WEB_COOKIE **Type**: Optional **Required For**: Product autocomplete MCP resources **Format**: Cookie header string **Example**: `"JSESSIONID=...; OptanonConsent=..."` **Validity**: ~24 hours **Security**: Treat like a password - never commit to git ## MCP Resource URIs ### Dynamic Resources (Templates) - `cisco://products/autocomplete/{search_term}` - Search Cisco product catalog - Returns product hierarchy, IDs, and names - Example: `cisco://products/autocomplete/4431` ### Static Resources - `cisco://products/autocomplete-help` - Setup and troubleshooting documentation - Markdown format - Includes cookie extraction guide ## API Details ### Cisco Product Autocomplete API **Endpoint**: `https://bst.cloudapps.cisco.com/api/productAutocomplete` **Query Parameter**: `productsearchTerm` **Authentication**: Cookie-based (browser session) **Method**: GET **Response Format**: JSON **Example Response**: ```json { "autoPopulateHMPProductDetails": [{ "parentMdfConceptId": 286281708, "parentMdfConceptName": "Cisco 4000 Series Integrated Services Routers", "mdfConceptId": 284358776, "mdfConceptName": "Cisco 4431 Integrated Services Router", "mdfMetaclass": "Model" }] } ``` ## Cookie Lifecycle Based on [CISCO_COOKIE_ANALYSIS.md](./CISCO_COOKIE_ANALYSIS.md): **Duration**: 24 hours (typical) **Type**: Session cookie (JSESSIONID + OptanonConsent) **Refresh Pattern**: Most likely "Sliding Window" - extends on activity **Absolute Max**: Up to 7 days with regular activity ### Signs of Expiration - HTTP 401 Unauthorized responses - HTTP 403 Forbidden responses - "Cookie expired or invalid" error messages - Empty results from API ### Refresh Process 1. Visit https://bst.cloudapps.cisco.com/ 2. If still logged in, extract cookie from DevTools 3. If logged out, log back in and extract new cookie 4. Update `CISCO_WEB_COOKIE` environment variable or MCP config ## Security Implementation ### Best Practices Implemented 1. ✅ Cookie stored in environment variable (not hardcoded) 2. ✅ User controls their own authentication 3. ✅ No server-side cookie storage or persistence 4. ✅ Clear documentation about security risks 5. ✅ Recommendation to use dedicated Cisco account 6. ✅ Warning to never commit cookies to git 7. ✅ Graceful error messages (no cookie exposure in logs) ### Cookie Validation ```typescript const webCookie = process.env.CISCO_WEB_COOKIE; if (!webCookie) { // Return helpful setup instructions } // Make API request with cookie const response = await fetch(url, { headers: { 'Cookie': webCookie } }); // Handle authentication errors if (response.status === 401 || response.status === 403) { // Return cookie expiration message with refresh instructions } ``` ## Usage Examples ### In Claude Desktop **Configuration** (`claude_desktop_config.json`): ```json { "mcpServers": { "cisco-support": { "command": "npx", "args": ["-y", "mcp-cisco-support"], "env": { "CISCO_CLIENT_ID": "your_id", "CISCO_CLIENT_SECRET": "your_secret", "SUPPORT_API": "bug,product", "CISCO_WEB_COOKIE": "JSESSIONID=...; OptanonConsent=..." } } } } ``` **Questions to Ask Claude**: - "Show me the help for product autocomplete" - "Search for Cisco product 4431 using autocomplete" - "What is the full name of product ISR4431?" - "Find products matching 'catalyst switch'" ### Via MCP Protocol ```typescript // List resource templates const templates = await mcpClient.request({ method: 'resources/templates/list', params: {} }); // Read help resource const help = await mcpClient.request({ method: 'resources/read', params: { uri: 'cisco://products/autocomplete-help' } }); // Search for product const results = await mcpClient.request({ method: 'resources/read', params: { uri: 'cisco://products/autocomplete/4431' } }); ``` ## Benefits Over Other Solutions Compared to other options from [PRODUCT_AUTOCOMPLETE_SOLUTIONS.md](./PRODUCT_AUTOCOMPLETE_SOLUTIONS.md): **vs Sampling-Based Resolution (Option 2)**: - ✅ More accurate (uses official Cisco API) - ✅ Faster (direct API call vs LLM) - ✅ No AI hallucinations - ⚠️ Requires manual cookie management **vs Static Product Mapping (Option 3)**: - ✅ Always up-to-date (live Cisco data) - ✅ No manual curation needed - ✅ Covers all products (not just common ones) - ⚠️ Requires user authentication **vs Proxy Service (Option 4)**: - ✅ No separate infrastructure - ✅ Simpler deployment - ✅ User controls auth - ⚠️ Manual cookie refresh **vs Hybrid Approach (Option 5)**: - ✅ Simpler implementation - ✅ Clear expectations - ⚠️ No fallback options ## Future Enhancements ### Short Term 1. Add cookie validation helper (check format before API call) 2. Add cookie age tracking (warn before expiration) 3. Implement caching for repeated lookups 4. Add metrics for API usage ### Medium Term 1. Implement Option 5 (Hybrid Approach) with fallback to static DB 2. Build community-sourced product mappings 3. Add browser extension for easy cookie extraction 4. Support multiple cookie formats (different Cisco sites) ### Long Term 1. Explore OAuth2 alternatives if Cisco provides them 2. Investigate headless browser automation for cookie refresh 3. Build static database from autocomplete API usage 4. Create desktop app for cookie management ## Related Documentation - [PRODUCT_AUTOCOMPLETE_SOLUTIONS.md](./PRODUCT_AUTOCOMPLETE_SOLUTIONS.md) - All 5 solution options analyzed - [CISCO_COOKIE_ANALYSIS.md](./CISCO_COOKIE_ANALYSIS.md) - Cookie lifecycle research - [ISR4431_SEARCH_ANALYSIS.md](./ISR4431_SEARCH_ANALYSIS.md) - Original problem that led to this solution ## Testing Build and test the implementation: ```bash # Build npm run build # Run validation tests node /private/tmp/test-autocomplete-resource.js # Test with real cookie (if available) export CISCO_WEB_COOKIE="your_cookie_here" export CISCO_CLIENT_ID="your_id" export CISCO_CLIENT_SECRET="your_secret" export SUPPORT_API="product" npx mcp-cisco-support --http # Query via MCP # (Use MCP client to read cisco://products/autocomplete/4431) ``` ## Deployment Checklist - [x] Implement resource templates in mcp-server.ts - [x] Implement static resources in mcp-server.ts - [x] Implement resource handlers with cookie validation - [x] Add comprehensive error handling - [x] Update README.md with new section - [x] Update .env.example with CISCO_WEB_COOKIE - [x] Create implementation documentation - [x] Build and verify TypeScript compilation - [x] Run validation tests - [ ] Test with real Cisco cookie - [ ] Update CHANGELOG.md - [ ] Commit changes - [ ] Create pull request / merge to main ## Conclusion Option 2 (MCP Resources with user-provided cookies) has been successfully implemented. The solution: 1. ✅ Respects Cisco's authentication model 2. ✅ Gives users full control over their credentials 3. ✅ Works immediately with any valid session 4. ✅ No additional infrastructure required 5. ✅ Comprehensive documentation and error handling 6. ✅ Security best practices implemented 7. ✅ Clear user guidance for setup and troubleshooting The implementation is production-ready pending real-world testing with actual Cisco cookies.