Cisco Catalyst Center (DNAC) MCP Server

# DNAC MCP Server - Project Overview ## 📋 Project Summary This is a **Model Context Protocol (MCP) server** that provides intelligent wireless client management tools for **Cisco Catalyst Center (DNA Center)**. It enables AI assistants like Claude to interact with DNAC infrastructure through standardized MCP tools. **Version:** 1.0.0 **License:** MIT **Python:** 3.10+ ## 🎯 Key Features - **Smart Query Limiting**: Automatic result limiting with configurable thresholds - **Intelligent Guidance**: Actionable suggestions when results exceed limits - **Rich Filtering**: Filter by site, MAC, IP, SSID, band, hostname, and more - **Health Monitoring**: Detailed client health metrics and diagnostics - **Rate Limiting**: Built-in API throttling to prevent overload - **Secure**: Support for SSL verification and credential management - **Well-Tested**: Comprehensive test suite following TDD principles ## 📁 Project Structure ``` dnac-mcp/ ├── src/ │ └── dnac_mcp/ │ ├── __init__.py # Package initialization │ ├── server.py # MCP server implementation │ ├── wireless_client_agent.py # DNAC client agent │ └── config.py # Configuration management ├── tests/ │ ├── __init__.py │ ├── test_server.py # MCP server tests │ ├── test_wireless_client_agent.py # Agent tests │ └── test_config.py # Configuration tests ├── examples/ │ └── example_usage.py # Usage examples ├── scripts/ │ └── verify_setup.py # Setup verification script ├── docs/ │ ├── README.md # Main documentation │ ├── CONTRIBUTING.md # Contribution guidelines │ └── CHANGELOG.md # Version history ├── pyproject.toml # Project configuration ├── requirements.txt # Core dependencies ├── requirements-dev.txt # Development dependencies ├── config.example.json # Example configuration ├── .gitignore # Git ignore rules └── LICENSE # MIT License ``` ## 🛠️ Architecture ### Components 1. **WirelessClientAgent** ([wireless_client_agent.py](src/dnac_mcp/wireless_client_agent.py)) - Core agent for querying DNAC wireless clients - Handles pagination and result limiting - Provides actionable guidance - Rate limiting for API calls 2. **MCP Server** ([server.py](src/dnac_mcp/server.py)) - Implements Model Context Protocol - Exposes tools for Claude/MCP clients - Handles tool execution and formatting - Async server using stdio transport 3. **Configuration Manager** ([config.py](src/dnac_mcp/config.py)) - Loads config from environment variables - Loads config from JSON files - Manages credentials securely ### Design Principles #### Test-Driven Development (TDD) All code follows the **Red-Green-Refactor** cycle: 1. ❌ **RED**: Write failing test 2. ✅ **GREEN**: Write minimal code to pass 3. 🔄 **REFACTOR**: Improve code while keeping tests green **Coverage:** 100% for core functionality #### SOLID Principles - **S**ingle Responsibility: Each class has one reason to change - **O**pen/Closed: Open for extension, closed for modification - **L**iskov Substitution: Subtypes are substitutable for base types - **I**nterface Segregation: No fat interfaces - **D**ependency Inversion: Depend on abstractions ## 🔧 Available Tools ### 1. `query_wireless_clients` Query wireless clients with smart filtering and limiting. **Parameters:** - `base_url` (required): DNAC URL - `username` (required): DNAC username - `password` (required): DNAC password - `site_id` (optional): Filter by site UUID - `mac_address` (optional): Filter by MAC - `hostname` (optional): Filter by AP hostname - `ip_address` (optional): Filter by IP - `ssid` (optional): Filter by SSID - `band` (optional): Filter by frequency band - `max_results` (optional): Max clients to return (default: 100) - `version` (optional): DNAC API version (default: "2.3.7.6") - `verify` (optional): Verify SSL (default: true) - `debug` (optional): Enable debug logging (default: true) **Returns:** ```json { "clients": [...], "total_count": 150, "exceeded_limit": true, "guidance": "Use more specific filters...", "fetched_count": 100 } ``` ### 2. `get_client_health` Get detailed health information for a specific client. **Parameters:** - `base_url` (required): DNAC URL - `username` (required): DNAC username - `password` (required): DNAC password - `mac_address` (required): Client MAC address - `version` (optional): DNAC API version - `verify` (optional): Verify SSL **Returns:** ```json { "health": { "healthScore": 8, "rssi": -50, "snr": 40 }, "response": {...}, "mac_address": "AA:BB:CC:DD:EE:FF" } ``` ## 🚀 Quick Start ### Installation ```bash # Clone repository git clone https://github.com/robertbergman/dnac-mcp.git cd dnac-mcp # Create virtual environment python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Install in development mode pip install -e . ``` ### Configuration **Option 1: Environment Variables** ```bash export DNAC_BASE_URL="https://dnac.example.com" export DNAC_USERNAME="admin" export DNAC_PASSWORD="password" ``` **Option 2: Configuration File** ```bash cp config.example.json config.json # Edit config.json with your credentials export DNAC_CONFIG_FILE="config.json" ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=src/dnac_mcp --cov-report=html # Verify setup python scripts/verify_setup.py ``` ### Using with Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "dnac-wireless-clients": { "command": "python", "args": ["-m", "dnac_mcp.server"], "env": { "DNAC_BASE_URL": "https://dnac.example.com", "DNAC_USERNAME": "admin", "DNAC_PASSWORD": "password" } } } } ``` ## 📊 Testing ### Test Coverage - **WirelessClientAgent**: 100% - **MCP Server**: 100% - **Configuration**: 100% - **Overall**: 100% for core functionality ### Running Tests ```bash # All tests pytest # Specific test file pytest tests/test_wireless_client_agent.py # Specific test pytest tests/test_wireless_client_agent.py::TestWirelessClientAgent::test_get_count # With coverage pytest --cov=src/dnac_mcp --cov-report=html open htmlcov/index.html ``` ## 🎨 Code Quality ### Formatting ```bash # Format code black src tests # Check formatting black --check src tests ``` ### Linting ```bash # Lint code ruff check src tests # Fix auto-fixable issues ruff check --fix src tests ``` ### Type Checking ```bash # Type check mypy src ``` ## 📚 Documentation - **[README.md](README.md)**: Main documentation with installation and usage - **[CONTRIBUTING.md](CONTRIBUTING.md)**: TDD and SOLID guidelines for contributors - **[CHANGELOG.md](CHANGELOG.md)**: Version history and changes - **[examples/example_usage.py](examples/example_usage.py)**: Usage examples - **[config.example.json](config.example.json)**: Configuration example ## 🤝 Contributing We welcome contributions! Please follow these steps: 1. **Fork** the repository 2. **Create** a feature branch 3. **Write tests** first (TDD approach) 4. **Implement** the feature following SOLID principles 5. **Format** code with `black` 6. **Lint** code with `ruff` 7. **Run tests** with `pytest` 8. **Submit** a pull request See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. ## 🐛 Troubleshooting ### Common Issues 1. **Connection Errors** - Verify `base_url` is correct - Check credentials - For self-signed certs: set `verify=false` 2. **SSL Errors** - Set `DNAC_VERIFY=false` (testing only) - Install CA certificates 3. **No Results** - Verify filters are correct - Check DNAC has matching clients - Enable debug: `debug=true` 4. **API Errors** - Check DNAC API version - Verify user permissions - Review logs: `catalyst_center_debug.log` ## 🗺️ Roadmap ### Planned Features - [ ] Support for wired clients - [ ] Client troubleshooting tools - [ ] Network device queries - [ ] Statistics and trends - [ ] Webhook notifications - [ ] GraphQL support - [ ] Multi-site aggregation - [ ] CSV/JSON export - [ ] Performance metrics - [ ] Historical data ## 📄 License MIT License - see [LICENSE](LICENSE) for details. ## 🙏 Acknowledgments - Built with [dnacentersdk](https://github.com/cisco-en-programmability/dnacentersdk) - Implements [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - Inspired by Cisco DevNet community ## 📞 Support - **Issues**: [GitHub Issues](https://github.com/robertbergman/dnac-mcp/issues) - **Discussions**: [GitHub Discussions](https://github.com/robertbergman/dnac-mcp/discussions) - **Documentation**: [DNAC SDK Docs](https://dnacentersdk.readthedocs.io/) --- **Built with ❤️ following TDD and SOLID principles**