mcp-cisco-support

# MCP Enhancement Proposal for Cisco Support Server **Document Version:** 1.0 **Date:** 2025-10-23 **Current Project Version:** 1.11.3 **Author:** Claude AI **Status:** Proposed ## Executive Summary This document proposes implementing additional Model Context Protocol (MCP) features to enhance the Cisco Support MCP Server. The project currently implements **Tools**, **Prompts**, and **ElicitationRequest**, but lacks several powerful MCP capabilities that could significantly improve functionality and user experience. ## Current MCP Implementation Status ### ✅ Currently Implemented - **Tools** - 30+ tools across Bug, Product, Software, Serial, RMA, and PSIRT APIs - **Prompts** - 11 pre-built workflow prompts for common scenarios - **ElicitationRequest** - Dynamic user interaction for missing parameters - **Ping** - Basic connectivity testing ### ❌ Missing MCP Features 1. **Resources** - Expose structured data and artifacts 2. **Sampling** - Server-initiated LLM requests 3. **Roots** - File system and workspace context 4. **Progress Notifications** - Real-time operation updates 5. **Logging** - Structured MCP-compliant logging 6. **Cancellation** - Abort long-running operations --- ## Proposed Enhancements ### 1. Resources 🌟 **HIGH PRIORITY** #### What Are Resources? Resources in MCP are structured data or content that servers expose to clients. They represent semantic information like documents, database entries, system logs, or real-time data streams that LLMs can access for context. #### Use Cases for Cisco Support Server **A. Bug Report Resources** ``` cisco://bugs/{bug_id} cisco://bugs/recent?severity=1&days=7 cisco://bugs/product/{product_id}/summary ``` Benefits: - Direct access to bug reports as resources - Clients can reference bugs without tool calls - Enable drag-and-drop bug reports into conversations - Real-time bug data subscriptions **B. Product Information Resources** ``` cisco://products/{product_id}/specifications cisco://products/{product_id}/eol-status cisco://products/series/{series}/models ``` Benefits: - Quick product spec lookups - EoL dashboard data - Product comparison resources **C. Advisory and Security Resources** ``` cisco://security/advisories/{advisory_id} cisco://security/cve/{cve_id} cisco://security/psirt/recent ``` Benefits: - Real-time security advisory access - CVE database as resources - Security bulletin subscriptions **D. Cached Search Results** ``` cisco://cache/search/{search_id} cisco://cache/recent-queries ``` Benefits: - Faster access to frequently requested data - Reduced API calls - Historical search context #### Implementation Priority: **HIGH** **Effort:** Medium (2-3 days) **Impact:** High - Significantly improves user experience and reduces API calls --- ### 2. Sampling 🤖 **MEDIUM PRIORITY** #### What is Sampling? Sampling allows MCP servers to request LLM completions from the client, enabling servers to use AI capabilities without requiring their own API keys. #### Use Cases for Cisco Support Server **A. Intelligent Bug Categorization** ```typescript // Server requests LLM to categorize a bug report const category = await requestSampling({ messages: [{ role: "user", content: `Categorize this Cisco bug: ${bugDescription}` }], systemPrompt: "You are a Cisco bug categorization expert..." }); ``` **B. Smart Product Name Resolution** ```typescript // Resolve ambiguous product names const productId = await requestSampling({ messages: [{ role: "user", content: `What is the product ID for "Catalyst 9200 switch with 24 ports"?` }] }); ``` **C. Upgrade Risk Analysis** ```typescript // Analyze upgrade risks using AI const riskAssessment = await requestSampling({ messages: [{ role: "user", content: `Analyze upgrade risk from IOS-XE ${current} to ${target} given these bugs: ${bugList}` }] }); ``` **D. Natural Language Query Translation** ```typescript // Convert user questions to API queries const apiParams = await requestSampling({ messages: [{ role: "user", content: `Convert to Cisco Bug API parameters: "${userQuery}"` }] }); ``` #### Implementation Priority: **MEDIUM** **Effort:** Medium (2-3 days) **Impact:** Medium-High - Enables intelligent server-side processing --- ### 3. Roots 📁 **LOW PRIORITY** #### What are Roots? Roots allow servers to declare file system locations or workspace contexts they operate on, helping clients understand relevant directories and resources. #### Use Cases for Cisco Support Server **A. Configuration File Workspace** ```typescript roots: [ { uri: "file:///etc/cisco", name: "Cisco Configs" }, { uri: "file:///var/log/cisco", name: "Cisco Logs" } ] ``` **B. Report Output Directory** ```typescript roots: [ { uri: "file://~/cisco-reports", name: "Bug Reports" } ] ``` **C. Cache Directory** ```typescript roots: [ { uri: "file://~/.cache/cisco-mcp", name: "API Cache" } ] ``` #### Implementation Priority: **LOW** **Effort:** Low (1 day) **Impact:** Low - Nice to have, but not critical for current use cases --- ### 4. Progress Notifications 📊 **HIGH PRIORITY** #### What are Progress Notifications? Real-time updates about long-running operations, allowing clients to show progress bars and status updates to users. #### Use Cases for Cisco Support Server **A. Multi-Severity Search Progress** ```typescript // Searching severities 1, 2, 3... sendProgress({ progress: 0, total: 3, message: "Searching severity 1..." }); sendProgress({ progress: 1, total: 3, message: "Searching severity 2..." }); sendProgress({ progress: 2, total: 3, message: "Searching severity 3..." }); ``` **B. Bulk Product Analysis** ```typescript // Processing 100 product IDs sendProgress({ progress: 25, total: 100, message: "Analyzed 25 of 100 products..." }); ``` **C. Comprehensive Analysis** ```typescript // Multi-step analysis workflow sendProgress({ progress: 1, total: 5, message: "1/5: Searching bugs..." }); sendProgress({ progress: 2, total: 5, message: "2/5: Checking advisories..." }); sendProgress({ progress: 3, total: 5, message: "3/5: Analyzing CVEs..." }); sendProgress({ progress: 4, total: 5, message: "4/5: Reviewing EoL status..." }); sendProgress({ progress: 5, total: 5, message: "5/5: Generating report..." }); ``` #### Implementation Priority: **HIGH** **Effort:** Low-Medium (1-2 days) **Impact:** High - Greatly improves UX for slow operations --- ### 5. Logging 📝 **MEDIUM PRIORITY** #### What is MCP Logging? Structured logging notifications that clients can display, filter, and monitor, providing transparency into server operations. #### Use Cases for Cisco Support Server **A. API Call Logging** ```typescript logDebug("Calling Cisco Bug API: /bugs/keyword/memory+leak"); logInfo("Retrieved 45 bugs in 1.2s"); logWarning("Rate limit: 90% of quota used"); logError("API authentication failed, retrying..."); ``` **B. Search Strategy Logging** ```typescript logInfo("Selected search strategy: product_id_with_version"); logDebug("Normalized version: 17.09.06 -> 17.9.6"); logInfo("Fallback to keyword search due to no results"); ``` **C. Performance Logging** ```typescript logDebug("OAuth token cached, skipping refresh"); logInfo("Cache hit for product C9200-24P"); logWarning("Slow API response: 5.2s (threshold: 3s)"); ``` #### Implementation Priority: **MEDIUM** **Effort:** Low (1 day) **Impact:** Medium - Helpful for debugging and monitoring --- ### 6. Cancellation Support ⛔ **LOW PRIORITY** #### What is Cancellation? Ability to abort long-running operations when users navigate away or change their mind. #### Use Cases for Cisco Support Server **A. Multi-API Searches** ```typescript // User can cancel comprehensive analysis mid-execution if (isCancelled()) { return { cancelled: true, partial_results: currentResults }; } ``` **B. Bulk Operations** ```typescript // Cancel processing 1000 serial numbers for (const serial of serials) { if (isCancelled()) break; await processSerial(serial); } ``` #### Implementation Priority: **LOW** **Effort:** Medium (2 days) **Impact:** Low - Rare use case, but good for completeness --- ## Implementation Roadmap ### Phase 1: High-Impact Features (Week 1-2) 1. **Resources** - Bug reports, product info, security advisories 2. **Progress Notifications** - Multi-step operation tracking ### Phase 2: AI Enhancement (Week 3) 3. **Sampling** - Intelligent query processing and analysis ### Phase 3: Developer Experience (Week 4) 4. **Logging** - Structured MCP logging 5. **Roots** - Workspace context 6. **Cancellation** - Operation abort support --- ## Technical Implementation Details ### Resources Implementation ```typescript import { ListResourcesRequestSchema, ReadResourceRequestSchema, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js'; // Register resource handlers mcpServer.setRequestHandler(ListResourcesRequestSchema, async () => { return { resources: [ { uri: "cisco://bugs/recent", name: "Recent High-Severity Bugs", mimeType: "application/json" }, // ... more resources ] }; }); mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => { const { uri } = request.params; if (uri.startsWith('cisco://bugs/')) { const bugId = uri.replace('cisco://bugs/', ''); const bugData = await fetchBugDetails(bugId); return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(bugData, null, 2) }] }; } }); ``` ### Progress Notifications Implementation ```typescript import { ProgressNotificationSchema } from '@modelcontextprotocol/sdk/types.js'; async function multiSeveritySearch(params: any) { const severities = [1, 2, 3]; const results = []; for (let i = 0; i < severities.length; i++) { // Send progress notification mcpServer.notification({ method: "notifications/progress", params: { progress: i, total: severities.length, progressToken: params._meta?.progressToken } }); results.push(await searchBySeverity(severities[i])); } return results; } ``` ### Sampling Implementation ```typescript import { CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js'; async function intelligentProductResolution(query: string) { const result = await mcpServer.request( { method: "sampling/createMessage", params: { messages: [{ role: "user", content: { type: "text", text: `Extract Cisco product ID from: "${query}"` } }], systemPrompt: "You are a Cisco product expert...", maxTokens: 100 } }, CreateMessageRequestSchema ); return result.content.text; } ``` ### Logging Implementation ```typescript import { LoggingLevel } from '@modelcontextprotocol/sdk/types.js'; function sendMcpLog(level: LoggingLevel, message: string, data?: any) { mcpServer.notification({ method: "notifications/message", params: { level, logger: "cisco-support-mcp", data: message, ...(data && { extra: data }) } }); } // Usage sendMcpLog("info", "Bug search completed", { count: 45, duration: "1.2s" }); sendMcpLog("warning", "API rate limit approaching", { usage: "90%" }); ``` --- ## Benefits Summary | Feature | Effort | Impact | Priority | Key Benefit | |---------|--------|--------|----------|-------------| | Resources | Medium | High | **HIGH** | Faster access, reduced API calls | | Progress | Low-Med | High | **HIGH** | Better UX for slow operations | | Sampling | Medium | Med-High | **MEDIUM** | Intelligent server processing | | Logging | Low | Medium | **MEDIUM** | Better debugging/monitoring | | Roots | Low | Low | **LOW** | Workspace context | | Cancellation | Medium | Low | **LOW** | Operation control | --- ## Testing Strategy ### Resources Testing - Unit tests for resource handlers - Integration tests with MCP Inspector - Performance tests for large resources - Cache invalidation tests ### Progress Testing - Multi-step operation simulations - Progress token handling - Client progress display validation ### Sampling Testing - Mock LLM responses for unit tests - Real sampling integration tests - Token limit handling - Error recovery testing --- ## Documentation Requirements 1. Update CLAUDE.md with new features 2. Add resource URI documentation 3. Create sampling use case examples 4. Update MCP Inspector usage guide 5. Add progress notification examples 6. Document logging levels and categories --- ## Backward Compatibility All new features are **additive and optional**: - Existing tools and prompts continue to work - Clients not supporting new features gracefully degrade - No breaking changes to current API - Feature detection via capabilities negotiation --- ## Success Metrics 1. **Resources**: 50% reduction in repeated API calls 2. **Progress**: User feedback on long-running operations 3. **Sampling**: Enable 3+ new intelligent features 4. **Logging**: Improved debugging efficiency 5. **Overall**: Maintain 100% backward compatibility --- ## Conclusion Implementing these MCP enhancements will position the Cisco Support MCP Server as a **best-in-class** reference implementation, showcasing the full power of the Model Context Protocol while providing significant value to users through improved performance, user experience, and intelligent automation. **Recommended First Steps:** 1. ✅ Review and approve this proposal 2. 🏗️ Implement Resources (highest ROI) 3. 📊 Add Progress Notifications (best UX improvement) 4. 🤖 Experiment with Sampling (most innovative) --- ## References - [MCP Specification - Resources](https://modelcontextprotocol.io/specification/2025-03-26/server/resources) - [MCP Specification - Sampling](https://modelcontextprotocol.io/specification/2025-03-26/client/sampling) - [MCP Specification - Progress](https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/progress) - [Glama Blog - MCP Primitives](https://glama.ai/blog/2025-07-10-exploring-mcps-hidden-primitives-prompts-resources-sampling-and-roots) - [VS Code - Full MCP Support](https://code.visualstudio.com/blogs/2025/06/12/full-mcp-spec-support)