claude-mpm 4.0.28__py3-none-any.whl → 4.0.30__py3-none-any.whl

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -0,0 +1,283 @@
+"""
+Reporter for formatting and displaying diagnostic results.
+
+WHY: Provide clear, actionable output from diagnostic checks with proper
+formatting for terminal display and JSON export.
+"""
+
+import json
+import sys
+from typing import Dict, List, Optional
+
+from .models import DiagnosticResult, DiagnosticStatus, DiagnosticSummary
+
+
+class DoctorReporter:
+    """Format and display diagnostic results.
+    
+    WHY: Consistent, user-friendly output that clearly shows system health
+    status and provides actionable fixes for any issues.
+    """
+    
+    # Status symbols and colors
+    STATUS_SYMBOLS = {
+        DiagnosticStatus.OK: "✅",
+        DiagnosticStatus.WARNING: "⚠️ ",
+        DiagnosticStatus.ERROR: "❌",
+        DiagnosticStatus.SKIPPED: "⏭️ "
+    }
+    
+    # ANSI color codes
+    COLORS = {
+        "reset": "\033[0m",
+        "bold": "\033[1m",
+        "red": "\033[91m",
+        "green": "\033[92m",
+        "yellow": "\033[93m",
+        "blue": "\033[94m",
+        "gray": "\033[90m"
+    }
+    
+    def __init__(self, use_color: bool = True, verbose: bool = False):
+        """Initialize reporter.
+        
+        Args:
+            use_color: Whether to use ANSI color codes
+            verbose: Whether to include detailed information
+        """
+        self.use_color = use_color and sys.stdout.isatty()
+        self.verbose = verbose
+    
+    def report(self, summary: DiagnosticSummary, format: str = "terminal"):
+        """Generate and output diagnostic report.
+        
+        Args:
+            summary: DiagnosticSummary with all results
+            format: Output format ("terminal", "json", "markdown")
+        """
+        if format == "json":
+            self._report_json(summary)
+        elif format == "markdown":
+            self._report_markdown(summary)
+        else:
+            self._report_terminal(summary)
+    
+    def _report_terminal(self, summary: DiagnosticSummary):
+        """Generate terminal-formatted report."""
+        # Header
+        self._print_header()
+        
+        # Results by category
+        for result in summary.results:
+            self._print_result(result)
+        
+        # Summary
+        self._print_summary(summary)
+        
+        # Fix suggestions
+        self._print_fixes(summary)
+    
+    def _print_header(self):
+        """Print report header."""
+        print()
+        print(self._color("Claude MPM Doctor Report", "bold"))
+        print("=" * 40)
+        print()
+    
+    def _print_result(self, result: DiagnosticResult, indent: int = 0):
+        """Print a single diagnostic result."""
+        indent_str = "  " * indent
+        
+        # Status symbol and category
+        symbol = self.STATUS_SYMBOLS.get(result.status, "?")
+        color = self._get_status_color(result.status)
+        
+        # Main result line
+        line = f"{indent_str}{symbol} {result.category}: "
+        
+        if result.status == DiagnosticStatus.OK:
+            line += self._color("OK", color)
+        elif result.status == DiagnosticStatus.WARNING:
+            line += self._color("Warning", color)
+        elif result.status == DiagnosticStatus.ERROR:
+            line += self._color("Error", color)
+        else:
+            line += self._color("Skipped", color)
+        
+        print(line)
+        
+        # Message
+        message_indent = "   " + indent_str
+        print(f"{message_indent}{result.message}")
+        
+        # Details (in verbose mode)
+        if self.verbose and result.details:
+            for key, value in result.details.items():
+                if key not in ["error", "issues"]:  # Skip complex fields
+                    print(f"{message_indent}{self._color(key, 'gray')}: {value}")
+        
+        # Fix suggestion
+        if result.fix_command:
+            fix_indent = "   " + indent_str
+            print(f"{fix_indent}{self._color('→ Fix:', 'blue')} Run '{result.fix_command}'")
+            if result.fix_description:
+                print(f"{fix_indent}  {self._color(result.fix_description, 'gray')}")
+        
+        # Sub-results (in verbose mode)
+        if self.verbose and result.sub_results:
+            for sub_result in result.sub_results:
+                self._print_result(sub_result, indent + 1)
+        
+        if indent == 0:
+            print()  # Extra line between top-level results
+    
+    def _print_summary(self, summary: DiagnosticSummary):
+        """Print summary statistics."""
+        print(self._color("─" * 40, "gray"))
+        
+        status_line = f"Summary: "
+        parts = []
+        
+        if summary.ok_count > 0:
+            parts.append(self._color(f"{summary.ok_count} OK", "green"))
+        if summary.warning_count > 0:
+            parts.append(self._color(f"{summary.warning_count} Warning{'s' if summary.warning_count != 1 else ''}", "yellow"))
+        if summary.error_count > 0:
+            parts.append(self._color(f"{summary.error_count} Error{'s' if summary.error_count != 1 else ''}", "red"))
+        if summary.skipped_count > 0:
+            parts.append(self._color(f"{summary.skipped_count} Skipped", "gray"))
+        
+        status_line += " | ".join(parts)
+        print(status_line)
+        
+        # Overall health
+        overall = summary.overall_status
+        if overall == DiagnosticStatus.OK:
+            print(self._color("\n✅ System is healthy!", "green"))
+        elif overall == DiagnosticStatus.WARNING:
+            print(self._color("\n⚠️  System has minor issues that should be addressed.", "yellow"))
+        else:
+            print(self._color("\n❌ System has critical issues that need immediate attention!", "red"))
+    
+    def _print_fixes(self, summary: DiagnosticSummary):
+        """Print consolidated fix suggestions."""
+        fixes = []
+        
+        for result in summary.results:
+            if result.fix_command and result.has_issues:
+                fixes.append((result.category, result.fix_command, result.fix_description))
+        
+        if fixes:
+            print()
+            print(self._color("Suggested Fixes:", "bold"))
+            print(self._color("─" * 40, "gray"))
+            
+            for i, (category, command, description) in enumerate(fixes, 1):
+                print(f"{i}. {category}:")
+                print(f"   {self._color(command, 'blue')}")
+                if description:
+                    print(f"   {self._color(description, 'gray')}")
+                print()
+            
+            if self.verbose:
+                print(self._color("Run 'claude-mpm doctor --fix' to attempt automatic fixes", "gray"))
+            else:
+                print(self._color("Run 'claude-mpm doctor --verbose' for more details", "gray"))
+    
+    def _report_json(self, summary: DiagnosticSummary):
+        """Generate JSON-formatted report."""
+        output = summary.to_dict()
+        
+        # Add metadata
+        output["metadata"] = {
+            "tool": "claude-mpm doctor",
+            "version": self._get_version(),
+            "verbose": self.verbose
+        }
+        
+        # Add fix suggestions
+        fixes = []
+        for result in summary.results:
+            if result.fix_command and result.has_issues:
+                fixes.append({
+                    "category": result.category,
+                    "command": result.fix_command,
+                    "description": result.fix_description
+                })
+        output["fixes"] = fixes
+        
+        print(json.dumps(output, indent=2))
+    
+    def _report_markdown(self, summary: DiagnosticSummary):
+        """Generate Markdown-formatted report."""
+        print("# Claude MPM Doctor Report\n")
+        
+        # Summary table
+        print("## Summary\n")
+        print("| Status | Count |")
+        print("|--------|-------|")
+        print(f"| ✅ OK | {summary.ok_count} |")
+        print(f"| ⚠️  Warning | {summary.warning_count} |")
+        print(f"| ❌ Error | {summary.error_count} |")
+        print(f"| ⏭️  Skipped | {summary.skipped_count} |")
+        print()
+        
+        # Detailed results
+        print("## Diagnostic Results\n")
+        
+        for result in summary.results:
+            symbol = self.STATUS_SYMBOLS.get(result.status, "?")
+            print(f"### {symbol} {result.category}\n")
+            print(f"**Status:** {result.status.value}")
+            print(f"**Message:** {result.message}\n")
+            
+            if result.fix_command:
+                print(f"**Fix:** `{result.fix_command}`")
+                if result.fix_description:
+                    print(f"_{result.fix_description}_\n")
+            
+            if self.verbose and result.details:
+                print("**Details:**")
+                for key, value in result.details.items():
+                    print(f"- {key}: {value}")
+                print()
+        
+        # Fixes section
+        fixes = [(r.category, r.fix_command, r.fix_description) 
+                 for r in summary.results if r.fix_command and r.has_issues]
+        
+        if fixes:
+            print("## Suggested Fixes\n")
+            for category, command, description in fixes:
+                print(f"- **{category}:** `{command}`")
+                if description:
+                    print(f"  - {description}")
+            print()
+    
+    def _color(self, text: str, color: str) -> str:
+        """Apply color to text if colors are enabled."""
+        if not self.use_color:
+            return text
+        
+        color_code = self.COLORS.get(color, "")
+        reset_code = self.COLORS["reset"]
+        return f"{color_code}{text}{reset_code}"
+    
+    def _get_status_color(self, status: DiagnosticStatus) -> str:
+        """Get color for a status."""
+        color_map = {
+            DiagnosticStatus.OK: "green",
+            DiagnosticStatus.WARNING: "yellow",
+            DiagnosticStatus.ERROR: "red",
+            DiagnosticStatus.SKIPPED: "gray"
+        }
+        return color_map.get(status, "reset")
+    
+    def _get_version(self) -> str:
+        """Get claude-mpm version."""
+        try:
+            from ..version_service import VersionService
+            service = VersionService()
+            return service.get_version()
+        except Exception:
+            return "unknown"

claude_mpm/services/diagnostics/models.py

@@ -0,0 +1,120 @@
+"""
+Data models for the diagnostic system.
+
+WHY: Define clear data structures for diagnostic results to ensure
+consistency across all checks and reporting.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class DiagnosticStatus(Enum):
+    """Status levels for diagnostic results."""
+    OK = "ok"
+    WARNING = "warning"
+    ERROR = "error"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class DiagnosticResult:
+    """Result from a diagnostic check.
+    
+    WHY: Standardized result format ensures consistent reporting
+    and makes it easy to aggregate and display results.
+    """
+    category: str  # e.g., "Installation", "Agents", "MCP Server"
+    status: DiagnosticStatus
+    message: str
+    details: Dict[str, Any] = field(default_factory=dict)
+    fix_command: Optional[str] = None
+    fix_description: Optional[str] = None
+    sub_results: List['DiagnosticResult'] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "category": self.category,
+            "status": self.status.value,
+            "message": self.message,
+            "details": self.details,
+            "fix_command": self.fix_command,
+            "fix_description": self.fix_description,
+            "sub_results": [r.to_dict() for r in self.sub_results]
+        }
+    
+    @property
+    def has_issues(self) -> bool:
+        """Check if this result indicates any issues."""
+        return self.status in (DiagnosticStatus.WARNING, DiagnosticStatus.ERROR)
+    
+    @property
+    def severity_level(self) -> int:
+        """Get numeric severity level for sorting."""
+        severity_map = {
+            DiagnosticStatus.OK: 0,
+            DiagnosticStatus.SKIPPED: 1,
+            DiagnosticStatus.WARNING: 2,
+            DiagnosticStatus.ERROR: 3
+        }
+        return severity_map.get(self.status, 0)
+
+
+@dataclass
+class DiagnosticSummary:
+    """Summary of all diagnostic results.
+    
+    WHY: Provides a high-level overview of system health
+    and quick access to issues that need attention.
+    """
+    total_checks: int = 0
+    ok_count: int = 0
+    warning_count: int = 0
+    error_count: int = 0
+    skipped_count: int = 0
+    results: List[DiagnosticResult] = field(default_factory=list)
+    
+    def add_result(self, result: DiagnosticResult):
+        """Add a result to the summary."""
+        self.results.append(result)
+        self.total_checks += 1
+        
+        if result.status == DiagnosticStatus.OK:
+            self.ok_count += 1
+        elif result.status == DiagnosticStatus.WARNING:
+            self.warning_count += 1
+        elif result.status == DiagnosticStatus.ERROR:
+            self.error_count += 1
+        elif result.status == DiagnosticStatus.SKIPPED:
+            self.skipped_count += 1
+    
+    @property
+    def has_issues(self) -> bool:
+        """Check if there are any warnings or errors."""
+        return self.warning_count > 0 or self.error_count > 0
+    
+    @property
+    def overall_status(self) -> DiagnosticStatus:
+        """Get overall system status."""
+        if self.error_count > 0:
+            return DiagnosticStatus.ERROR
+        elif self.warning_count > 0:
+            return DiagnosticStatus.WARNING
+        else:
+            return DiagnosticStatus.OK
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "summary": {
+                "total_checks": self.total_checks,
+                "ok": self.ok_count,
+                "warnings": self.warning_count,
+                "errors": self.error_count,
+                "skipped": self.skipped_count,
+                "overall_status": self.overall_status.value
+            },
+            "results": [r.to_dict() for r in self.results]
+        }

claude_mpm/services/mcp_gateway/core/interfaces.py

@@ -413,7 +413,7 @@ class IMCPGateway(IMCPLifecycle):
     Main interface for MCP gateway implementation.
 
     Orchestrates tool registry, communication, and request handling.
-    Acts as a protocol bridge between Claude Desktop and internal tools.
+    Acts as a protocol bridge between Claude Code and internal tools.
     """
 
     @abstractmethod

claude_mpm/services/mcp_gateway/main.py

@@ -442,7 +442,7 @@ Examples:
   # Run with debug logging
   python -m claude_mpm.services.mcp_gateway.main --debug
 
-  # Run as MCP server for Claude Desktop
+  # Run as MCP server for Claude Code
   python -m claude_mpm.services.mcp_gateway.main --stdio
         """,
     )

claude_mpm/services/mcp_gateway/server/mcp_gateway.py

@@ -6,8 +6,8 @@ MCP protocol gateway using Anthropic's official MCP package.
 Handles stdio-based communication, request routing, and tool invocation.
 Acts as a bridge between Claude Code and internal tools.
 
-NOTE: MCP is ONLY for Claude Code - NOT for Claude Desktop.
-Claude Desktop uses a different system for agent deployment.
+NOTE: MCP is ONLY for Claude Code - NOT for Claude Code.
+Claude Code uses a different system for agent deployment.
 
 Part of ISS-0035: MCP Gateway Implementation - Core Gateway and Tool Registry
 """
@@ -339,7 +339,7 @@ class MCPGateway(BaseMCPService, IMCPGateway):
         to handle incoming requests from Claude Code.
 
         WHY: We use stdio (stdin/stdout) as it's the standard communication
-        method for MCP servers in Claude Desktop. This ensures compatibility
+        method for MCP servers in Claude Code. This ensures compatibility
         and allows the server to be launched as a subprocess.
         """
         try:

claude_mpm/services/mcp_gateway/server/stdio_handler.py

@@ -24,7 +24,7 @@ class StdioHandler(BaseMCPService, IMCPCommunication):
     STDIO-based communication handler for MCP.
 
     WHY: The MCP protocol uses stdio (stdin/stdout) for communication between
-    Claude Desktop and MCP servers. This handler manages the low-level
+    Claude Code and MCP servers. This handler manages the low-level
     message exchange, ensuring proper JSON-RPC formatting and error handling.
 
     DESIGN DECISIONS:

claude_mpm/services/mcp_gateway/server/stdio_server.py

@@ -3,7 +3,7 @@ Simplified MCP Stdio Server
 ============================
 
 A proper stdio-based MCP server that communicates via JSON-RPC over stdin/stdout.
-This server is spawned on-demand by Claude Desktop/Code and exits when the connection closes.
+This server is spawned on-demand by Claude Code/Code and exits when the connection closes.
 
 WHY: MCP servers should be simple stdio-based processes that Claude can spawn and control.
 They should NOT run as persistent background services with lock files.
@@ -45,7 +45,7 @@ def apply_backward_compatibility_patches():
     Apply backward compatibility patches for MCP protocol differences.
     
     This function patches the MCP Server to handle missing clientInfo
-    in initialize requests from older Claude Desktop versions.
+    in initialize requests from older Claude Code versions.
     """
     try:
         from mcp.server import Server
@@ -114,7 +114,7 @@ class SimpleMCPServer:
     A simple stdio-based MCP server implementation.
 
     WHY: This server follows the MCP specification for stdio communication,
-    making it compatible with Claude Desktop/Code's MCP client.
+    making it compatible with Claude Code/Code's MCP client.
 
     DESIGN DECISIONS:
     - No persistent state or lock files

claude_mpm/services/mcp_gateway/tools/ticket_tools.py

@@ -3,9 +3,9 @@ MCP Tool Adapters for aitrackdown Ticket Management
 ====================================================
 
 Provides MCP tool wrappers for common aitrackdown operations, enabling
-ticket management through Claude Desktop's MCP interface.
+ticket management through Claude Code's MCP interface.
 
-WHY: These tools allow Claude Desktop to interact with aitrackdown for
+WHY: These tools allow Claude Code to interact with aitrackdown for
 ticket management without requiring direct CLI access, providing a
 seamless integration experience.
 

claude_mpm/services/memory/__init__.py

@@ -9,9 +9,11 @@ This module provides memory management services including:
 from .builder import MemoryBuilder
 from .optimizer import MemoryOptimizer
 from .router import MemoryRouter
+from .indexed_memory import IndexedMemoryService
 
 __all__ = [
     "MemoryBuilder",
     "MemoryRouter",
     "MemoryOptimizer",
+    "IndexedMemoryService",
 ]

claude_mpm/services/socketio/handlers/connection.py

@@ -27,59 +27,53 @@ def timeout_handler(timeout_seconds: float = 5.0):
     """
     def decorator(func: Callable) -> Callable:
         @functools.wraps(func)
-        async def wrapper(self, *args, **kwargs):
+        async def wrapper(*args, **kwargs):
             handler_name = func.__name__
             start_time = time.time()
             
             try:
                 # Create a task with timeout
                 result = await asyncio.wait_for(
-                    func(self, *args, **kwargs),
+                    func(*args, **kwargs),
                     timeout=timeout_seconds
                 )
                 
                 elapsed = time.time() - start_time
                 if elapsed > timeout_seconds * 0.8:  # Warn if close to timeout
-                    self.logger.warning(
-                        f"⚠️ Handler {handler_name} took {elapsed:.2f}s "
-                        f"(close to {timeout_seconds}s timeout)"
-                    )
+                    # Try to get logger from closure scope or fallback to print
+                    try:
+                        import logging
+                        logger = logging.getLogger(__name__)
+                        logger.warning(
+                            f"⚠️ Handler {handler_name} took {elapsed:.2f}s "
+                            f"(close to {timeout_seconds}s timeout)"
+                        )
+                    except:
+                        print(f"⚠️ Handler {handler_name} took {elapsed:.2f}s (close to {timeout_seconds}s timeout)")
                     
                 return result
                 
             except asyncio.TimeoutError:
                 elapsed = time.time() - start_time
-                self.logger.error(
-                    f"❌ Handler {handler_name} timed out after {elapsed:.2f}s"
-                )
-                
-                # Try to send error response to client if we have their sid
-                if args and isinstance(args[0], str):  # First arg is usually sid
-                    sid = args[0]
-                    try:
-                        # Use a short timeout for error response
-                        await asyncio.wait_for(
-                            self.emit_to_client(
-                                sid, 
-                                "error",
-                                {
-                                    "message": f"Handler {handler_name} timed out",
-                                    "handler": handler_name,
-                                    "timeout": timeout_seconds
-                                }
-                            ),
-                            timeout=1.0
-                        )
-                    except:
-                        pass  # Best effort error notification
+                # Try to get logger from closure scope or fallback to print
+                try:
+                    import logging
+                    logger = logging.getLogger(__name__)
+                    logger.error(f"❌ Handler {handler_name} timed out after {elapsed:.2f}s")
+                except:
+                    print(f"❌ Handler {handler_name} timed out after {elapsed:.2f}s")
                         
                 return None
                 
             except Exception as e:
                 elapsed = time.time() - start_time
-                self.logger.error(
-                    f"❌ Handler {handler_name} failed after {elapsed:.2f}s: {e}"
-                )
+                # Try to get logger from closure scope or fallback to print
+                try:
+                    import logging
+                    logger = logging.getLogger(__name__)
+                    logger.error(f"❌ Handler {handler_name} failed after {elapsed:.2f}s: {e}")
+                except:
+                    print(f"❌ Handler {handler_name} failed after {elapsed:.2f}s: {e}")
                 raise
                 
         return wrapper
@@ -325,7 +319,7 @@ class ConnectionEventHandler(BaseEventHandler):
 
         @self.sio.event
         @timeout_handler(timeout_seconds=3.0)
-        async def disconnect(sid):
+        async def disconnect(sid, *args):
             """Handle client disconnection.
 
             WHY: We need to clean up client tracking when they disconnect