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

{mcp_ticketer-0.1.29 → mcp_ticketer-0.1.30}/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.30/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.30}/PKG-INFO

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

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

{mcp_ticketer-0.1.29 → mcp_ticketer-0.1.30}/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.30}/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.30
 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.30}/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
@@ -53,6 +54,7 @@ test_codex_config.py
 test_comprehensive.py
 test_config_resolution.py
 test_credential_validation.py
+test_diagnostics_mcp.py
 test_error_handling.py
 test_github.py
 test_github_token.py

mcp_ticketer-0.1.30/test_diagnostics_mcp.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Test the new diagnostic MCP tools."""
+
+import asyncio
+import json
+import subprocess
+import sys
+import time
+from typing import Any, Dict
+
+
+async def test_mcp_tool(tool_name: str, arguments: Dict[str, Any] = None) -> Dict[str, Any]:
+    """Test an MCP tool by sending a JSON-RPC request."""
+    if arguments is None:
+        arguments = {}
+    
+    request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {
+            "name": tool_name,
+            "arguments": arguments
+        }
+    }
+    
+    # Start MCP server process
+    process = subprocess.Popen(
+        ["mcp-ticketer", "serve"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True
+    )
+    
+    try:
+        # Send request
+        request_json = json.dumps(request) + "\n"
+        stdout, stderr = process.communicate(input=request_json, timeout=10)
+        
+        if stderr:
+            print(f"Server stderr: {stderr}")
+        
+        # Parse response
+        if stdout.strip():
+            response = json.loads(stdout.strip())
+            return response
+        else:
+            return {"error": "No response from server"}
+            
+    except subprocess.TimeoutExpired:
+        process.kill()
+        return {"error": "Request timed out"}
+    except json.JSONDecodeError as e:
+        return {"error": f"Invalid JSON response: {e}"}
+    except Exception as e:
+        return {"error": f"Request failed: {e}"}
+    finally:
+        if process.poll() is None:
+            process.terminate()
+
+
+async def main():
+    """Test the diagnostic MCP tools."""
+    print("🔍 Testing MCP Diagnostic Tools")
+    print("=" * 50)
+    
+    # Test system_health tool
+    print("\n1. Testing system_health tool...")
+    health_response = await test_mcp_tool("system_health")
+    
+    if "error" in health_response:
+        print(f"❌ Health check failed: {health_response['error']}")
+    else:
+        print("✅ Health check completed")
+        if "result" in health_response:
+            content = health_response["result"].get("content", [])
+            if content and len(content) > 0:
+                print("📊 Health Status:")
+                print(content[0].get("text", "No text content"))
+            else:
+                print("⚠️  No content in response")
+        else:
+            print(f"Response: {json.dumps(health_response, indent=2)}")
+    
+    # Test system_diagnose tool
+    print("\n2. Testing system_diagnose tool...")
+    diagnose_response = await test_mcp_tool("system_diagnose", {"include_logs": False})
+    
+    if "error" in diagnose_response:
+        print(f"❌ Diagnosis failed: {diagnose_response['error']}")
+    else:
+        print("✅ Diagnosis completed")
+        if "result" in diagnose_response:
+            content = diagnose_response["result"].get("content", [])
+            if content and len(content) > 0:
+                print("📋 Diagnosis Report:")
+                text = content[0].get("text", "No text content")
+                # Show first 500 characters
+                print(text[:500] + ("..." if len(text) > 500 else ""))
+            else:
+                print("⚠️  No content in response")
+        else:
+            print(f"Response: {json.dumps(diagnose_response, indent=2)}")
+    
+    # Test tools/list to verify our tools are registered
+    print("\n3. Testing tools/list to verify diagnostic tools are registered...")
+    list_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/list",
+        "params": {}
+    }
+    
+    process = subprocess.Popen(
+        ["mcp-ticketer", "serve"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True
+    )
+    
+    try:
+        request_json = json.dumps(list_request) + "\n"
+        stdout, stderr = process.communicate(input=request_json, timeout=10)
+        
+        if stdout.strip():
+            response = json.loads(stdout.strip())
+            if "result" in response and "tools" in response["result"]:
+                tools = response["result"]["tools"]
+                diagnostic_tools = [t for t in tools if t["name"] in ["system_health", "system_diagnose"]]
+                
+                if diagnostic_tools:
+                    print(f"✅ Found {len(diagnostic_tools)} diagnostic tools:")
+                    for tool in diagnostic_tools:
+                        print(f"  • {tool['name']}: {tool['description']}")
+                else:
+                    print("❌ No diagnostic tools found in tools list")
+                    print(f"Available tools: {[t['name'] for t in tools]}")
+            else:
+                print(f"❌ Unexpected response: {response}")
+        else:
+            print("❌ No response from tools/list")
+            
+    except Exception as e:
+        print(f"❌ Tools list failed: {e}")
+    finally:
+        if process.poll() is None:
+            process.terminate()
+    
+    print("\n🎉 Diagnostic tools testing complete!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())