Unimus MCP Server

# Changelog All notable changes to the Unimus MCP Server project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.0.0] - 2025-06-20 🎉 **MAJOR MILESTONE: First stable release of Unimus MCP Server!** This release represents a fully-featured, production-ready MCP server for Unimus network configuration management with enterprise-grade capabilities. ### Added - **Complete MCP Tool Suite**: All 15 MCP tools implemented and fully validated - Device management and querying with flexible attribute selection - Backup content search with regex pattern matching and context - Network topology analysis and device relationship mapping - Schedule management and change tracking - System health monitoring and degraded mode operation - **Enhanced Device Metadata & Analytics**: - `enrich_metadata` parameter for calculated device insights - 12 comprehensive metadata fields including backup health, device lifecycle, connectivity analysis - Intelligent categorization with backup freshness and configuration stability assessment - **Network Intelligence Features**: - `unimus_get_network_topology_analysis`: Complete network overview with subnet detection and device clustering - `unimus_get_device_relationships`: Deep analysis of device relationships and network connections - Automatic zone-based analysis and security assessment - Device role classification (standalone, endpoint, network_node, infrastructure_hub) - **Response Caching System**: - Intelligent caching with 2.3x performance improvement (up to 358x for cached operations) - Multiple backends: memory (TTLCache) and disk (DiskCache) support - Configurable TTL per operation type (60s-86400s range) - 65.7% cache hit ratio with comprehensive statistics tracking - **Enterprise-Grade Configuration Management**: - YAML and TOML configuration file support with hierarchical precedence - Environment variable overrides for deployment flexibility - Comprehensive validation and error handling - Advanced settings including custom headers and feature flags - **Production-Ready Docker Deployment**: - Multi-stage optimized Dockerfile (154MB final image) - Multi-platform support (linux/amd64, linux/arm64) - Kubernetes-style health checks (/healthz, /readyz, /health) - Graceful degraded mode operation with external dependency resilience - Security hardening with non-root user and minimal attack surface - **Robust CI/CD Pipeline**: - Automated Docker builds and publishing to GitHub Container Registry - Comprehensive health check testing in degraded mode scenarios - Security vulnerability scanning with Trivy and SARIF upload - Multi-threaded architecture preventing health check interference - **Comprehensive Testing Framework**: - 39% code coverage with 134/135 tests passing (99.3% success rate) - Live production validation against real Unimus infrastructure - Enterprise-grade mock patterns and error simulation - Integration testing with 17-device test environment ### Changed - **Server Architecture**: Improved multi-threaded startup logic in `server.py` - MCP server and health check server run in separate daemon threads - Main thread stability improvements preventing thread interference - Graceful shutdown handling with KeyboardInterrupt support - **Configuration System**: Complete overhaul from environment-only to hierarchical configuration - Precedence: Environment Variables → Configuration File → Defaults - Backward compatibility maintained for existing deployments - **Health Check Strategy**: Enhanced readiness vs liveness probe separation - `/readyz` validates external dependencies (Unimus connectivity) - `/healthz` provides simple liveness indication - `/health` maintains legacy compatibility ### Fixed - **Docker Build Issues**: Resolved multiple Docker workflow problems - Correct multi-stage build implementation with proper artifact copying - Fixed repository name case sensitivity for container registries - Resolved missing dependencies and README.md in build context - **Threading Conflicts**: Eliminated thread interference between MCP and HTTP servers - Prevented stdio I/O from blocking network I/O operations - Ensured health check endpoints remain accessible during operation - **Cache Implementation**: Fixed cache hit ratio issues and backend selection - Resolved isinstance() check problems with TTLCache objects - Improved cache key generation with MD5 hashing and parameter serialization ### Security - **Container Security**: Implemented security best practices - Non-root user execution (UID 1000) - Minimal base image with only essential runtime dependencies - Vulnerability scanning integration with automated security reporting - **Authentication**: Robust API token handling and validation - Secure credential management in container environments - Proper error handling without credential exposure ### Performance - **Caching Performance**: Spectacular performance improvements - Overall: 57.1% improvement (2.3x speedup) - Individual operations: Up to 358x speedup for cached responses - Cache effectiveness: 65.7% hit ratio in production scenarios - **Container Optimization**: Efficient Docker image design - 154MB production image size - Optimized layer caching for faster builds - Multi-platform build support without performance penalty ### Documentation - **Comprehensive Wiki**: Complete documentation overhaul - Installation guides for multiple deployment scenarios - API reference for all 15 MCP tools with examples - Configuration reference with YAML/TOML examples - Docker deployment guide with enterprise patterns - Development guide with testing and contribution information ### Technical Specifications - **Compatibility**: Python 3.10+ with Unimus 1.7.x or newer (API v.2) - **Dependencies**: Modern stack with mcp>=1.3.0, requests, PyYAML, cachetools, diskcache - **Architecture**: FastMCP-based server with RESTful Unimus API integration - **Deployment**: Docker-first with traditional Python installation support - **Testing**: Comprehensive test suite with live infrastructure validation --- **🎯 Production Readiness**: This 1.0.0 release has been extensively tested against live Unimus infrastructure with 17 managed devices, validating all features under real-world conditions. The implementation follows enterprise-grade patterns and is ready for production deployment. **🚀 Performance**: With response caching and optimized architecture, this release delivers significant performance improvements while maintaining reliability and comprehensive error handling. **🔒 Security**: Built with security-first principles, including container hardening, vulnerability scanning, and secure credential management. ### Repository Management - **Enterprise Showcase Anonymization**: Relocated enterprise network analysis from main repository to wiki with anonymized data - IP addresses changed from client-specific (10.197.x.x) to generic (192.168.x.x) - Hostnames anonymized from client-specific (nl-dc-oum-*) to generic (dc-site1-*) - Client confidentiality protection while maintaining technical demonstration value - Added Enterprise Showcase link to wiki homepage for easy access