# 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
- OAuth2 authentication with Cisco API (client credentials flow)
- 8 MCP-compliant tools for comprehensive bug searching (with more tools planned)
- 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": ["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)
- **`bug`** - All 14 Bug API tools (basic bug search capabilities)
- **`all`** - All available APIs and tools (complete feature set)
- **`bug,case,psirt`** - Multiple specific APIs (custom combinations)
### 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"
### 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
### 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** | 8 tools | Bug Search, Details, Product-specific searches |
| **Case** | š **Planned** | 0 tools | Support case management and operations |
| **EoX** | š **Planned** | 0 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** | š **Planned** | 0 tools | Serial number to product information mapping |
| **RMA** | š **Planned** | 0 tools | Return Merchandise Authorization processes |
| **PSIRT** | ā
**Complete** | 8 tools | Product Security Incident Response Team vulnerability data |
### Next Implementation Priorities
1. **Case Management API** - High priority for support workflows
- Create/update/search support cases
- Case status tracking and management
- Attachment handling for cases
2. **EoX API** - Critical for lifecycle management
- End of Life announcements
- End of Sale notifications
- Product lifecycle information
3. **Product Information API** - Essential for product research
- Product specifications and details
- Product family and series information
- Product documentation links
4. **Serial Number API** - Important for asset tracking
- Serial to product mapping
- Warranty information lookup
- Contract and coverage details
5. **Software Suggestion API** - Valuable for updates
- Software recommendations
- Update suggestions
- 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
### 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"
# 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/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
