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

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

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [0.1.30] - 2025-10-24
+
+### Fixed
+- **Diagnostics System**: Improved fallback mode handling for missing dependencies
+  - Fixed initialization order for warnings/issues lists
+  - Enhanced mock object detection for configuration and queue systems
+  - Better graceful degradation when PyYAML or other dependencies are missing
+  - Improved environment variable detection in fallback mode
+  - More informative status reporting for degraded components
+
+### Enhanced
+- **Error Handling**: More robust handling of import failures and missing dependencies
+- **User Experience**: Clearer distinction between critical failures and degraded functionality
+- **Fallback Diagnostics**: Better information gathering even when full system is unavailable
+
 ## [0.1.29] - 2025-10-24
 
 ### Added

mcp_ticketer-0.1.31/DIAGNOSTICS_FEATURE.md

@@ -0,0 +1,301 @@
+# 🔍 MCP Ticketer Diagnostics & Self-Diagnosis System
+
+**Version**: 0.1.28+  
+**Status**: ✅ **IMPLEMENTED & DEPLOYED**  
+**Date**: 2025-10-24
+
+## 🎯 Overview
+
+The MCP Ticketer diagnostics system provides comprehensive health monitoring and self-diagnosis capabilities for both users and AI agents. This addresses the critical need for system visibility when troubleshooting issues like the "60% queue failure rate" problem.
+
+## 🚀 Features Implemented
+
+### 1. **CLI Health Commands**
+
+#### Quick Health Check
+```bash
+mcp-ticketer health
+```
+
+**Output Example:**
+```
+🏥 MCP Ticketer Quick Health Check
+==================================================
+✅ Python: 3.13.7
+✅ Configuration: Found .aitrackdown
+✅ Aitrackdown: Directory exists at .aitrackdown
+ℹ️  Aitrackdown: 46 tickets found
+✅ Environment: 2 adapter variables configured
+  • LINEAR_API_KEY
+  • GITHUB_TOKEN
+✅ Installation: mcp-ticketer 0.1.28 installed
+⚠️  Queue System: Could not check status - import error
+
+🎉 System appears healthy!
+💡 For detailed diagnosis, run: mcp-ticketer diagnose
+```
+
+#### Comprehensive Diagnosis
+```bash
+mcp-ticketer diagnose                    # Full diagnosis
+mcp-ticketer diagnose --simple           # Simple diagnosis (no heavy dependencies)
+mcp-ticketer diagnose --output report.json  # Save to file
+mcp-ticketer diagnose --json             # JSON output
+```
+
+**Output Example:**
+```
+🔍 MCP Ticketer Simple Diagnosis
+============================================================
+
+📋 Basic System Check
+✅ Python 3.13.7
+✅ mcp-ticketer 0.1.28 installed
+
+📋 Configuration Check
+ℹ️  No configuration files (using defaults)
+✅ 2 adapter environment variables configured
+
+============================================================
+📋 DIAGNOSIS SUMMARY
+============================================================
+
+💡 Recommendations:
+  ✅ System appears healthy
+```
+
+### 2. **MCP Diagnostic Tools**
+
+Two new MCP tools are available for AI agents:
+
+#### `system_health`
+- **Purpose**: Quick system health check
+- **Parameters**: None
+- **Returns**: Configuration status, queue worker status, failure rates
+- **Use Case**: AI agents can quickly check if the system is operational
+
+#### `system_diagnose`
+- **Purpose**: Comprehensive system diagnostics
+- **Parameters**: 
+  - `include_logs` (boolean, optional): Include recent log analysis
+- **Returns**: Detailed analysis of all components with recommendations
+- **Use Case**: Deep troubleshooting when issues are detected
+
+### 3. **Intelligent Fallback System**
+
+The diagnostics system includes multiple fallback mechanisms:
+
+1. **Simple Health Check**: Works without heavy dependencies (PyYAML, etc.)
+2. **Graceful Degradation**: Falls back to simple diagnostics if full system fails
+3. **Import Protection**: Handles missing dependencies gracefully
+4. **Error Recovery**: Continues diagnosis even if individual components fail
+
+## 🔧 Technical Implementation
+
+### Architecture
+
+```
+src/mcp_ticketer/cli/
+├── diagnostics.py      # Full diagnostics system
+├── simple_health.py    # Lightweight fallback diagnostics
+└── main.py            # CLI command integration
+
+src/mcp_ticketer/mcp/
+└── server.py          # MCP tool integration
+```
+
+### Key Components
+
+#### 1. **SystemDiagnostics Class** (`diagnostics.py`)
+- Comprehensive system analysis
+- Configuration validation
+- Adapter functionality testing
+- Queue system health monitoring
+- Log analysis
+- Performance metrics
+- Actionable recommendations
+
+#### 2. **Simple Health Functions** (`simple_health.py`)
+- Lightweight checks without heavy dependencies
+- Basic configuration detection
+- Environment variable validation
+- Installation verification
+- Fallback for when full diagnostics fail
+
+#### 3. **MCP Integration** (`server.py`)
+- Two new MCP tools: `system_health` and `system_diagnose`
+- JSON-RPC compatible responses
+- Error handling and status reporting
+- Integration with existing MCP server
+
+### Diagnostic Categories
+
+#### ✅ **Configuration Analysis**
+- Adapter configuration validation
+- Credential verification (where available)
+- Default adapter detection
+- Configuration file discovery
+
+#### ⚡ **Queue System Health**
+- Worker process status
+- Queue statistics and failure rates
+- Health score calculation (0-100)
+- Performance metrics
+
+#### 🔌 **Adapter Functionality**
+- Adapter initialization testing
+- Basic functionality verification (non-destructive)
+- Credential validation
+- Error reporting
+
+#### 📝 **Log Analysis** (Full diagnostics only)
+- Recent error detection
+- Warning pattern analysis
+- Log file discovery
+- Issue correlation
+
+#### 📊 **Performance Metrics**
+- Response time measurement
+- Resource usage analysis
+- Throughput assessment
+- Bottleneck identification
+
+## 🎯 Use Cases
+
+### For Users
+
+1. **Quick System Check**
+   ```bash
+   mcp-ticketer health
+   ```
+   - Verify installation
+   - Check basic configuration
+   - Identify obvious issues
+
+2. **Troubleshooting Issues**
+   ```bash
+   mcp-ticketer diagnose
+   ```
+   - Comprehensive system analysis
+   - Detailed error reporting
+   - Actionable recommendations
+
+3. **CI/CD Integration**
+   ```bash
+   mcp-ticketer health || exit 1
+   ```
+   - Automated health checks
+   - Build pipeline validation
+   - Deployment verification
+
+### For AI Agents
+
+1. **System Status Monitoring**
+   ```json
+   {
+     "tool": "system_health",
+     "arguments": {}
+   }
+   ```
+   - Quick operational status
+   - Failure rate monitoring
+   - Component health overview
+
+2. **Issue Investigation**
+   ```json
+   {
+     "tool": "system_diagnose", 
+     "arguments": {"include_logs": true}
+   }
+   ```
+   - Deep system analysis
+   - Root cause identification
+   - Comprehensive reporting
+
+3. **Proactive Monitoring**
+   - Regular health checks
+   - Early issue detection
+   - Automated troubleshooting
+
+## 📈 Benefits
+
+### 🔍 **Visibility**
+- Clear system status reporting
+- Component-level health monitoring
+- Performance metrics tracking
+- Issue identification and categorization
+
+### 🚀 **Reliability**
+- Proactive issue detection
+- Automated health monitoring
+- Self-healing recommendations
+- Graceful degradation handling
+
+### 🤖 **AI Agent Integration**
+- Native MCP tool support
+- Structured diagnostic data
+- Actionable recommendations
+- Automated troubleshooting workflows
+
+### 👥 **User Experience**
+- Simple command-line interface
+- Rich, colorized output
+- Multiple output formats (text, JSON)
+- Progressive disclosure (health → diagnose)
+
+## 🔄 Exit Codes
+
+The diagnostic commands use standard exit codes for automation:
+
+- **0**: System healthy, no issues detected
+- **1**: Critical issues found, immediate attention required
+- **2**: Warnings detected, monitoring recommended
+
+## 🎉 Impact on Original Issue
+
+This diagnostics system directly addresses the original problem:
+
+> "The mcp-ticketer system itself is experiencing critical issues! This is actually very revealing - the ticketing system has a 60% failure rate"
+
+### Before Diagnostics
+- ❌ No visibility into system health
+- ❌ No way to identify root causes
+- ❌ Manual investigation required
+- ❌ AI agents couldn't self-diagnose
+
+### After Diagnostics
+- ✅ **Instant system health visibility**
+- ✅ **Automated issue detection**
+- ✅ **AI agent self-diagnosis capability**
+- ✅ **Actionable recommendations**
+- ✅ **Proactive monitoring**
+
+### Example Diagnostic Output for Queue Issues
+```
+❌ Queue Health: High failure rate 60.0% (12/20)
+❌ Queue Worker: Not running
+
+💡 Recommendations:
+• Restart queue worker: mcp-ticketer queue worker restart
+• Check queue system logs for error patterns
+• Consider clearing failed queue items: mcp-ticketer queue clear --failed
+```
+
+## 🚀 Future Enhancements
+
+1. **Metrics Dashboard**: Web-based health monitoring
+2. **Alert Integration**: Slack/email notifications for critical issues
+3. **Historical Tracking**: Trend analysis and performance history
+4. **Auto-Remediation**: Automated fixing of common issues
+5. **Custom Health Checks**: User-defined diagnostic rules
+
+## 📚 Documentation
+
+- **User Guide**: See `mcp-ticketer health --help` and `mcp-ticketer diagnose --help`
+- **MCP Integration**: Tools available as `system_health` and `system_diagnose`
+- **API Reference**: See `src/mcp_ticketer/cli/diagnostics.py` for implementation details
+- **Examples**: See `test_diagnostics_mcp.py` for MCP usage examples
+
+---
+
+**The diagnostics system transforms MCP Ticketer from a "black box" into a transparent, self-monitoring system that both users and AI agents can easily understand and troubleshoot.** 🎯

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 0.1.29
+Version: 0.1.31
 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.29 → mcp_ticketer-0.1.31}/src/mcp_ticketer/__version__.py

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

{mcp_ticketer-0.1.29 → mcp_ticketer-0.1.31}/src/mcp_ticketer/cli/diagnostics.py

@@ -15,22 +15,58 @@ 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
+def safe_import_config():
+    """Safely import configuration with fallback."""
+    try:
+        from ..core.config import get_config
+        return get_config
+    except ImportError:
+        # Create a minimal config fallback
+        class MockConfig:
+            def get_enabled_adapters(self):
+                return {}
+
+            @property
+            def default_adapter(self):
+                return "aitrackdown"
+
+        def get_config():
+            return MockConfig()
+
+        return get_config
+
+def safe_import_registry():
+    """Safely import adapter registry with fallback."""
+    try:
+        from ..core.registry import AdapterRegistry
+        return AdapterRegistry
+    except ImportError:
+        class MockRegistry:
+            @staticmethod
+            def get_adapter(adapter_type):
+                raise ImportError(f"Adapter {adapter_type} not available")
+
+        return MockRegistry
+
+def safe_import_queue_manager():
+    """Safely import queue manager with fallback."""
+    try:
+        from ..queue.manager import QueueManager
+        return QueueManager
+    except ImportError:
+        class MockQueueManager:
+            def get_worker_status(self):
+                return {"running": False, "pid": None}
+
+            def get_queue_stats(self):
+                return {"total": 0, "failed": 0}
+
+        return MockQueueManager
+
+# Initialize with safe imports
+get_config = safe_import_config()
+AdapterRegistry = safe_import_registry()
+QueueManager = safe_import_queue_manager()
 
 console = Console()
 logger = logging.getLogger(__name__)
@@ -40,22 +76,37 @@ class SystemDiagnostics:
     """Comprehensive system diagnostics and health reporting."""
 
     def __init__(self):
+        # Initialize lists first
+        self.issues = []
+        self.warnings = []
+        self.successes = []
+
         try:
             self.config = get_config()
+            # Check if this is a mock config
+            if hasattr(self.config, '__class__') and 'Mock' in self.config.__class__.__name__:
+                self.config_available = False
+                self.warnings.append("Configuration system using fallback mode")
+            else:
+                self.config_available = True
         except Exception as e:
             self.config = None
+            self.config_available = False
             console.print(f"⚠️  Could not load configuration: {e}")
 
         try:
-            self.queue_manager = QueueManager() if QueueManager else None
+            self.queue_manager = QueueManager()
+            # Check if this is a mock queue manager
+            if hasattr(self.queue_manager, '__class__') and 'Mock' in self.queue_manager.__class__.__name__:
+                self.queue_available = False
+                self.warnings.append("Queue system using fallback mode")
+            else:
+                self.queue_available = True
         except Exception as e:
             self.queue_manager = None
+            self.queue_available = False
             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]")
@@ -112,6 +163,33 @@ class SystemDiagnostics:
             console.print(f"❌ {issue}")
             return config_status
 
+        if not self.config_available:
+            warning = "Configuration system in fallback mode - limited functionality"
+            config_status["issues"].append(warning)
+            config_status["status"] = "degraded"
+            self.warnings.append(warning)
+            console.print(f"⚠️  {warning}")
+
+            # Try to detect adapters from environment variables
+            import os
+            env_adapters = []
+            if os.getenv("LINEAR_API_KEY"):
+                env_adapters.append("linear")
+            if os.getenv("GITHUB_TOKEN"):
+                env_adapters.append("github")
+            if os.getenv("JIRA_SERVER"):
+                env_adapters.append("jira")
+
+            config_status["adapters_configured"] = len(env_adapters)
+            config_status["default_adapter"] = "aitrackdown"
+
+            if env_adapters:
+                console.print(f"ℹ️  Detected {len(env_adapters)} adapter(s) from environment: {', '.join(env_adapters)}")
+            else:
+                console.print("ℹ️  No adapter environment variables detected, using aitrackdown")
+
+            return config_status
+
         try:
             # Check adapter configurations
             adapters = self.config.get_enabled_adapters()
@@ -238,6 +316,15 @@ class SystemDiagnostics:
         }
 
         try:
+            if not self.queue_available:
+                warning = "Queue system in fallback mode - limited functionality"
+                self.warnings.append(warning)
+                console.print(f"⚠️  {warning}")
+                queue_status["worker_running"] = False
+                queue_status["worker_pid"] = None
+                queue_status["health_score"] = 50  # Degraded but not critical
+                return queue_status
+
             # Check worker status
             worker_status = self.queue_manager.get_worker_status()
             queue_status["worker_running"] = worker_status.get("running", False)

{mcp_ticketer-0.1.29 → mcp_ticketer-0.1.31}/src/mcp_ticketer/core/config.py

@@ -283,6 +283,10 @@ class ConfigurationManager:
             # Load from first available config file
             config_data = self._load_config_file(self._config_file_paths[0])
             logger.info(f"Loaded configuration from: {self._config_file_paths[0]}")
+        else:
+            # No config file found - try environment discovery
+            logger.info("No configuration file found, attempting environment discovery")
+            config_data = self._discover_from_environment()
 
         # Parse adapter configurations
         if "adapters" in config_data:
@@ -328,6 +332,95 @@ class ConfigurationManager:
             logger.error(f"Error loading config file {config_path}: {e}")
             return {}
 
+    def _discover_from_environment(self) -> dict[str, Any]:
+        """Discover configuration from environment variables."""
+        try:
+            from .env_discovery import EnvironmentDiscovery
+
+            discovery = EnvironmentDiscovery()
+            discovered = discovery.discover_all()
+
+            if not discovered.adapters:
+                logger.info("No adapters discovered from environment variables")
+                # Return minimal config with aitrackdown as fallback
+                return {
+                    "adapters": {
+                        "aitrackdown": {
+                            "type": "aitrackdown",
+                            "enabled": True,
+                            "base_path": str(Path.home() / ".mcp-ticketer" / ".aitrackdown")
+                        }
+                    },
+                    "default_adapter": "aitrackdown"
+                }
+
+            # Convert discovered adapters to config format
+            config_data = {
+                "adapters": {},
+                "default_adapter": None
+            }
+
+            for adapter in discovered.adapters:
+                adapter_config = {
+                    "type": adapter.type.value,
+                    "enabled": True
+                }
+
+                # Add adapter-specific configuration
+                if adapter.type.value == "linear":
+                    adapter_config.update({
+                        "api_key": adapter.credentials.get("api_key"),
+                        "team_id": adapter.credentials.get("team_id"),
+                        "project_id": adapter.credentials.get("project_id")
+                    })
+                elif adapter.type.value == "github":
+                    adapter_config.update({
+                        "token": adapter.credentials.get("token"),
+                        "repo": adapter.credentials.get("repo"),
+                        "owner": adapter.credentials.get("owner")
+                    })
+                elif adapter.type.value == "jira":
+                    adapter_config.update({
+                        "server": adapter.credentials.get("server"),
+                        "email": adapter.credentials.get("email"),
+                        "api_token": adapter.credentials.get("api_token"),
+                        "project_key": adapter.credentials.get("project_key")
+                    })
+
+                config_data["adapters"][adapter.name] = adapter_config
+
+                # Set first discovered adapter as default
+                if config_data["default_adapter"] is None:
+                    config_data["default_adapter"] = adapter.name
+
+            logger.info(f"Discovered {len(config_data['adapters'])} adapter(s) from environment")
+            return config_data
+
+        except ImportError:
+            logger.warning("Environment discovery not available, using aitrackdown fallback")
+            return {
+                "adapters": {
+                    "aitrackdown": {
+                        "type": "aitrackdown",
+                        "enabled": True,
+                        "base_path": str(Path.home() / ".mcp-ticketer" / ".aitrackdown")
+                    }
+                },
+                "default_adapter": "aitrackdown"
+            }
+        except Exception as e:
+            logger.error(f"Environment discovery failed: {e}")
+            return {
+                "adapters": {
+                    "aitrackdown": {
+                        "type": "aitrackdown",
+                        "enabled": True,
+                        "base_path": str(Path.home() / ".mcp-ticketer" / ".aitrackdown")
+                    }
+                },
+                "default_adapter": "aitrackdown"
+            }
+
     def get_config(self) -> AppConfig:
         """Get the current configuration."""
         if self._config is None:

{mcp_ticketer-0.1.29 → mcp_ticketer-0.1.31}/src/mcp_ticketer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-ticketer
-Version: 0.1.29
+Version: 0.1.31
 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.29 → mcp_ticketer-0.1.31}/src/mcp_ticketer.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ CODE_STRUCTURE.md
 CONFIG_RESOLUTION_FIX.md
 CONTRIBUTING.md
 CREDENTIAL_VALIDATION_FIX.md
+DIAGNOSTICS_FEATURE.md
 ENV_DISCOVERY_COMPLETE.md
 FIX_SUMMARY.md
 HIERARCHY_IMPLEMENTATION_SUMMARY.md