CLAUDE.md•42.1 kB
# Cisco Support MCP Server
A comprehensive TypeScript MCP (Model Context Protocol) server for Cisco Support APIs with both stdio and HTTP transport support. This extensible server currently provides access to Cisco's Bug Search API and is designed to support additional Cisco Support tools in the future.
## Project Overview
This TypeScript server features:
- **Dual Transport Support**: stdio (local MCP) and HTTP (remote server)
- **Extensible Architecture**: Designed to support multiple Cisco Support APIs
- **MCP Resources**: ✨ NEW - Expose Cisco data as structured resources
- **ElicitationRequest Support**: ⚠️ EXPERIMENTAL - Dynamic user interaction (limited client support)
- OAuth2 authentication with Cisco API (client credentials flow)
- 50+ MCP-compliant tools for comprehensive Cisco Support operations
- Real-time updates via Server-Sent Events (HTTP mode)
- TypeScript with full type safety and MCP SDK integration
- Docker containerization with multi-stage builds
- NPX support for easy local installation
- Security best practices
## Project Structure
```
mcp-cisco-support/
├── src/
│ └── index.ts # Main TypeScript server implementation
├── dist/ # Compiled JavaScript (generated by build)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── .env.example # Environment variables template
├── .env # Actual environment variables (create from example)
├── .gitignore # Git ignore rules
├── Dockerfile # Docker configuration
├── docker-compose.yml # Docker Compose setup
└── README.md # Project documentation
```
## Dependencies
Install these npm packages:
```json
{
"dependencies": {
"@modelcontextprotocol/sdk": "^1.12.1",
"express": "^4.18.2",
"cors": "^2.8.5",
"helmet": "^7.1.0",
"morgan": "^1.10.0",
"uuid": "^9.0.1",
"dotenv": "^16.3.1"
},
"devDependencies": {
"@types/cors": "^2.8.17",
"@types/express": "^4.17.21",
"@types/morgan": "^1.9.9",
"@types/node": "^20.10.0",
"@types/uuid": "^9.0.7",
"typescript": "^5.8.3",
"tsx": "^4.6.2"
}
}
```
## Quick Start
### Local MCP Server (stdio)
```bash
# Install globally via NPX
npx mcp-cisco-support
# Or install and run locally
npm install
npm run build
npm run stdio
```
### HTTP Server
```bash
# Development mode
npm run dev
# Production mode
npm run build
npm start
```
## MCP Client Configuration
### Using with Claude Desktop
Add this configuration to your Claude Desktop settings file:
**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**On Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"cisco-support": {
"command": "npx",
"args": ["-y", "mcp-cisco-support"],
"env": {
"CISCO_CLIENT_ID": "your_client_id_here",
"CISCO_CLIENT_SECRET": "your_client_secret_here",
"SUPPORT_API": "enhanced_analysis"
}
}
}
}
```
### API Configuration Options
Configure which tools are available using the `SUPPORT_API` environment variable:
- **`enhanced_analysis`** ⭐ **RECOMMENDED** - Only the 6 enhanced analysis tools (simplified deployment)
- **`sampling`** 🤖 **AI-POWERED** - 5 AI-powered tools using MCP sampling (requires client support)
- **`bug`** - All 14 Bug API tools (basic bug search capabilities)
- **`all`** - All stable APIs (bug, case, eox, product, serial, rma, software, psirt)
- ⚠️ **Note:** `all` does NOT include experimental features (`sampling`, `smart_bonding`, `enhanced_analysis`)
- To include experimental features, use: `all,sampling` or `all,smart_bonding`
- **`bug,case,psirt,sampling`** - Multiple specific APIs (custom combinations)
**Examples:**
- `SUPPORT_API=all` → 45 tools (all stable APIs)
- `SUPPORT_API=all,sampling` → 50 tools (stable + 5 AI-powered)
- `SUPPORT_API=bug,sampling` → 19 tools (bug + AI-powered)
### Example Usage
Once configured, you can ask Claude questions like:
- **Basic Bug Search**:
- "Search for recent bugs related to 'crash' in Cisco products"
- "Find open bugs with severity 1 or 2"
- "Show me bugs modified in the last 30 days"
- **Product-Specific Searches**:
- "Find bugs for product ID C9200-24P"
- "Search for bugs in Cisco Catalyst 9200 Series affecting release 17.5.1"
- "Show bugs fixed in software release 17.5.2"
- **Advanced Filtering**:
- "Find resolved bugs with severity 3 modified after 2023-01-01"
- "Search for bugs in 'Cisco ASR 9000 Series' sorted by severity"
- "Can you show me all the cisco bugs in the last 30 days for the product Cisco Unified Communications Manager (CallManager)?" (uses keyword search)
- "Find bugs for Cisco Unified Communications Manager affecting releases 14.0 and 15.0" (uses product series search)
- **Software Version Comparison** (🆕 NEW):
- "Compare software versions 17.9.1 and 17.12.3 for Cisco C9300-24P"
- "Analyze differences between IOS-XE 16.12.04 and 17.03.01 on ISR4431"
- "Should I upgrade from 15.1(4)M to 15.2(4)M on my ASR 1000?"
- "Compare bugs and CVEs between version 12.5(1)SU1 and 14.0(1)SU2 for CallManager"
- **AI-Powered Features** (🤖 NEW - Requires Sampling):
- "What's the product ID for a Catalyst 9200 24-port switch?" (natural language product resolution)
- "Analyze this bug description and categorize it" (intelligent bug categorization)
- "Give me an AI analysis of upgrade risks from 17.9.1 to 17.12.3" (upgrade risk assessment)
- "Summarize these bugs for my CallManager upgrade" (natural language bug summaries)
- "Parse this query: show me critical bugs for Catalyst 9200 running 17.9.1" (query extraction)
### Using with Other MCP Clients
For stdio transport:
```bash
mcp-cisco-support --stdio
```
For HTTP transport:
```bash
mcp-cisco-support --http
# Server will start on http://localhost:3000
```
### MCP Inspector v0.14.0+ Compatibility
This server fully supports MCP Inspector v0.14.0+ including:
- **Ping method**: Test connectivity and server responsiveness
- **Standard MCP protocol**: initialize, tools/list, tools/call
- **Both transports**: stdio for local inspection, HTTP for remote testing
To test with MCP Inspector:
1. Start the server: `mcp-cisco-support --stdio`
2. Connect MCP Inspector to the stdio transport
3. Use the ping feature to test connectivity
4. Explore available tools and test tool calls
## NPX Installation and Setup
### Publishing to NPM (for npx support)
1. Update package.json version and author information
2. Build the project: `npm run build`
3. Publish to NPM: `npm publish`
4. Install globally: `npm install -g mcp-cisco-support`
5. Use via npx: `npx mcp-cisco-support`
### Local NPX Setup (for development)
1. Build the project: `npm run build`
2. Link globally: `npm link`
3. Use via npx: `npx mcp-cisco-support`
## Transport Modes
### stdio Transport (Default)
- **Use case**: Local MCP clients (Claude Desktop, etc.)
- **Protocol**: JSON-RPC over stdio
- **Command**: `mcp-cisco-support` or `mcp-cisco-support --stdio`
- **Benefits**: Direct integration with MCP clients, no network overhead
### HTTP Transport
- **Use case**: Remote server, web applications, SSE clients
- **Protocol**: JSON-RPC over HTTP + Server-Sent Events
- **Command**: `mcp-cisco-support --http`
- **Port**: 3000 (configurable via PORT env var)
- **Endpoints**:
- `POST /mcp` - MCP JSON-RPC endpoint (supports ping method)
- `GET /ping` - Simple ping endpoint for connectivity testing
- `GET /sse` - Server-Sent Events stream
- `GET /health` - Health check
- `GET /` - Server information
## Build Commands
```bash
# Install dependencies
npm install
# Build TypeScript to JavaScript
npm run build
# Development with hot reload
npm run dev
# Run in stdio mode (default)
npm run stdio
# or
npm start
# Run in HTTP mode
npm start -- --http
# Type checking
npx tsc --noEmit
# Test ping functionality (HTTP mode)
curl http://localhost:3000/ping
# Test MCP ping via JSON-RPC (HTTP mode)
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
# GitHub Actions monitoring
npm run actions:status # Check latest build status
npm run actions:list # List recent workflow runs
npm run actions:watch # Watch current run in real-time
npm run actions:logs # View logs of latest run
```
## Environment Variables
Create `.env.example` and `.env` files with:
```bash
# Cisco API OAuth2 Configuration
CISCO_CLIENT_ID=your_client_id_here
CISCO_CLIENT_SECRET=your_client_secret_here
# Server Configuration
PORT=3000
NODE_ENV=development
```
## API Endpoints
The server implements these Cisco Bug API v2.0 endpoints:
### Authentication
- **OAuth2 URL**: `https://id.cisco.com/oauth2/default/v1/token`
- **Grant Type**: `client_credentials`
- **Token Validity**: 12 hours
- **Auto-refresh**: 30 minutes before expiry
### Bug API Base URL
- **Base URL**: `https://apix.cisco.com/bug/v2.0`
## MCP Tools Implemented
### Bug Search Tools (8 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
### Enhanced Analysis Tools (5 tools)
9. **smart_search_strategy** - Analyzes search queries and suggests optimal search approaches
10. **progressive_bug_search** - Automatically tries multiple search strategies with version normalization
11. **multi_severity_search** - Searches multiple severity levels and combines results
12. **comprehensive_analysis** - Combines bug database search with web search guidance for complete analysis
13. **compare_software_versions** - 🆕 **NEW**: Compare bugs, CVEs, and recommendations between two software versions
14. **product_name_resolver** - Resolves product IDs to full product names with search strategies
**IMPORTANT Parameter Limitations (v1.9.5+)**:
- **Severity**: Returns ONLY the specified level (severity=3 returns only severity 3 bugs, not 1-3)
- **Status**: Only accepts single values (`"O"`) not comma-separated (`"O,F"`)
- **Multi-severity searches**: Use multi_severity_search tool for "severity 3 or higher" type queries
- For multiple status values, make separate API calls
## Server Endpoints
- `GET /` - Server info and available endpoints
- `GET /api/mcp/tools` - List all available MCP tools
- `POST /api/mcp/call` - Execute MCP tool calls
- `GET /api/sse` - Server-Sent Events endpoint for real-time updates
- `GET /health` - Health check endpoint
## Key Features
### MCP Sampling 🤖 NEW (v1.14.0+)
- **AI-Powered Intelligence**: Leverage LLM capabilities without server-side API keys
- **Natural Language Processing**: Convert friendly product names to technical IDs
- **Intelligent Analysis**: AI-driven bug categorization and risk assessment
- **Smart Summaries**: Generate human-readable summaries from technical data
- **Query Parsing**: Extract structured parameters from conversational queries
#### Sampling Requirements
- **Client Support**: Requires MCP client with sampling capability (SDK v1.20.2+)
- **Protocol**: MCP 2025-06-18 specification
- **Configuration**: Set `SUPPORT_API=sampling` or include in comma-separated list
- **Human-in-Loop**: Clients should provide approval UI for sampling requests
#### Available Sampling Tools (5 tools)
**1. resolve_product_name** 🔍
- Converts natural language product descriptions to Cisco product IDs
- Example: "Catalyst 9200 24-port switch" → "C9200-24P"
- Use case: When users describe products conversationally
**2. categorize_bug** 🏷️
- AI analysis of bug descriptions
- Returns: severity, impact, and functional category
- Use case: Quick triage of unfamiliar bugs
**3. analyze_upgrade_risk_with_ai** ⚠️
- Comprehensive upgrade risk analysis using AI
- Analyzes bug data between versions
- Provides detailed recommendations and precautions
**4. summarize_bugs_with_ai** 📊
- Generate natural language summaries of bug lists
- Highlights critical issues and patterns
- Use case: Executive summaries and reports
**5. extract_product_query** 🔎
- Parse natural language queries into structured search parameters
- Extracts product IDs, versions, severity, status, keywords
- Use case: Conversational bug searches
#### How Sampling Works
```typescript
// Client declares sampling capability during initialization
{
"capabilities": {
"sampling": {}
}
}
// Server requests LLM completion
const analysis = await server.createMessage({
messages: [{
role: 'user',
content: { type: 'text', text: 'Analyze this bug...' }
}],
systemPrompt: 'You are a Cisco bug analysis expert',
maxTokens: 500,
modelPreferences: {
intelligencePriority: 0.8,
speedPriority: 0.6,
costPriority: 0.5
}
});
```
#### Model Preferences
Sampling uses an abstraction layer instead of specific model names:
- **intelligencePriority** (0.0-1.0): How important are advanced capabilities
- **speedPriority** (0.0-1.0): How important is low latency
- **costPriority** (0.0-1.0): How important is minimizing cost
- **hints**: Optional model name suggestions (treated as flexible substrings)
#### Security Considerations
- ✅ **Human Approval**: Clients should show sampling requests for user review
- ✅ **No Server Keys**: Server never needs LLM API keys
- ✅ **Client Control**: Client maintains full control over model access
- ✅ **Audit Trail**: All sampling requests logged for transparency
#### Enabling Sampling
**In Claude Desktop config:**
```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,sampling"
}
}
}
}
```
**Fallback Behavior:**
If client doesn't support sampling, tools return helpful error messages explaining:
- What sampling is
- How to enable it
- Alternative non-AI tools to use
### MCP Resources ✨ NEW
- **Structured Data Access**: Expose Cisco data as MCP resources for direct client access
- **Reduced API Calls**: Clients can reference data without repeated tool calls
- **Real-time Information**: Always-fresh data from Cisco APIs
- **URI-based Access**: Simple `cisco://` URI scheme for all resources
#### Available Resource URIs
**Bug Resources** (requires `SUPPORT_API=bug` or `all`):
- `cisco://bugs/recent/critical` - Critical bugs (severity 1-2) from last 7 days
- `cisco://bugs/recent/high` - High-severity bugs (severity 1-3) from last 30 days
- `cisco://bugs/{bug_id}` - Specific bug details (e.g., `cisco://bugs/CSCvi12345`)
**Product Resources** (requires `SUPPORT_API=product` or `all`):
- `cisco://products/catalog` - Product catalog information
- `cisco://products/{product_id}` - Product details (e.g., `cisco://products/C9300-24P`)
**Security Resources** (requires `SUPPORT_API=psirt` or `all`):
- `cisco://security/advisories/recent` - Latest 20 security advisories
- `cisco://security/advisories/critical` - Critical severity advisories
- `cisco://security/advisories/{advisory_id}` - Specific advisory (e.g., `cisco://security/advisories/cisco-sa-20180221-ucdm`)
- `cisco://security/cve/{cve_id}` - Advisory by CVE (e.g., `cisco://security/cve/CVE-2018-0101`)
#### Resource Templates
The server uses **resource templates** to advertise dynamic URI patterns. Instead of listing every possible bug or product, templates show which URI patterns are supported:
```typescript
resourceTemplates: [
{
uriTemplate: "cisco://bugs/{bug_id}",
name: "Cisco Bug Report",
description: "Access any Cisco bug by its ID (e.g., CSCvi12345)"
},
{
uriTemplate: "cisco://products/{product_id}",
name: "Cisco Product Information",
description: "Get product details by product ID (e.g., C9300-24P, ISR4431)"
},
{
uriTemplate: "cisco://security/advisories/{advisory_id}",
name: "Cisco Security Advisory",
description: "Get security advisory by ID (e.g., cisco-sa-20180221-ucdm)"
},
{
uriTemplate: "cisco://security/cve/{cve_id}",
name: "Security Advisory by CVE",
description: "Get security advisory by CVE identifier (e.g., CVE-2018-0101)"
}
]
```
This tells MCP clients: "I can handle ANY bug ID, product ID, advisory ID, or CVE in these patterns" without enumerating every possibility.
#### Resource Usage Example
```typescript
// List static resources
const { resources } = await mcpServer.request({
method: 'resources/list',
params: {}
});
// List resource templates (separate endpoint per MCP spec)
const { resourceTemplates } = await mcpServer.request({
method: 'resources/templates/list',
params: {}
});
// Read a specific resource using a template pattern
const bugData = await mcpServer.request({
method: 'resources/read',
params: { uri: 'cisco://bugs/CSCvi12345' }
});
// Read a product using a template pattern
const productData = await mcpServer.request({
method: 'resources/read',
params: { uri: 'cisco://products/C9300-24P' }
});
// Read a CVE using a template pattern
const cveData = await mcpServer.request({
method: 'resources/read',
params: { uri: 'cisco://security/cve/CVE-2018-0101' }
});
```
### ElicitationRequest Support ⚠️ EXPERIMENTAL
- **Dynamic User Interaction**: Request missing parameters from users at runtime
- **Predefined Schemas**: Ready-to-use schemas for common Cisco Support scenarios
- **Security-First Design**: Never requests sensitive information like credentials
- **Interactive Workflows**: Enable complex multi-step processes requiring user input
- **Limited Client Support**: Few MCP clients currently implement this feature
**Current Status (January 2025):**
- ❌ **Limited Client Support**: No major MCP clients (including Claude Desktop) have confirmed full ElicitationRequest implementation
- ✅ **Spec Compliant**: Code follows MCP specification (2025-06-18)
- ✅ **Alternative Available**: Claude Desktop handles missing parameters through natural conversational follow-up questions
**What Is ElicitationRequest?**
- Part of MCP spec for requesting user input at runtime
- Allows servers to pause and ask for missing parameters
- Uses structured schemas (flat objects with primitives only)
**Why Keep It?**
- Future client support (when available)
- Custom MCP client implementations
- HTTP mode with custom UI
- Reference implementation
**Available Elicitation Schemas** (for future use):
- **`apiCredentials`**: Request API credentials (with user confirmation)
- **`searchRefinement`**: Request search parameter refinement (severity, status, date range)
- **`userConfirmation`**: Request user confirmation for actions
- **`productSelection`**: Request product selection from multiple options
**Usage Example** (for custom clients):
```typescript
import { createElicitationRequest, ElicitationSchemas } from './mcp-server.js';
// Request search refinement (when client supports elicitation)
const request = createElicitationRequest(
'Please refine your search parameters for better results',
ElicitationSchemas.searchRefinement
);
```
**For Claude Desktop Users:**
Claude handles this naturally through conversation:
```
User: "Find bugs for ISR4431"
Claude: "I'll search for bugs on the ISR4431. Would you like me to focus on
high/critical severity, or search all levels? Also, should I check
any specific software version?"
```
This conversational approach works better than rigid schemas and is already supported.
### OAuth2 Authentication
- Automatic token management with refresh
- Handle 401 responses by refreshing token
- Store token and expiry in memory
### Error Handling
- Comprehensive error handling for network issues
- Timeout handling (30 seconds)
- Proper HTTP status codes
- Detailed logging
### Server-Sent Events
- Real-time updates for tool execution
- Connection management
- Heartbeat messages every 30 seconds
- Graceful disconnect handling
### Security
- Helmet for security headers
- CORS enabled
- Input validation
- Environment variable protection
## Docker Configuration
### Dockerfile Requirements
- Multi-stage TypeScript build with Node.js 18-alpine
- Non-root user execution for security
- Health checks and proper monitoring
- Multi-platform support (linux/amd64, linux/arm64)
- Build optimization with layer caching
- Proper file permissions and labels
### Docker Compose
- Health checks and monitoring
- Environment variables configuration
- Volume mounts for logs
- Network configuration
- Restart policies
### GitHub Container Registry
Automated Docker builds are available via GitHub Actions:
- **Latest**: `ghcr.io/sieteunoseis/mcp-cisco-support:latest`
- **Tagged**: `ghcr.io/sieteunoseis/mcp-cisco-support:v1.0.0`
- **Branch**: `ghcr.io/sieteunoseis/mcp-cisco-support:main-abc123`
Pull and run the pre-built image:
```bash
docker pull ghcr.io/sieteunoseis/mcp-cisco-support:latest
docker run -d -p 3000:3000 \
-e CISCO_CLIENT_ID=your_id \
-e CISCO_CLIENT_SECRET=your_secret \
ghcr.io/sieteunoseis/mcp-cisco-support:latest --http
```
## CI/CD Workflows
### GitHub Actions
The project includes automated workflows for:
#### Docker Build (`docker-build.yml`)
- **Triggers**: Push to main/master, manual dispatch
- **Multi-platform**: Builds for linux/amd64 and linux/arm64
- **Registry**: Pushes to GitHub Container Registry (ghcr.io)
- **Caching**: Uses GitHub Actions cache for faster builds
- **Security**: Includes build provenance attestation
- **Tagging**: Automatic versioning and latest tags
#### NPM Publish (`npm-publish.yml`)
- **Triggers**: GitHub releases, manual dispatch with dry-run option
- **Features**: TypeScript compilation, version management, provenance
- **Registry**: Publishes to NPM registry
- **Security**: Uses NPM provenance for supply chain security
### Setup Requirements
To enable the workflows, configure these repository secrets:
- `NPM_TOKEN`: NPM authentication token for publishing
- `GITHUB_TOKEN`: Automatically provided by GitHub
### Manual Workflow Dispatch
Both workflows can be triggered manually:
- **Docker Build**: With optional custom tag suffix
- **NPM Publish**: With dry-run option for testing
### Monitoring GitHub Actions
Use these npm scripts to monitor workflow runs:
```bash
# Quick status check
npm run actions:status
# List recent workflow runs
npm run actions:list
# Watch current run in real-time
npm run actions:watch
# View logs of latest run
npm run actions:logs
```
**Direct GitHub CLI commands:**
```bash
# Check specific run by ID
gh run view <run-id>
# View logs of specific run
gh run view <run-id> --log
# Re-run a failed workflow
gh run rerun <run-id>
# Cancel a running workflow
gh run cancel <run-id>
```
## Implementation Guidelines
1. **TypeScript with strict mode** for type safety
2. **MCP SDK integration** for protocol compliance
3. **Dual transport support** (stdio and HTTP)
4. **Use native fetch** instead of axios
5. **Implement proper pagination** (10 results per page)
6. **Handle all filter parameters** (status, severity, modified_date, sort_by)
7. **JSON Schema validation** for input validation
8. **Broadcast SSE events** for tool execution start/complete/error (HTTP mode)
9. **Use URLSearchParams** for query string building
10. **Implement graceful shutdown** handling
11. **Add comprehensive logging** with timestamps
12. **Include proper TypeScript types** and JSDoc comments
## Testing Considerations
Ensure the server handles:
- Invalid credentials
- Network timeouts
- Malformed requests
- Large result sets
- Concurrent requests
- SSE connection drops
## Example Tool Schema
Each tool should have proper input schema validation:
```javascript
{
name: 'search_bugs_by_keyword',
description: 'Search for bugs using keywords in descriptions and headlines',
inputSchema: {
type: 'object',
properties: {
keyword: {
type: 'string',
description: 'Keywords to search for'
},
page_index: {
type: 'integer',
default: 1,
description: 'Page number (10 results per page)'
},
// ... other parameters
},
required: ['keyword']
}
}
```
## Cisco API Reference
Reference the official documentation at:
- https://developer.cisco.com/docs/support-apis/bug/
Key API patterns:
- `/bugs/bug_ids/{bug_ids}` - Get specific bugs
- `/bugs/keyword/{keyword}` - Search by keyword
- `/bugs/products/product_id/{base_pid}` - Search by product
- `/bugs/product_series/{series}/affected_releases/{releases}` - Product series queries
Start by setting up the basic Express server structure, then implement OAuth2 authentication, followed by the MCP tools and SSE functionality.
## Troubleshooting
### Claude Desktop Integration Issues
#### Common Problems
1. **JSON-RPC parsing errors in stdio mode**:
- Ensure logging is disabled in stdio mode to prevent interference
- Check that console output doesn't contain non-JSON-RPC messages
2. **Connection refused errors**:
- ✅ **FIXED in v1.3.0**: Added proper `/mcp` endpoint with StreamableHTTP transport
- Use `http://localhost:3000/mcp` for HTTP connections
- Server supports both legacy `/sse` and standard `/mcp` endpoints
3. **500 Internal Server Error - Parameter validation**:
- ✅ **FIXED in v1.4.1-1.4.2**: Cisco Bug API only accepts single parameter values
- **Severity**: Use `"3"` not `"1,2,3"` - make separate searches for each severity level
- **Status**: Use `"O"` not `"O,F"` - search each status individually
- **For "severity 3 or higher"**: Search severity 1, then 2, then 3 separately
- Use the `cisco-high-severity-search` prompt for guided multi-severity searches
4. **API parameter validation errors**:
- Don't send default status/severity parameters unless explicitly specified
- Let Cisco API use its own defaults for broader compatibility
5. **Authentication failures**:
- Verify CISCO_CLIENT_ID and CISCO_CLIENT_SECRET in environment
- Ensure Cisco API application has proper permissions
#### Debugging Tools
**Monitor Claude Desktop logs in real-time**:
```bash
# macOS - Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
# Look for specific error patterns
grep -i error ~/Library/Logs/Claude/mcp*.log
grep -i "cisco-support" ~/Library/Logs/Claude/mcp*.log
```
**Test server manually**:
```bash
# Test stdio mode
npx mcp-cisco-support
# Test HTTP mode with new /mcp endpoint
npx mcp-cisco-support --http
curl http://localhost:3000/health
curl -X POST http://localhost:3000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
```
#### MCP Endpoints (v1.3.0+)
**Primary MCP Endpoint** (recommended):
- `POST /mcp` - MCP JSON-RPC calls with session management
- `GET /mcp` - SSE streams for ongoing sessions
- `DELETE /mcp` - Session termination
**Legacy Endpoints** (backward compatibility):
- `GET /sse` - Legacy SSE connection
- `POST /messages` - Legacy SSE messages
#### Log Analysis
Key log messages to monitor:
- `"Message from client"` - Incoming MCP requests
- `"Message from server"` - Outgoing MCP responses
- `"Tool call started"` - API calls beginning
- `"Session initialized"` - New MCP sessions created
- `"error"` - Any error conditions
**Healthy connection logs should show**:
1. Server initialization
2. Client initialize request/response with session ID
3. tools/list requests/responses
4. No JSON parsing errors
## Development Roadmap
### Current API Implementation Status
| API | Status | Tools | Description |
|-----|--------|-------|-------------|
| **Bug** | ✅ **Implemented** | 14 tools | Bug Search, Details, Product-specific searches + Enhanced Analysis |
| **Case** | ✅ **Complete** | 4 tools | Support case management and operations |
| **EoX** | ✅ **Complete** | 4 tools | End of Life/Sale information and notifications |
| **Product** | ✅ **Complete** | 3 tools | Product details, specifications, and technical information |
| **Software** | ✅ **Complete** | 6 tools | Software suggestions, releases, and upgrade recommendations |
| **Serial** | ✅ **Complete** | 3 tools | Serial number to coverage, warranty, and product information |
| **RMA** | ✅ **Complete** | 3 tools | Return Merchandise Authorization tracking and management |
| **PSIRT** | ✅ **Complete** | 8 tools | Product Security Incident Response Team vulnerability data |
| **Smart Bonding** | ⚠️ **EXPERIMENTAL** | 8 tools | Complete ticket lifecycle and TSP codes (UNTESTED - separate auth required) |
### Next Implementation Priorities
✅ **ALL CORE APIS COMPLETE** - 8/8 Support APIs fully implemented with 46 tools!
**Recently Added:**
1. ✅ **Smart Bonding API (EXPERIMENTAL)** - Branch: `feature/smart-bonding-api`
- ⚠️ **Status:** UNTESTED - Requires special credentials from Cisco Account Manager
- **Tools:** 8 (complete ticket lifecycle management)
- get_smart_bonding_tsp_codes - TSP code retrieval for classification
- pull_smart_bonding_tickets - Pull new ticket updates
- create_smart_bonding_ticket - Create new tickets (returns upload credentials)
- update_smart_bonding_ticket - Add work notes and updates
- upload_file_to_smart_bonding_ticket - Upload files via HTTPS PUT to cxd.cisco.com
- escalate_smart_bonding_ticket - Escalate to Cisco
- resolve_smart_bonding_ticket - Mark as resolved
- close_smart_bonding_ticket - Close with diagnosis/solution
- **Auth:** Separate OAuth2 system (cloudsso.cisco.com) with 1-hour token validity
- **File Uploads:** Separate HTTPS PUT to cxd.cisco.com using credentials from ticket creation (Field80-82)
- **Environment:** `SMART_BONDING_CLIENT_ID`, `SMART_BONDING_CLIENT_SECRET`, `SMART_BONDING_ENV`
- **Endpoints:** GET /tspcodes, GET /pull/call, POST /push/call, PUT https://cxd.cisco.com/home/*
- **Note:** Not included in `SUPPORT_API=all` - must be explicitly enabled
**Completed Implementations:**
1. ✅ **Case Management API** - Complete (4 tools)
2. ✅ **EoX API** - Complete (4 tools)
3. ✅ **Product Information API** - Complete (3 tools)
4. ✅ **Serial Number API** - Complete (3 tools)
5. ✅ **Software Suggestion API** - Complete (6 tools)
- Compatibility information
6. **RMA API** - Support for return processes
- RMA request creation
- Return status tracking
- Return authorization management
7. **PSIRT API** - Security vulnerability data
- Security advisory information
- CVE vulnerability details
- Product security notifications
- Severity-based vulnerability searches
### Architecture Benefits
The configurable API system provides:
- **Scalability**: Each API can be developed independently
- **User Control**: Users enable only APIs they have access to
- **Performance**: Smaller tool sets for faster initialization
- **Security**: No exposure of unauthorized API endpoints
- **Maintainability**: Clean separation by API functionality
### Implementation Framework
Each new API follows this pattern:
1. **API Tools Definition**: Create tool array for the API
2. **Schema Validation**: Define input schemas for all tools
3. **API Integration**: Implement Cisco API calls and authentication
4. **Response Formatting**: Add hyperlinks and structured output
5. **Error Handling**: Comprehensive error management
6. **Documentation**: Update README and examples
7. **Testing**: Validate with real API credentials
### Configuration Examples
Users can configure exactly what they need:
```bash
# Development/Testing - Bug API only
SUPPORT_API=bug
# Simplified Analysis - Enhanced tools only (recommended for most users)
SUPPORT_API=enhanced_analysis
# Support Engineer - Case management focus
SUPPORT_API=bug,case,rma
# Product Manager - Product lifecycle focus
SUPPORT_API=bug,eox,product,software
# Administrator - Full access
SUPPORT_API=all
```
## Testing Framework
This project includes a comprehensive Jest-based testing framework that validates all functionality without requiring live API calls during development.
### Test Coverage
✅ **Simple Tests**: 3/3 passing - Basic functionality validation
✅ **Bug API Tests**: 17/17 passing - All 8 Bug API tools fully tested
✅ **MCP Server Tests**: 11/11 passing - Server functionality and configuration
✅ **Integration Tests**: 7/7 passing - Real API validation with live credentials
✅ **Error Handling Tests**: Timeout, authentication, and parameter validation
✅ **Elicitation Tests**: 7/7 passing - ElicitationRequest feature and schema validation
### Test Commands
```bash
# Run all tests
npm test
# Run specific test suites
npm test -- --testNamePattern="Bug API"
npm test -- --testNamePattern="Simple"
npm test -- --testNamePattern="MCP Server"
npm test -- --testNamePattern="Elicitation"
# Run integration tests with real API (requires credentials)
CISCO_CLIENT_ID=your_id CISCO_CLIENT_SECRET=your_secret npm test -- --testNamePattern="Integration"
# Run tests with coverage
npm test -- --coverage
# Type checking
npx tsc --noEmit
```
### Test Structure
- **`tests/simple.test.ts`** - Basic functionality and tool discovery
- **`tests/bugApi.test.ts`** - Comprehensive Bug API tool testing with mocks
- **`tests/mcpServer.test.ts`** - MCP server functionality and prompt testing
- **`tests/integration.test.ts`** - Real API integration tests (skipped by default)
- **`tests/errorHandling.test.ts`** - Error scenarios and edge cases
- **`tests/elicitation.test.ts`** - ElicitationRequest feature testing
- **`tests/mockData.ts`** - Mock Cisco API responses for unit tests
- **`tests/setup.ts`** - Jest configuration and global mocks
### Mock Data and Testing
The test framework uses comprehensive mock data that simulates real Cisco Bug API responses:
```typescript
// Example mock bug response
{
bugs: [
{
bug_id: 'CSCvi12345',
headline: 'Test bug for CallManager 12.5 memory leak',
status: 'O',
severity: '3',
product: 'Cisco Unified Communications Manager',
affected_releases: ['12.5(1)SU1', '12.5(1)SU2'],
fixed_releases: ['12.5(1)SU3']
}
],
total_results: 1
}
```
### Real API Testing
Integration tests can be run with real Cisco API credentials to validate:
- OAuth2 authentication flow
- Parameter validation with live API
- Error handling with actual API responses
- Rate limiting and network error scenarios
### Key Test Features
- **Fetch Mocking**: Proper Jest mocking for all HTTP requests
- **Parameter Validation**: Tests for all required and optional parameters
- **Error Scenarios**: Comprehensive error handling validation
- **Schema Validation**: JSON Schema compliance for all tools
- **Real vs Mock**: Separate unit tests (mocked) and integration tests (real API)
### Testing Best Practices
When developing new features:
1. **Write Unit Tests First**: Create mocked tests for new tools
2. **Add Integration Tests**: Test with real API when possible
3. **Mock Properly**: Use realistic mock data that matches API responses
4. **Test Error Cases**: Include timeout, auth failures, and invalid parameters
5. **Validate Schemas**: Ensure all tools have proper JSON Schema validation
## API Documentation (WADL)
The project includes official Cisco Bug API v2.0 WADL (Web Application Description Language) specification in the `wadl/` directory:
### WADL File Structure
```
wadl/
└── Cisco-BUG-API-v2_0.wadl # Complete API specification
```
### Key WADL Insights
The WADL file confirms critical API limitations that were implemented in this server:
1. **Single Value Parameters**: The WADL definitively shows that `severity` and `status` parameters only accept single values, not comma-separated lists:
```xml
<!-- From WADL: Only one severity value allowed -->
<param name="severity" style="query" type="xs:string"/>
```
2. **Parameter Constraints**: Documents valid values for each parameter:
- **Severity**: 1, 2, 3, 4, 5, 6 (single values only)
- **Status**: O (Open), F (Fixed), T (Terminated), etc.
- **Modified Date**: 1, 2, 3, 4, 5 (days/weeks/months)
3. **Endpoint Structure**: Validates the correct URL patterns for all 8 implemented endpoints:
- `/bugs/bug_ids/{bug_ids}`
- `/bugs/keyword/{keyword}`
- `/bugs/products/product_id/{base_pid}`
- `/bugs/products/product_id/{base_pid}/software_releases/{software_releases}`
- `/bugs/product_series/{product_series}/affected_releases/{affected_releases}`
- `/bugs/product_series/{product_series}/fixed_releases/{fixed_releases}`
- `/bugs/products/product_name/{product_name}/affected_releases/{affected_releases}`
- `/bugs/products/product_name/{product_name}/fixed_releases/{fixed_releases}`
4. **Authentication Requirements**: Confirms OAuth2 client credentials flow
5. **Response Formats**: Specifies JSON response structure and error codes
### Using WADL for Development
The WADL file serves as the authoritative reference for:
- Parameter validation rules
- Response format specifications
- Error code definitions
- Authentication requirements
- Rate limiting information
This ensures the MCP server implementation matches Cisco's official API specification exactly.
### WADL Validation Process
When implementing new API endpoints:
1. **Check WADL First**: Verify endpoint exists and parameter requirements
2. **Validate Parameters**: Ensure all parameter constraints are followed
3. **Test Against Spec**: Compare implementation behavior with WADL definitions
4. **Update Tests**: Add test cases that validate WADL compliance
5. **Document Limitations**: Note any API constraints in tool descriptions
## GitHub Wiki Management
The project maintains comprehensive documentation on the GitHub wiki at: https://github.com/sieteunoseis/mcp-cisco-support/wiki
### Available Wiki Pages
Current wiki pages include:
- **N8n Personal Assistant Integration** - Complete N8n setup guide with system message prompts
- **Available Tools** - Comprehensive tool reference
- **Development Guide** - Development and contribution guidelines
- **Docker Deployment** - Container deployment instructions
- **Security Guide** - Security configuration and best practices
- **Troubleshooting Guide** - Common issues and solutions
- **Testing Framework** - Testing methodology and examples
- **SSE Integration** - Server-Sent Events implementation details
### Updating Wiki Pages
To update or add new wiki pages:
#### Method 1: GitHub Web Interface (Recommended)
1. Navigate to: https://github.com/sieteunoseis/mcp-cisco-support/wiki
2. Click "Edit" on existing pages or "New Page" for new content
3. Make changes directly in the web editor
4. Click "Save Page" to publish changes
#### Method 2: Command Line (Advanced)
```bash
# Clone the wiki repository (separate from main repo)
git clone https://github.com/sieteunoseis/mcp-cisco-support.wiki.git wiki-repo
# Navigate to wiki directory
cd wiki-repo
# Create or edit markdown files
# File names become page titles (spaces replaced with hyphens)
echo "# New Page Content" > New-Page-Title.md
# Commit and push changes
git add .
git commit -m "Add/update wiki page: New Page Title"
git push origin master
# Clean up
cd .. && rm -rf wiki-repo
```
#### Method 3: Automated Script
```bash
# Create a helper script for wiki updates
cat > update-wiki.sh << 'EOF'
#!/bin/bash
WIKI_PAGE="$1"
CONTENT_FILE="$2"
if [ -z "$WIKI_PAGE" ] || [ -z "$CONTENT_FILE" ]; then
echo "Usage: ./update-wiki.sh 'Page-Title' 'content-file.md'"
exit 1
fi
# Clone wiki repo
git clone https://github.com/sieteunoseis/mcp-cisco-support.wiki.git temp-wiki
cd temp-wiki
# Copy content
cp "../$CONTENT_FILE" "$WIKI_PAGE.md"
# Commit and push
git add "$WIKI_PAGE.md"
git commit -m "Update wiki page: $WIKI_PAGE"
git push origin master
# Clean up
cd .. && rm -rf temp-wiki
echo "Wiki page '$WIKI_PAGE' updated successfully!"
EOF
chmod +x update-wiki.sh
# Usage example:
# ./update-wiki.sh "New-Feature-Guide" "docs/new-feature.md"
```
### Wiki Page Naming Conventions
- **File Names**: Use hyphens for spaces (e.g., `N8n-Personal-Assistant.md`)
- **Page Titles**: Descriptive and searchable (e.g., "N8n Personal Assistant Integration")
- **Content Structure**: Use consistent markdown formatting with proper headers
- **Links**: Use relative links between wiki pages when possible
### Wiki Best Practices
1. **Keep Content Current**: Update wiki pages when making significant changes to the codebase
2. **Cross-Reference**: Link related wiki pages and main project documentation
3. **Examples**: Include practical examples and code snippets
4. **Screenshots**: Add screenshots for UI-related documentation (store in main repo's `screenshots/` directory)
5. **Version Compatibility**: Note version requirements and compatibility information
6. **Search Optimization**: Use descriptive headers and keywords for better searchability
### Important Notes
- **Separate Repository**: The wiki is stored in a separate Git repository (.wiki.git)
- **Markdown Format**: All pages use GitHub-flavored Markdown
- **No Build Process**: Wiki pages are rendered directly by GitHub
- **Public Access**: Wiki pages are publicly accessible (same as main repository visibility)
- **History**: Wiki pages maintain full Git history for tracking changes