claude-mpm 4.4.3__py3-none-any.whl → 4.4.4__py3-none-any.whl

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -242,40 +242,74 @@ class DoctorReporter:
         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} |")
+        """Generate comprehensive Markdown-formatted report."""
+        import datetime
+
+        # Header with timestamp
+        print("# Claude MPM Doctor Report")
+        print(
+            f"\n**Generated:** {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
+        )
+        print(f"**Version:** {self._get_version()}\n")
+        print("---\n")
+
+        # System Overview
+        print("## System Overview\n")
+        self._print_system_overview_markdown(summary)
         print()
 
-        # Detailed results
-        print("## Diagnostic Results\n")
+        # Summary Statistics
+        print("## Summary Statistics\n")
+        print("| Status | Count | Percentage |")
+        print("|--------|-------|------------|")
+        total = (
+            summary.ok_count
+            + summary.warning_count
+            + summary.error_count
+            + summary.skipped_count
+        )
+        if total > 0:
+            print(f"| ✅ OK | {summary.ok_count} | {summary.ok_count*100//total}% |")
+            print(
+                f"| ⚠️  Warning | {summary.warning_count} | {summary.warning_count*100//total}% |"
+            )
+            print(
+                f"| ❌ Error | {summary.error_count} | {summary.error_count*100//total}% |"
+            )
+            print(
+                f"| ⏭️  Skipped | {summary.skipped_count} | {summary.skipped_count*100//total}% |"
+            )
+        print()
+
+        # Overall Health Status
+        overall = summary.overall_status
+        if overall == DiagnosticStatus.OK:
+            print("### 🎉 Overall Status: **Healthy**")
+            print("Your Claude MPM installation is functioning properly.\n")
+        elif overall == DiagnosticStatus.WARNING:
+            print("### ⚠️ Overall Status: **Needs Attention**")
+            print("Your installation has minor issues that should be addressed.\n")
+        else:
+            print("### ❌ Overall Status: **Critical Issues**")
+            print(
+                "Your installation has critical issues that need immediate attention.\n"
+            )
+
+        # MCP Services Status (if available)
+        self._print_mcp_services_markdown(summary)
 
+        # Installation Details
+        self._print_installation_details_markdown(summary)
+
+        # Detailed Diagnostic Results
+        print("## Detailed 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()
+            self._print_result_markdown(result)
 
-        # Fixes section
+        # Recommendations Section
+        self._print_recommendations_markdown(summary)
+
+        # Fixes Section
         fixes = [
             (r.category, r.fix_command, r.fix_description)
             for r in summary.results
@@ -283,13 +317,24 @@ class DoctorReporter:
         ]
 
         if fixes:
-            print("## Suggested Fixes\n")
+            print("## 🔧 Suggested Fixes\n")
+            print("Run these commands to fix identified issues:\n")
+            print("```bash")
             for category, command, description in fixes:
-                print(f"- **{category}:** `{command}`")
+                print(f"# Fix: {category}")
                 if description:
-                    print(f"  - {description}")
+                    print(f"# {description}")
+                print(command)
+                print()
+            print("```")
             print()
 
+        # Footer
+        print("---")
+        print(
+            "\n*For more information, run `claude-mpm doctor --verbose` or visit the [documentation](https://github.com/bobmatnyc/claude-mpm).*"
+        )
+
     def _color(self, text: str, color: str) -> str:
         """Apply color to text if colors are enabled."""
         if not self.use_color:
@@ -318,3 +363,185 @@ class DoctorReporter:
             return service.get_version()
         except Exception:
             return "unknown"
+
+    def _print_system_overview_markdown(self, summary: DiagnosticSummary):
+        """Print system overview in markdown format."""
+        import platform
+        import sys
+
+        print("| Component | Value |")
+        print("|-----------|-------|")
+        print(f"| Platform | {platform.system()} {platform.release()} |")
+        print(f"| Python Version | {sys.version.split()[0]} |")
+
+        # Extract key details from results
+        for result in summary.results:
+            if result.category == "Installation":
+                if result.details.get("claude_mpm_version"):
+                    print(
+                        f"| Claude MPM Version | {result.details['claude_mpm_version']} |"
+                    )
+                if result.details.get("installation_method"):
+                    print(
+                        f"| Installation Method | {result.details['installation_method']} |"
+                    )
+            elif result.category == "Claude Desktop":
+                if result.details.get("version"):
+                    print(f"| Claude Desktop | {result.details['version']} |")
+
+    def _print_mcp_services_markdown(self, summary: DiagnosticSummary):
+        """Print MCP services status table in markdown."""
+        # Find MCP Services result
+        mcp_services_result = None
+        for result in summary.results:
+            if result.category == "MCP Services":
+                mcp_services_result = result
+                break
+
+        if not mcp_services_result or not mcp_services_result.details.get("services"):
+            return
+
+        print("## MCP Services Status\n")
+        print("| Service | Installed | Accessible | Version | Status |")
+        print("|---------|-----------|------------|---------|--------|")
+
+        services = mcp_services_result.details.get("services", {})
+        for service_name, service_info in services.items():
+            installed = "✅" if service_info.get("installed") else "❌"
+            accessible = "✅" if service_info.get("accessible") else "❌"
+            version = service_info.get("version")
+            if version:
+                version = str(version)[:20]  # Truncate long versions
+            else:
+                version = "N/A"
+            status = service_info.get("status", "unknown")
+
+            # Map status to emoji
+            if status == "ok":
+                status_emoji = "✅"
+            elif status == "warning":
+                status_emoji = "⚠️"
+            elif status == "error":
+                status_emoji = "❌"
+            else:
+                status_emoji = "❓"
+
+            print(
+                f"| {service_name} | {installed} | {accessible} | {version} | {status_emoji} |"
+            )
+        print()
+
+    def _print_installation_details_markdown(self, summary: DiagnosticSummary):
+        """Print installation details in markdown."""
+        # Find installation result
+        install_result = None
+        for result in summary.results:
+            if result.category == "Installation":
+                install_result = result
+                break
+
+        if not install_result:
+            return
+
+        print("## Installation Details\n")
+
+        # Print sub-results if available
+        if install_result.sub_results and self.verbose:
+            for sub in install_result.sub_results:
+                if sub.category == "Python Version":
+                    print("### Python Environment")
+                    print(f"- **Version:** {sub.message}")
+                elif sub.category == "Installation Method":
+                    print("### Installation Method")
+                    print(f"- **Method:** {sub.message}")
+                    if sub.details.get("container_type"):
+                        print(f"- **Container:** {sub.details['container_type']}")
+                    if sub.details.get("pipx_metadata"):
+                        metadata = sub.details["pipx_metadata"]
+                        if metadata.get("version"):
+                            print(f"- **Pipx Version:** {metadata['version']}")
+                elif sub.category == "Dependencies":
+                    print("### Dependencies")
+                    print(f"- **Status:** {sub.message}")
+                    if sub.details.get("installed"):
+                        print(
+                            f"- **Installed Packages:** {len(sub.details['installed'])}"
+                        )
+            print()
+
+    def _print_result_markdown(self, result: DiagnosticResult):
+        """Print a single result in markdown format."""
+        symbol = self.STATUS_SYMBOLS.get(result.status, "?")
+        print(f"### {symbol} {result.category}\n")
+
+        # Status badge
+        status_badge = {
+            DiagnosticStatus.OK: "![OK](https://img.shields.io/badge/status-OK-green)",
+            DiagnosticStatus.WARNING: "![Warning](https://img.shields.io/badge/status-Warning-yellow)",
+            DiagnosticStatus.ERROR: "![Error](https://img.shields.io/badge/status-Error-red)",
+            DiagnosticStatus.SKIPPED: "![Skipped](https://img.shields.io/badge/status-Skipped-gray)",
+        }.get(result.status, "")
+
+        print(f"{status_badge}")
+        print(f"\n**Message:** {result.message}\n")
+
+        if result.fix_command:
+            print("**Fix Available:**")
+            print("```bash")
+            print(result.fix_command)
+            print("```")
+            if result.fix_description:
+                print(f"*{result.fix_description}*\n")
+
+        if self.verbose and result.details:
+            print("<details>")
+            print("<summary>Details</summary>\n")
+            print("```json")
+            import json
+
+            print(json.dumps(result.details, indent=2, default=str))
+            print("```")
+            print("</details>\n")
+
+    def _print_recommendations_markdown(self, summary: DiagnosticSummary):
+        """Print recommendations based on diagnostic results."""
+        recommendations = []
+
+        # Analyze results for recommendations
+        has_errors = summary.error_count > 0
+        has_warnings = summary.warning_count > 0
+
+        # Check specific conditions
+        for result in summary.results:
+            if (
+                result.category == "Installation"
+                and result.status != DiagnosticStatus.OK
+            ):
+                if "pipx" not in str(result.details.get("installation_method", "")):
+                    recommendations.append(
+                        "Consider using pipx for isolated installation: `pipx install claude-mpm`"
+                    )
+
+            if result.category == "MCP Services":
+                services = result.details.get("services", {})
+                missing = [
+                    s for s, info in services.items() if not info.get("installed")
+                ]
+                if missing:
+                    recommendations.append(
+                        f"Install missing MCP services for enhanced features: {', '.join(missing)}"
+                    )
+
+            if (
+                result.category == "Claude Desktop"
+                and result.status == DiagnosticStatus.WARNING
+            ):
+                recommendations.append(
+                    "Update Claude Desktop to the latest version for best compatibility"
+                )
+
+        if recommendations:
+            print("## 📋 Recommendations\n")
+            for i, rec in enumerate(recommendations, 1):
+                print(f"{i}. {rec}")
+            print()

claude_mpm/services/event_bus/direct_relay.py

@@ -18,9 +18,10 @@ import logging
 from datetime import datetime, timezone
 from typing import Any
 
+from claude_mpm.core.logging_utils import get_logger
+
 from .event_bus import EventBus
 
-from claude_mpm.core.logging_utils import get_logger
 logger = get_logger(__name__)
 
 

claude_mpm/services/event_bus/event_bus.py

@@ -18,6 +18,7 @@ from pyee.asyncio import AsyncIOEventEmitter
 
 # Configure logger
 from claude_mpm.core.logging_utils import get_logger
+
 logger = get_logger(__name__)
 
 

claude_mpm/services/event_bus/relay.py

@@ -24,10 +24,11 @@ except ImportError:
 
 import contextlib
 
-from .event_bus import EventBus
-
 # Configure logger
 from claude_mpm.core.logging_utils import get_logger
+
+from .event_bus import EventBus
+
 logger = get_logger(__name__)
 
 

claude_mpm/services/framework_claude_md_generator/content_assembler.py

@@ -9,10 +9,10 @@ from collections import OrderedDict
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
+from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.services.agents.management import AgentCapabilitiesGenerator
 from claude_mpm.services.agents.registry import DeployedAgentDiscovery
 
-from claude_mpm.core.logging_utils import get_logger
 logger = get_logger(__name__)
 
 

claude_mpm/services/infrastructure/daemon_manager.py

@@ -31,9 +31,9 @@ except ImportError:
     import psutil
 
 # from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.services.socketio.server.main import SocketIOServer
 
-from claude_mpm.core.logging_utils import get_logger
 logger = get_logger(__name__)
 
 

claude_mpm/services/mcp_config_manager.py

@@ -76,6 +76,7 @@ class MCPConfigManager:
 
             # Check system PATH (including homebrew)
             import shutil
+
             system_path = shutil.which(service_name)
             if system_path and system_path not in candidates:
                 candidates.append(system_path)
@@ -84,14 +85,13 @@ class MCPConfigManager:
             for path in candidates:
                 try:
                     result = subprocess.run(
-                        [path, "--help"],
-                        capture_output=True,
-                        text=True,
-                        timeout=5
+                        [path, "--help"], capture_output=True, text=True, timeout=5, check=False
                     )
                     # Check if this version has MCP support
                     if "claude" in result.stdout or "mcp" in result.stdout:
-                        self.logger.debug(f"Found kuzu-memory with MCP support at {path}")
+                        self.logger.debug(
+                            f"Found kuzu-memory with MCP support at {path}"
+                        )
                         return path
                 except:
                     pass
@@ -125,7 +125,9 @@ class MCPConfigManager:
             )
             return local_path
 
-        self.logger.debug(f"Service {service_name} not found - will auto-install when needed")
+        self.logger.debug(
+            f"Service {service_name} not found - will auto-install when needed"
+        )
         return None
 
     def _check_pipx_installation(self, service_name: str) -> Optional[str]:
@@ -224,12 +226,10 @@ class MCPConfigManager:
             # Check kuzu-memory version to determine correct command
             # v1.1.0+ has "claude mcp-server", v1.0.0 has "serve"
             import subprocess
+
             try:
                 result = subprocess.run(
-                    [service_path, "--help"],
-                    capture_output=True,
-                    text=True,
-                    timeout=10
+                    [service_path, "--help"], capture_output=True, text=True, timeout=10, check=False
                 )
                 if "claude" in result.stdout:
                     # v1.1.0+ with claude command

claude_mpm/services/mcp_gateway/core/process_pool.py

@@ -395,6 +395,7 @@ async def auto_initialize_vector_search():
     try:
         # Import MCPConfigManager to handle installation
         from claude_mpm.services.mcp_config_manager import MCPConfigManager
+
         config_manager = MCPConfigManager()
 
         # Check if mcp-vector-search is already installed
@@ -411,7 +412,9 @@ async def auto_initialize_vector_search():
             import subprocess
 
             if not shutil.which("pipx"):
-                logger.warning("⚠️ pipx not found. Please install pipx to enable automatic mcp-vector-search installation")
+                logger.warning(
+                    "⚠️ pipx not found. Please install pipx to enable automatic mcp-vector-search installation"
+                )
                 logger.info("   Install pipx with: python -m pip install --user pipx")
                 return
 
@@ -420,26 +423,34 @@ async def auto_initialize_vector_search():
                     ["pipx", "install", "mcp-vector-search"],
                     capture_output=True,
                     text=True,
-                    timeout=60  # 1 minute timeout for installation
+                    timeout=60, check=False,  # 1 minute timeout for installation
                 )
 
                 if result.returncode == 0:
                     logger.info("✅ mcp-vector-search installed successfully")
                     # Detect the newly installed path
-                    vector_search_path = config_manager.detect_service_path("mcp-vector-search")
+                    vector_search_path = config_manager.detect_service_path(
+                        "mcp-vector-search"
+                    )
                     if not vector_search_path:
-                        logger.warning("mcp-vector-search installed but command not found in PATH")
+                        logger.warning(
+                            "mcp-vector-search installed but command not found in PATH"
+                        )
                         return
 
                     # Update the Claude configuration to include the newly installed service
                     logger.info("📝 Updating Claude configuration...")
-                    config_success, config_msg = config_manager.ensure_mcp_services_configured()
+                    config_success, config_msg = (
+                        config_manager.ensure_mcp_services_configured()
+                    )
                     if config_success:
                         logger.info(f"✅ {config_msg}")
                     else:
                         logger.warning(f"⚠️ Configuration update issue: {config_msg}")
                 else:
-                    logger.warning(f"Failed to install mcp-vector-search: {result.stderr}")
+                    logger.warning(
+                        f"Failed to install mcp-vector-search: {result.stderr}"
+                    )
                     return
 
             except subprocess.TimeoutExpired:
@@ -452,10 +463,14 @@ async def auto_initialize_vector_search():
         # At this point, mcp-vector-search should be available
         # Get the actual command to use
         import shutil
+
         vector_search_cmd = shutil.which("mcp-vector-search")
         if not vector_search_cmd:
             # Try pipx installation path as fallback
-            pipx_path = Path.home() / ".local/pipx/venvs/mcp-vector-search/bin/mcp-vector-search"
+            pipx_path = (
+                Path.home()
+                / ".local/pipx/venvs/mcp-vector-search/bin/mcp-vector-search"
+            )
             if pipx_path.exists():
                 vector_search_cmd = str(pipx_path)
             else:
@@ -477,10 +492,13 @@ async def auto_initialize_vector_search():
                     if chroma_db.exists() and chroma_db.stat().st_size > 0:
                         logger.info("✓ Vector search index is healthy and ready")
                         return
-                    else:
-                        logger.info("⚠️ Vector search index may be corrupted, rebuilding...")
+                    logger.info(
+                        "⚠️ Vector search index may be corrupted, rebuilding..."
+                    )
                 except Exception as e:
-                    logger.debug(f"Vector search health check failed: {e}, will attempt to rebuild")
+                    logger.debug(
+                        f"Vector search health check failed: {e}, will attempt to rebuild"
+                    )
 
         # Initialize or reinitialize the project
         logger.info(f"🎯 Initializing vector search for project: {current_dir}")
@@ -488,12 +506,13 @@ async def auto_initialize_vector_search():
         # Initialize the project (this creates the config)
         # Note: mcp-vector-search operates on the current directory
         import subprocess
+
         proc = subprocess.run(
             [vector_search_cmd, "init"],
             capture_output=True,
             text=True,
             timeout=30,
-            cwd=str(current_dir)  # Run in the project directory
+            cwd=str(current_dir), check=False,  # Run in the project directory
         )
 
         if proc.returncode == 0:
@@ -508,29 +527,36 @@ async def auto_initialize_vector_search():
                         capture_output=True,
                         text=True,
                         timeout=300,  # 5 minute timeout for indexing
-                        cwd=str(current_dir)  # Run in the project directory
+                        cwd=str(current_dir), check=False,  # Run in the project directory
                     )
                     if index_proc.returncode == 0:
                         logger.info("✅ Project indexing completed successfully")
                         # Parse output to show statistics if available
                         if "indexed" in index_proc.stdout.lower():
                             # Extract and log indexing statistics
-                            lines = index_proc.stdout.strip().split('\n')
+                            lines = index_proc.stdout.strip().split("\n")
                             for line in lines:
                                 if "indexed" in line.lower() or "files" in line.lower():
                                     logger.info(f"   {line.strip()}")
                     else:
-                        logger.warning(f"⚠️ Project indexing failed: {index_proc.stderr}")
+                        logger.warning(
+                            f"⚠️ Project indexing failed: {index_proc.stderr}"
+                        )
                 except subprocess.TimeoutExpired:
-                    logger.warning("⚠️ Project indexing timed out (will continue in background)")
+                    logger.warning(
+                        "⚠️ Project indexing timed out (will continue in background)"
+                    )
                 except Exception as e:
                     logger.debug(f"Background indexing error (non-critical): {e}")
 
             # Run indexing in background thread
             import threading
+
             index_thread = threading.Thread(target=background_index, daemon=True)
             index_thread.start()
-            logger.info("📚 Background indexing started - vector search will be available shortly")
+            logger.info(
+                "📚 Background indexing started - vector search will be available shortly"
+            )
 
         else:
             logger.warning(f"⚠️ Vector search initialization failed: {proc.stderr}")
@@ -556,6 +582,7 @@ async def auto_initialize_kuzu_memory():
     try:
         # Import MCPConfigManager to handle installation
         from claude_mpm.services.mcp_config_manager import MCPConfigManager
+
         config_manager = MCPConfigManager()
 
         # Check if kuzu-memory is already installed
@@ -572,7 +599,9 @@ async def auto_initialize_kuzu_memory():
             import subprocess
 
             if not shutil.which("pipx"):
-                logger.warning("⚠️ pipx not found. Please install pipx to enable automatic kuzu-memory installation")
+                logger.warning(
+                    "⚠️ pipx not found. Please install pipx to enable automatic kuzu-memory installation"
+                )
                 logger.info("   Install pipx with: python -m pip install --user pipx")
                 return
 
@@ -581,7 +610,7 @@ async def auto_initialize_kuzu_memory():
                     ["pipx", "install", "kuzu-memory"],
                     capture_output=True,
                     text=True,
-                    timeout=60  # 1 minute timeout for installation
+                    timeout=60, check=False,  # 1 minute timeout for installation
                 )
 
                 if result.returncode == 0:
@@ -589,12 +618,16 @@ async def auto_initialize_kuzu_memory():
                     # Detect the newly installed path
                     kuzu_memory_path = config_manager.detect_service_path("kuzu-memory")
                     if not kuzu_memory_path:
-                        logger.warning("kuzu-memory installed but command not found in PATH")
+                        logger.warning(
+                            "kuzu-memory installed but command not found in PATH"
+                        )
                         return
 
                     # Update the Claude configuration to include the newly installed service
                     logger.info("📝 Updating Claude configuration...")
-                    config_success, config_msg = config_manager.ensure_mcp_services_configured()
+                    config_success, config_msg = (
+                        config_manager.ensure_mcp_services_configured()
+                    )
                     if config_success:
                         logger.info(f"✅ {config_msg}")
                     else:
@@ -613,6 +646,7 @@ async def auto_initialize_kuzu_memory():
         # At this point, kuzu-memory should be available
         # Get the actual command to use
         import shutil
+
         kuzu_memory_cmd = shutil.which("kuzu-memory")
         if not kuzu_memory_cmd:
             # Try pipx installation path as fallback
@@ -629,18 +663,23 @@ async def auto_initialize_kuzu_memory():
 
         # Check if database is already initialized
         if kuzu_memories_dir.exists():
-            logger.debug(f"Kuzu-memory database already initialized at {kuzu_memories_dir}")
+            logger.debug(
+                f"Kuzu-memory database already initialized at {kuzu_memories_dir}"
+            )
         else:
-            logger.info(f"🎯 Initializing kuzu-memory database for project: {current_dir}")
+            logger.info(
+                f"🎯 Initializing kuzu-memory database for project: {current_dir}"
+            )
 
             # Initialize the database in current project directory
             import subprocess
+
             proc = subprocess.run(
                 [kuzu_memory_cmd, "init"],
                 capture_output=True,
                 text=True,
                 timeout=30,
-                cwd=str(current_dir),
+                cwd=str(current_dir), check=False,
             )
 
             if proc.returncode == 0: