mcp-ticketer 0.1.28__tar.gz → 0.1.29__tar.gz

{mcp_ticketer-0.1.28 → mcp_ticketer-0.1.29}/CHANGELOG.md

@@ -6,6 +6,41 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [0.1.29] - 2025-10-24
+
+### Added
+- **Comprehensive Diagnostics System**: Complete health monitoring and self-diagnosis capabilities
+  - `mcp-ticketer health`: Quick system health check command
+  - `mcp-ticketer diagnose`: Comprehensive system diagnostics with detailed analysis
+  - `system_health` MCP tool: AI agents can perform quick health checks
+  - `system_diagnose` MCP tool: AI agents can run comprehensive diagnostics
+- **Intelligent Fallback System**: Graceful degradation when dependencies are missing
+  - Simple health checks that work without heavy dependencies
+  - Automatic fallback to lightweight diagnostics when full system fails
+  - Import protection for missing optional dependencies
+- **Multi-Component Analysis**:
+  - Configuration validation and adapter testing
+  - Queue system health monitoring with failure rate analysis
+  - Environment variable detection and validation
+  - Installation verification and version checking
+  - Performance metrics and response time analysis
+- **Rich Output Formats**:
+  - Colorized terminal output with status indicators
+  - JSON export for automation and integration
+  - File output for reporting and analysis
+  - Progressive disclosure (health → diagnose)
+- **Exit Code Standards**: Proper exit codes for CI/CD integration (0=healthy, 1=critical, 2=warnings)
+
+### Enhanced
+- **MCP Server**: Added two new diagnostic tools for AI agent integration
+- **Error Handling**: Improved graceful handling of missing dependencies and failed components
+- **User Experience**: Clear, actionable recommendations for resolving detected issues
+
+### Fixed
+- **System Visibility**: Addresses the "60% failure rate" issue by providing comprehensive system monitoring
+- **AI Agent Troubleshooting**: AI agents can now self-diagnose and identify system issues
+- **Dependency Resilience**: System remains functional even when optional dependencies are missing
+
 ### Added
 - WebSocket support for real-time updates
 - Custom ticket templates

{mcp_ticketer-0.1.28 → mcp_ticketer-0.1.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 0.1.28
+Version: 0.1.29
 Summary: Universal ticket management interface for AI agents with MCP support
 Author-email: MCP Ticketer Team <support@mcp-ticketer.io>
 Maintainer-email: MCP Ticketer Team <support@mcp-ticketer.io>

{mcp_ticketer-0.1.28 → mcp_ticketer-0.1.29}/src/mcp_ticketer/__version__.py

@@ -1,6 +1,6 @@
 """Version information for mcp-ticketer package."""
 
-__version__ = "0.1.28"
+__version__ = "0.1.29"
 __version_info__ = tuple(int(part) for part in __version__.split("."))
 
 # Package metadata

mcp_ticketer-0.1.29/src/mcp_ticketer/cli/diagnostics.py

@@ -0,0 +1,492 @@
+"""Comprehensive diagnostics and self-diagnosis functionality for MCP Ticketer."""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+try:
+    from ..core.config import get_config
+except ImportError:
+    # Fallback for missing dependencies
+    def get_config():
+        raise ImportError("Configuration system not available")
+
+try:
+    from ..core.registry import AdapterRegistry
+except ImportError:
+    AdapterRegistry = None
+
+try:
+    from ..queue.manager import QueueManager
+except ImportError:
+    QueueManager = None
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+class SystemDiagnostics:
+    """Comprehensive system diagnostics and health reporting."""
+
+    def __init__(self):
+        try:
+            self.config = get_config()
+        except Exception as e:
+            self.config = None
+            console.print(f"⚠️  Could not load configuration: {e}")
+
+        try:
+            self.queue_manager = QueueManager() if QueueManager else None
+        except Exception as e:
+            self.queue_manager = None
+            console.print(f"⚠️  Could not initialize queue manager: {e}")
+
+        self.issues = []
+        self.warnings = []
+        self.successes = []
+
+    async def run_full_diagnosis(self) -> Dict[str, Any]:
+        """Run complete system diagnosis and return detailed report."""
+        console.print("\n🔍 [bold blue]MCP Ticketer System Diagnosis[/bold blue]")
+        console.print("=" * 60)
+
+        report = {
+            "timestamp": datetime.now().isoformat(),
+            "version": self._get_version(),
+            "system_info": self._get_system_info(),
+            "configuration": await self._diagnose_configuration(),
+            "adapters": await self._diagnose_adapters(),
+            "queue_system": await self._diagnose_queue_system(),
+            "recent_logs": await self._analyze_recent_logs(),
+            "performance": await self._analyze_performance(),
+            "recommendations": self._generate_recommendations(),
+        }
+
+        self._display_diagnosis_summary(report)
+        return report
+
+    def _get_version(self) -> str:
+        """Get current version information."""
+        try:
+            from ..__version__ import __version__
+            return __version__
+        except ImportError:
+            return "unknown"
+
+    def _get_system_info(self) -> Dict[str, Any]:
+        """Gather system information."""
+        return {
+            "python_version": sys.version,
+            "platform": sys.platform,
+            "working_directory": str(Path.cwd()),
+            "config_path": str(self.config.config_file) if hasattr(self.config, 'config_file') else "unknown",
+        }
+
+    async def _diagnose_configuration(self) -> Dict[str, Any]:
+        """Diagnose configuration issues."""
+        console.print("\n📋 [yellow]Configuration Analysis[/yellow]")
+
+        config_status = {
+            "status": "healthy",
+            "adapters_configured": 0,
+            "default_adapter": None,
+            "issues": [],
+        }
+
+        if not self.config:
+            issue = "Configuration system not available"
+            config_status["issues"].append(issue)
+            config_status["status"] = "critical"
+            self.issues.append(issue)
+            console.print(f"❌ {issue}")
+            return config_status
+
+        try:
+            # Check adapter configurations
+            adapters = self.config.get_enabled_adapters()
+            config_status["adapters_configured"] = len(adapters)
+            config_status["default_adapter"] = self.config.default_adapter
+
+            if not adapters:
+                issue = "No adapters configured"
+                config_status["issues"].append(issue)
+                config_status["status"] = "critical"
+                self.issues.append(issue)
+                console.print(f"❌ {issue}")
+            else:
+                console.print(f"✅ {len(adapters)} adapter(s) configured")
+
+            # Check each adapter configuration
+            for name, adapter_config in adapters.items():
+                try:
+                    adapter_class = AdapterRegistry.get_adapter(adapter_config.type.value)
+                    adapter = adapter_class(adapter_config.dict())
+                    
+                    # Test adapter validation if available
+                    if hasattr(adapter, 'validate_credentials'):
+                        is_valid, error = adapter.validate_credentials()
+                        if is_valid:
+                            console.print(f"✅ {name}: credentials valid")
+                            self.successes.append(f"{name} adapter configured correctly")
+                        else:
+                            issue = f"{name}: credential validation failed - {error}"
+                            config_status["issues"].append(issue)
+                            self.warnings.append(issue)
+                            console.print(f"⚠️  {issue}")
+                    else:
+                        console.print(f"ℹ️  {name}: no credential validation available")
+
+                except Exception as e:
+                    issue = f"{name}: configuration error - {str(e)}"
+                    config_status["issues"].append(issue)
+                    self.issues.append(issue)
+                    console.print(f"❌ {issue}")
+
+        except Exception as e:
+            issue = f"Configuration loading failed: {str(e)}"
+            config_status["issues"].append(issue)
+            config_status["status"] = "critical"
+            self.issues.append(issue)
+            console.print(f"❌ {issue}")
+
+        return config_status
+
+    async def _diagnose_adapters(self) -> Dict[str, Any]:
+        """Diagnose adapter functionality."""
+        console.print("\n🔌 [yellow]Adapter Diagnosis[/yellow]")
+        
+        adapter_status = {
+            "total_adapters": 0,
+            "healthy_adapters": 0,
+            "failed_adapters": 0,
+            "adapter_details": {},
+        }
+
+        try:
+            adapters = self.config.get_enabled_adapters()
+            adapter_status["total_adapters"] = len(adapters)
+
+            for name, adapter_config in adapters.items():
+                details = {
+                    "type": adapter_config.type.value,
+                    "status": "unknown",
+                    "last_test": None,
+                    "error": None,
+                }
+
+                try:
+                    adapter_class = AdapterRegistry.get_adapter(adapter_config.type.value)
+                    adapter = adapter_class(adapter_config.dict())
+                    
+                    # Test basic adapter functionality
+                    test_start = datetime.now()
+                    
+                    # Try to list tickets (non-destructive test)
+                    try:
+                        await adapter.list(limit=1)
+                        details["status"] = "healthy"
+                        details["last_test"] = test_start.isoformat()
+                        adapter_status["healthy_adapters"] += 1
+                        console.print(f"✅ {name}: operational")
+                    except Exception as e:
+                        details["status"] = "failed"
+                        details["error"] = str(e)
+                        adapter_status["failed_adapters"] += 1
+                        issue = f"{name}: functionality test failed - {str(e)}"
+                        self.issues.append(issue)
+                        console.print(f"❌ {issue}")
+
+                except Exception as e:
+                    details["status"] = "failed"
+                    details["error"] = str(e)
+                    adapter_status["failed_adapters"] += 1
+                    issue = f"{name}: initialization failed - {str(e)}"
+                    self.issues.append(issue)
+                    console.print(f"❌ {issue}")
+
+                adapter_status["adapter_details"][name] = details
+
+        except Exception as e:
+            issue = f"Adapter diagnosis failed: {str(e)}"
+            self.issues.append(issue)
+            console.print(f"❌ {issue}")
+
+        return adapter_status
+
+    async def _diagnose_queue_system(self) -> Dict[str, Any]:
+        """Diagnose queue system health."""
+        console.print("\n⚡ [yellow]Queue System Diagnosis[/yellow]")
+        
+        queue_status = {
+            "worker_running": False,
+            "worker_pid": None,
+            "queue_stats": {},
+            "recent_failures": [],
+            "failure_rate": 0.0,
+            "health_score": 0,
+        }
+
+        try:
+            # Check worker status
+            worker_status = self.queue_manager.get_worker_status()
+            queue_status["worker_running"] = worker_status.get("running", False)
+            queue_status["worker_pid"] = worker_status.get("pid")
+
+            if queue_status["worker_running"]:
+                console.print(f"✅ Queue worker running (PID: {queue_status['worker_pid']})")
+                self.successes.append("Queue worker is running")
+            else:
+                issue = "Queue worker not running"
+                self.issues.append(issue)
+                console.print(f"❌ {issue}")
+
+            # Get queue statistics
+            stats = self.queue_manager.get_queue_stats()
+            queue_status["queue_stats"] = stats
+            
+            total_items = stats.get("total", 0)
+            failed_items = stats.get("failed", 0)
+            
+            if total_items > 0:
+                failure_rate = (failed_items / total_items) * 100
+                queue_status["failure_rate"] = failure_rate
+                
+                if failure_rate > 50:
+                    issue = f"High failure rate: {failure_rate:.1f}% ({failed_items}/{total_items})"
+                    self.issues.append(issue)
+                    console.print(f"❌ {issue}")
+                elif failure_rate > 20:
+                    warning = f"Elevated failure rate: {failure_rate:.1f}% ({failed_items}/{total_items})"
+                    self.warnings.append(warning)
+                    console.print(f"⚠️  {warning}")
+                else:
+                    console.print(f"✅ Queue failure rate: {failure_rate:.1f}% ({failed_items}/{total_items})")
+
+            # Calculate health score
+            health_score = 100
+            if not queue_status["worker_running"]:
+                health_score -= 50
+            health_score -= min(queue_status["failure_rate"], 50)
+            queue_status["health_score"] = max(0, health_score)
+
+            console.print(f"📊 Queue health score: {queue_status['health_score']}/100")
+
+        except Exception as e:
+            issue = f"Queue system diagnosis failed: {str(e)}"
+            self.issues.append(issue)
+            console.print(f"❌ {issue}")
+
+        return queue_status
+
+    async def _analyze_recent_logs(self) -> Dict[str, Any]:
+        """Analyze recent log entries for issues."""
+        console.print("\n📝 [yellow]Recent Log Analysis[/yellow]")
+        
+        log_analysis = {
+            "log_files_found": [],
+            "recent_errors": [],
+            "recent_warnings": [],
+            "patterns": {},
+        }
+
+        try:
+            # Look for common log locations
+            log_paths = [
+                Path.home() / ".mcp-ticketer" / "logs",
+                Path.cwd() / ".mcp-ticketer" / "logs",
+                Path("/var/log/mcp-ticketer"),
+            ]
+
+            for log_path in log_paths:
+                if log_path.exists():
+                    log_analysis["log_files_found"].append(str(log_path))
+                    await self._analyze_log_directory(log_path, log_analysis)
+
+            if not log_analysis["log_files_found"]:
+                console.print("ℹ️  No log files found in standard locations")
+            else:
+                console.print(f"✅ Found logs in {len(log_analysis['log_files_found'])} location(s)")
+
+        except Exception as e:
+            issue = f"Log analysis failed: {str(e)}"
+            self.issues.append(issue)
+            console.print(f"❌ {issue}")
+
+        return log_analysis
+
+    async def _analyze_log_directory(self, log_path: Path, log_analysis: Dict[str, Any]):
+        """Analyze logs in a specific directory."""
+        try:
+            for log_file in log_path.glob("*.log"):
+                if log_file.stat().st_mtime > (datetime.now() - timedelta(hours=24)).timestamp():
+                    await self._parse_log_file(log_file, log_analysis)
+        except Exception as e:
+            self.warnings.append(f"Could not analyze logs in {log_path}: {str(e)}")
+
+    async def _parse_log_file(self, log_file: Path, log_analysis: Dict[str, Any]):
+        """Parse individual log file for issues."""
+        try:
+            with open(log_file, 'r') as f:
+                lines = f.readlines()[-100:]  # Last 100 lines
+                
+            for line in lines:
+                if "ERROR" in line:
+                    log_analysis["recent_errors"].append(line.strip())
+                elif "WARNING" in line:
+                    log_analysis["recent_warnings"].append(line.strip())
+
+        except Exception as e:
+            self.warnings.append(f"Could not parse {log_file}: {str(e)}")
+
+    async def _analyze_performance(self) -> Dict[str, Any]:
+        """Analyze system performance metrics."""
+        console.print("\n⚡ [yellow]Performance Analysis[/yellow]")
+        
+        performance = {
+            "response_times": {},
+            "throughput": {},
+            "resource_usage": {},
+        }
+
+        try:
+            # Test basic operations performance
+            start_time = datetime.now()
+            
+            # Test configuration loading
+            config_start = datetime.now()
+            _ = get_config()
+            config_time = (datetime.now() - config_start).total_seconds()
+            performance["response_times"]["config_load"] = config_time
+            
+            if config_time > 1.0:
+                self.warnings.append(f"Slow configuration loading: {config_time:.2f}s")
+            
+            console.print(f"📊 Configuration load time: {config_time:.3f}s")
+
+        except Exception as e:
+            issue = f"Performance analysis failed: {str(e)}"
+            self.issues.append(issue)
+            console.print(f"❌ {issue}")
+
+        return performance
+
+    def _generate_recommendations(self) -> List[str]:
+        """Generate actionable recommendations based on diagnosis."""
+        recommendations = []
+
+        if self.issues:
+            recommendations.append("🚨 Critical issues detected - immediate attention required")
+            
+            if any("Queue worker not running" in issue for issue in self.issues):
+                recommendations.append("• Restart queue worker: mcp-ticketer queue worker restart")
+                
+            if any("failure rate" in issue.lower() for issue in self.issues):
+                recommendations.append("• Check queue system logs for error patterns")
+                recommendations.append("• Consider clearing failed queue items: mcp-ticketer queue clear --failed")
+                
+            if any("No adapters configured" in issue for issue in self.issues):
+                recommendations.append("• Configure at least one adapter: mcp-ticketer init-aitrackdown")
+
+        if self.warnings:
+            recommendations.append("⚠️  Warnings detected - monitoring recommended")
+
+        if not self.issues and not self.warnings:
+            recommendations.append("✅ System appears healthy - no immediate action required")
+
+        return recommendations
+
+    def _display_diagnosis_summary(self, report: Dict[str, Any]):
+        """Display a comprehensive diagnosis summary."""
+        console.print("\n" + "=" * 60)
+        console.print("📋 [bold green]DIAGNOSIS SUMMARY[/bold green]")
+        console.print("=" * 60)
+
+        # Overall health status
+        if self.issues:
+            status_color = "red"
+            status_text = "CRITICAL"
+            status_icon = "🚨"
+        elif self.warnings:
+            status_color = "yellow"
+            status_text = "WARNING"
+            status_icon = "⚠️"
+        else:
+            status_color = "green"
+            status_text = "HEALTHY"
+            status_icon = "✅"
+
+        console.print(f"\n{status_icon} [bold {status_color}]System Status: {status_text}[/bold {status_color}]")
+
+        # Statistics
+        stats_table = Table(show_header=True, header_style="bold blue")
+        stats_table.add_column("Component")
+        stats_table.add_column("Status")
+        stats_table.add_column("Details")
+
+        # Add component statuses
+        config_status = "✅ OK" if not any("configuration" in issue.lower() for issue in self.issues) else "❌ FAILED"
+        stats_table.add_row("Configuration", config_status, f"{report['configuration']['adapters_configured']} adapters")
+
+        queue_health = report['queue_system']['health_score']
+        queue_status = "✅ OK" if queue_health > 80 else "⚠️  DEGRADED" if queue_health > 50 else "❌ FAILED"
+        stats_table.add_row("Queue System", queue_status, f"{queue_health}/100 health score")
+
+        adapter_stats = report['adapters']
+        adapter_status = "✅ OK" if adapter_stats['failed_adapters'] == 0 else "❌ FAILED"
+        stats_table.add_row("Adapters", adapter_status, f"{adapter_stats['healthy_adapters']}/{adapter_stats['total_adapters']} healthy")
+
+        console.print(stats_table)
+
+        # Issues and recommendations
+        if self.issues:
+            console.print(f"\n🚨 [bold red]Critical Issues ({len(self.issues)}):[/bold red]")
+            for issue in self.issues:
+                console.print(f"  • {issue}")
+
+        if self.warnings:
+            console.print(f"\n⚠️  [bold yellow]Warnings ({len(self.warnings)}):[/bold yellow]")
+            for warning in self.warnings:
+                console.print(f"  • {warning}")
+
+        if report['recommendations']:
+            console.print(f"\n💡 [bold blue]Recommendations:[/bold blue]")
+            for rec in report['recommendations']:
+                console.print(f"  {rec}")
+
+        console.print(f"\n📊 [bold]Summary:[/bold] {len(self.successes)} successes, {len(self.warnings)} warnings, {len(self.issues)} critical issues")
+
+
+async def run_diagnostics(
+    output_file: Optional[str] = None,
+    json_output: bool = False,
+) -> None:
+    """Run comprehensive system diagnostics."""
+    diagnostics = SystemDiagnostics()
+    report = await diagnostics.run_full_diagnosis()
+
+    if output_file:
+        with open(output_file, 'w') as f:
+            json.dump(report, f, indent=2)
+        console.print(f"\n📄 Full report saved to: {output_file}")
+
+    if json_output:
+        console.print("\n" + json.dumps(report, indent=2))
+
+    # Return exit code based on issues
+    if diagnostics.issues:
+        raise typer.Exit(1)  # Critical issues found
+    elif diagnostics.warnings:
+        raise typer.Exit(2)  # Warnings found
+    else:
+        raise typer.Exit(0)  # All good

{mcp_ticketer-0.1.28 → mcp_ticketer-0.1.29}/src/mcp_ticketer/cli/main.py

@@ -22,6 +22,7 @@ from ..queue.ticket_registry import TicketRegistry
 # Import adapters module to trigger registration
 import mcp_ticketer.adapters  # noqa: F401
 from .configure import configure_wizard, set_adapter_config, show_current_config
+from .diagnostics import run_diagnostics
 from .discover import app as discover_app
 from .migrate_config import migrate_config_command
 from .queue_commands import app as queue_app
@@ -1260,6 +1261,48 @@ app.add_typer(queue_app, name="queue")
 # Add discover command to main app
 app.add_typer(discover_app, name="discover")
 
+# Add diagnostics command
+@app.command()
+def diagnose(
+    output_file: Optional[str] = typer.Option(None, "--output", "-o", help="Save full report to file"),
+    json_output: bool = typer.Option(False, "--json", help="Output report in JSON format"),
+    simple: bool = typer.Option(False, "--simple", help="Use simple diagnostics (no heavy dependencies)"),
+) -> None:
+    """Run comprehensive system diagnostics and health check."""
+    if simple:
+        from .simple_health import simple_diagnose
+        report = simple_diagnose()
+        if output_file:
+            import json
+            with open(output_file, 'w') as f:
+                json.dump(report, f, indent=2)
+            console.print(f"\n📄 Report saved to: {output_file}")
+        if json_output:
+            import json
+            console.print("\n" + json.dumps(report, indent=2))
+        if report["issues"]:
+            raise typer.Exit(1)
+    else:
+        try:
+            asyncio.run(run_diagnostics(output_file=output_file, json_output=json_output))
+        except Exception as e:
+            console.print(f"⚠️  Full diagnostics failed: {e}")
+            console.print("🔄 Falling back to simple diagnostics...")
+            from .simple_health import simple_diagnose
+            report = simple_diagnose()
+            if report["issues"]:
+                raise typer.Exit(1)
+
+
+@app.command()
+def health() -> None:
+    """Quick health check - shows system status summary."""
+    from .simple_health import simple_health_check
+
+    result = simple_health_check()
+    if result != 0:
+        raise typer.Exit(result)
+
 # Create MCP configuration command group
 mcp_app = typer.Typer(
     name="mcp",