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

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -2,7 +2,7 @@
 Check MCP external services installation and health.
 
 WHY: Verify that MCP services (mcp-vector-search, mcp-browser, mcp-ticketer, kuzu-memory)
-are properly installed and accessible for enhanced Claude Desktop capabilities.
+are properly installed and accessible for enhanced Claude Code capabilities.
 """
 
 import json
@@ -21,30 +21,38 @@ class MCPServicesCheck(BaseDiagnosticCheck):
     MCP_SERVICES = {
         "mcp-vector-search": {
             "package": "mcp-vector-search",
-            "command": ["mcp-vector-search", "--help"],
+            "command": [
+                "mcp-vector-search",
+                "--version",
+            ],  # Use --version for proper check
             "description": "Vector search for semantic code navigation",
             "check_health": True,
             "health_command": ["mcp-vector-search", "--version"],
+            "pipx_run_command": ["pipx", "run", "mcp-vector-search", "--version"],
         },
         "mcp-browser": {
             "package": "mcp-browser",
-            "command": ["mcp-browser", "--help"],
+            "command": ["mcp-browser", "--version"],  # Use --version for proper check
             "description": "Browser automation and web interaction",
             "check_health": True,
             "health_command": ["mcp-browser", "--version"],
+            "pipx_run_command": ["pipx", "run", "mcp-browser", "--version"],
         },
         "mcp-ticketer": {
             "package": "mcp-ticketer",
-            "command": ["mcp-ticketer", "--help"],
+            "command": ["mcp-ticketer", "--version"],  # Use --version for proper check
             "description": "Ticket and task management",
             "check_health": True,
             "health_command": ["mcp-ticketer", "--version"],
+            "pipx_run_command": ["pipx", "run", "mcp-ticketer", "--version"],
         },
         "kuzu-memory": {
             "package": "kuzu-memory",
-            "command": ["kuzu-memory", "--help"],
+            "command": ["kuzu-memory", "--version"],  # Use --version for proper check
             "description": "Graph-based memory system",
-            "check_health": False,  # May not have version command
+            "check_health": True,  # v1.1.0+ has version command
+            "health_command": ["kuzu-memory", "--version"],
+            "pipx_run_command": ["pipx", "run", "kuzu-memory", "--version"],
         },
     }
 
@@ -143,6 +151,13 @@ class MCPServicesCheck(BaseDiagnosticCheck):
         if command_path:
             details["command_path"] = command_path
 
+        # If not directly accessible, try pipx run command
+        if not accessible and "pipx_run_command" in config:
+            if self._verify_command_works(config["pipx_run_command"]):
+                accessible = True
+                details["accessible_via_pipx_run"] = True
+                details["pipx_run_available"] = True
+
         # Check for installation in various locations
         if not pipx_installed and not accessible:
             # Try common installation locations
@@ -157,11 +172,19 @@ class MCPServicesCheck(BaseDiagnosticCheck):
 
         # Check service health/version if accessible
         if accessible and config.get("check_health"):
-            version = self._get_service_version(
-                config.get("health_command", config["command"])
-            )
-            if version:
-                details["version"] = version
+            # Try different version commands in order of preference
+            version_commands = []
+            if details.get("accessible_via_pipx_run") and "pipx_run_command" in config:
+                version_commands.append(config["pipx_run_command"])
+            if "health_command" in config:
+                version_commands.append(config["health_command"])
+            version_commands.append(config["command"])
+
+            for cmd in version_commands:
+                version = self._get_service_version(cmd)
+                if version:
+                    details["version"] = version
+                    break
 
         # Determine status
         if not (pipx_installed or accessible):
@@ -175,6 +198,14 @@ class MCPServicesCheck(BaseDiagnosticCheck):
             )
 
         if pipx_installed and not accessible:
+            # Check if pipx run works
+            if details.get("pipx_run_available"):
+                return DiagnosticResult(
+                    category=f"MCP Service: {service_name}",
+                    status=DiagnosticStatus.OK,
+                    message="Installed via pipx (use 'pipx run' to execute)",
+                    details=details,
+                )
             return DiagnosticResult(
                 category=f"MCP Service: {service_name}",
                 status=DiagnosticStatus.WARNING,
@@ -247,29 +278,73 @@ class MCPServicesCheck(BaseDiagnosticCheck):
 
             if result.returncode == 0:
                 path = result.stdout.strip()
-                return True, path
+                # Verify the command actually works with --version
+                if self._verify_command_works(command):
+                    return True, path
+                return False, path
         except (subprocess.SubprocessError, FileNotFoundError):
             pass
 
-        # Try direct execution
+        # Try direct execution with --version
+        if self._verify_command_works(command):
+            return True, None
+
+        return False, None
+
+    def _verify_command_works(self, command: List[str]) -> bool:
+        """Verify a command actually works by checking its --version output."""
         try:
             result = subprocess.run(
                 command,
                 capture_output=True,
                 text=True,
-                timeout=2,
+                timeout=5,
                 check=False,
             )
-            if (
-                result.returncode == 0
-                or "help" in result.stdout.lower()
-                or "usage" in result.stdout.lower()
-            ):
-                return True, None
-        except (subprocess.SubprocessError, FileNotFoundError):
+
+            # Check for successful execution or version output
+            # Don't accept error messages containing "help" or "usage" as success
+            if result.returncode == 0:
+                # Look for actual version information
+                output = (result.stdout + result.stderr).lower()
+                # Check for version indicators
+                if any(
+                    keyword in output
+                    for keyword in ["version", "v1.", "v0.", "1.", "0."]
+                ):
+                    # But reject if it's an error message
+                    if not any(
+                        error in output
+                        for error in [
+                            "error",
+                            "not found",
+                            "no such",
+                            "command not found",
+                        ]
+                    ):
+                        return True
+
+            # For some tools, non-zero return code is OK if version is shown
+            elif "--version" in command or "--help" in command:
+                output = (result.stdout + result.stderr).lower()
+                # Must have version info and no error indicators
+                if "version" in output or "v1." in output or "v0." in output:
+                    if not any(
+                        error in output
+                        for error in [
+                            "error",
+                            "not found",
+                            "no such",
+                            "command not found",
+                            "traceback",
+                        ]
+                    ):
+                        return True
+
+        except (subprocess.SubprocessError, FileNotFoundError, OSError):
             pass
 
-        return False, None
+        return False
 
     def _check_alternative_installations(
         self, service_name: str

claude_mpm/services/diagnostics/diagnostic_runner.py

@@ -14,7 +14,7 @@ from claude_mpm.core.logging_utils import get_logger
 from .checks import (
     AgentCheck,
     BaseDiagnosticCheck,
-    ClaudeDesktopCheck,
+    ClaudeCodeCheck,
     CommonIssuesCheck,
     ConfigurationCheck,
     FilesystemCheck,
@@ -53,7 +53,7 @@ class DiagnosticRunner:
             ConfigurationCheck,
             FilesystemCheck,
             InstructionsCheck,  # Check instruction files early
-            ClaudeDesktopCheck,
+            ClaudeCodeCheck,
             AgentCheck,
             MCPCheck,
             MCPServicesCheck,  # Check external MCP services
@@ -121,7 +121,7 @@ class DiagnosticRunner:
         ]
         # Level 2: May depend on level 1
         level2 = [
-            ClaudeDesktopCheck,
+            ClaudeCodeCheck,
             AgentCheck,
             MCPCheck,
             MCPServicesCheck,
@@ -209,8 +209,8 @@ class DiagnosticRunner:
             "config": ConfigurationCheck,
             "filesystem": FilesystemCheck,
             "fs": FilesystemCheck,
-            "claude": ClaudeDesktopCheck,
-            "claude_desktop": ClaudeDesktopCheck,
+            "claude": ClaudeCodeCheck,
+            "claude_code": ClaudeCodeCheck,
             "agents": AgentCheck,
             "agent": AgentCheck,
             "mcp": MCPCheck,

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -385,9 +385,9 @@ class DoctorReporter:
                     print(
                         f"| Installation Method | {result.details['installation_method']} |"
                     )
-            elif result.category == "Claude Desktop":
+            elif result.category == "Claude Code":
                 if result.details.get("version"):
-                    print(f"| Claude Desktop | {result.details['version']} |")
+                    print(f"| Claude Code (CLI) | {result.details['version']} |")
 
     def _print_mcp_services_markdown(self, summary: DiagnosticSummary):
         """Print MCP services status table in markdown."""
@@ -533,11 +533,11 @@ class DoctorReporter:
                     )
 
             if (
-                result.category == "Claude Desktop"
+                result.category == "Claude Code"
                 and result.status == DiagnosticStatus.WARNING
             ):
                 recommendations.append(
-                    "Update Claude Desktop to the latest version for best compatibility"
+                    "Update Claude Code (CLI) to the latest version for best compatibility"
                 )
 
         if recommendations:

claude_mpm/services/mcp_config_manager.py

@@ -11,6 +11,7 @@ MCP service installations.
 
 import json
 import subprocess
+import sys
 from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
@@ -85,7 +86,11 @@ class MCPConfigManager:
             for path in candidates:
                 try:
                     result = subprocess.run(
-                        [path, "--help"], capture_output=True, text=True, timeout=5, check=False
+                        [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:
@@ -194,55 +199,172 @@ class MCPConfigManager:
         """
         Generate configuration for a specific MCP service.
 
+        Prefers 'pipx run' or 'uvx' commands over direct execution for better isolation.
+
         Args:
             service_name: Name of the MCP service
 
         Returns:
             Service configuration dict or None if service not found
         """
-        service_path = self.detect_service_path(service_name)
-        if not service_path:
-            return None
+        import shutil
 
-        config = {
-            "type": "stdio",
-            "command": service_path,
-        }
+        # Check for pipx run first (preferred for isolation)
+        use_pipx_run = False
+        use_uvx = False
+
+        # Try pipx run test
+        if shutil.which("pipx"):
+            try:
+                result = subprocess.run(
+                    ["pipx", "run", service_name, "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0 or "version" in result.stdout.lower():
+                    use_pipx_run = True
+                    self.logger.debug(f"Will use 'pipx run' for {service_name}")
+            except:
+                pass
+
+        # Try uvx if pipx run not available
+        if not use_pipx_run and shutil.which("uvx"):
+            try:
+                result = subprocess.run(
+                    ["uvx", service_name, "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0 or "version" in result.stdout.lower():
+                    use_uvx = True
+                    self.logger.debug(f"Will use 'uvx' for {service_name}")
+            except:
+                pass
+
+        # If neither work, try to find direct path
+        service_path = None
+        if not use_pipx_run and not use_uvx:
+            service_path = self.detect_service_path(service_name)
+            if not service_path:
+                return None
+
+        # Build configuration
+        config = {"type": "stdio"}
 
         # Service-specific configurations
         if service_name == "mcp-vector-search":
-            config["args"] = [
-                "-m",
-                "mcp_vector_search.mcp.server",
-                str(self.project_root),
-            ]
+            if use_pipx_run:
+                config["command"] = "pipx"
+                config["args"] = [
+                    "run",
+                    "mcp-vector-search",
+                    "-m",
+                    "mcp_vector_search.mcp.server",
+                    str(self.project_root),
+                ]
+            elif use_uvx:
+                config["command"] = "uvx"
+                config["args"] = [
+                    "mcp-vector-search",
+                    "-m",
+                    "mcp_vector_search.mcp.server",
+                    str(self.project_root),
+                ]
+            else:
+                config["command"] = service_path
+                config["args"] = [
+                    "-m",
+                    "mcp_vector_search.mcp.server",
+                    str(self.project_root),
+                ]
             config["env"] = {}
+
         elif service_name == "mcp-browser":
-            config["args"] = ["mcp"]
+            if use_pipx_run:
+                config["command"] = "pipx"
+                config["args"] = ["run", "mcp-browser", "mcp"]
+            elif use_uvx:
+                config["command"] = "uvx"
+                config["args"] = ["mcp-browser", "mcp"]
+            else:
+                config["command"] = service_path
+                config["args"] = ["mcp"]
             config["env"] = {"MCP_BROWSER_HOME": str(Path.home() / ".mcp-browser")}
+
         elif service_name == "mcp-ticketer":
-            config["args"] = ["mcp"]
-        elif service_name == "kuzu-memory":
-            # Check kuzu-memory version to determine correct command
-            # v1.1.0+ has "claude mcp-server", v1.0.0 has "serve"
-            import subprocess
+            if use_pipx_run:
+                config["command"] = "pipx"
+                config["args"] = ["run", "mcp-ticketer", "mcp"]
+            elif use_uvx:
+                config["command"] = "uvx"
+                config["args"] = ["mcp-ticketer", "mcp"]
+            else:
+                config["command"] = service_path
+                config["args"] = ["mcp"]
 
-            try:
-                result = subprocess.run(
-                    [service_path, "--help"], capture_output=True, text=True, timeout=10, check=False
-                )
-                if "claude" in result.stdout:
-                    # v1.1.0+ with claude command
-                    config["args"] = ["claude", "mcp-server"]
-                else:
-                    # v1.0.0 with serve command
-                    config["args"] = ["serve"]
-            except:
-                # Default to older version command
-                config["args"] = ["serve"]
-            # kuzu-memory works with project-specific databases, no custom path needed
+        elif service_name == "kuzu-memory":
+            # Determine kuzu-memory command version
+            kuzu_args = ["mcp", "serve"]  # Default to the correct modern format
+            test_cmd = None
+
+            if use_pipx_run:
+                test_cmd = ["pipx", "run", "kuzu-memory", "--help"]
+            elif use_uvx:
+                test_cmd = ["uvx", "kuzu-memory", "--help"]
+            elif service_path:
+                test_cmd = [service_path, "--help"]
+
+            if test_cmd:
+                try:
+                    result = subprocess.run(
+                        test_cmd,
+                        capture_output=True,
+                        text=True,
+                        timeout=10,
+                        check=False,
+                    )
+                    # Check for MCP support in help output
+                    help_output = result.stdout.lower() + result.stderr.lower()
+
+                    # Modern version detection - look for "mcp serve" command
+                    if "mcp serve" in help_output or ("mcp" in help_output and "serve" in help_output):
+                        # Modern version with mcp serve command
+                        kuzu_args = ["mcp", "serve"]
+                    # Legacy version detection - only "serve" without "mcp"
+                    elif "serve" in help_output and "mcp" not in help_output:
+                        # Very old version that only has serve command
+                        kuzu_args = ["serve"]
+                    # Note: "claude mcp-server" format is deprecated and not used
+                    else:
+                        # Default to the correct modern format
+                        kuzu_args = ["mcp", "serve"]
+                except Exception:
+                    # Default to the correct mcp serve command on any error
+                    kuzu_args = ["mcp", "serve"]
+
+            if use_pipx_run:
+                config["command"] = "pipx"
+                config["args"] = ["run", "kuzu-memory"] + kuzu_args
+            elif use_uvx:
+                config["command"] = "uvx"
+                config["args"] = ["kuzu-memory"] + kuzu_args
+            else:
+                config["command"] = service_path
+                config["args"] = kuzu_args
+
+        # Generic config for unknown services
+        elif use_pipx_run:
+            config["command"] = "pipx"
+            config["args"] = ["run", service_name]
+        elif use_uvx:
+            config["command"] = "uvx"
+            config["args"] = [service_name]
         else:
-            # Generic config for unknown services
+            config["command"] = service_path
             config["args"] = []
 
         return config
@@ -464,7 +586,7 @@ class MCPConfigManager:
 
     def install_missing_services(self) -> Tuple[bool, str]:
         """
-        Install missing MCP services via pipx.
+        Install missing MCP services via pipx with verification and fallbacks.
 
         Returns:
             Tuple of (success, message)
@@ -481,22 +603,167 @@ class MCPConfigManager:
         failed = []
 
         for service_name in missing:
-            try:
-                self.logger.info(f"Installing {service_name} via pipx...")
-                subprocess.run(
-                    ["pipx", "install", service_name],
-                    capture_output=True,
-                    text=True,
-                    check=True,
-                )
-                installed.append(service_name)
-                self.logger.info(f"Successfully installed {service_name}")
-            except subprocess.CalledProcessError as e:
+            # Try pipx install first
+            success, method = self._install_service_with_fallback(service_name)
+            if success:
+                installed.append(f"{service_name} ({method})")
+                self.logger.info(f"Successfully installed {service_name} via {method}")
+            else:
                 failed.append(service_name)
-                self.logger.error(f"Failed to install {service_name}: {e.stderr}")
+                self.logger.error(f"Failed to install {service_name}")
 
         if failed:
             return False, f"Failed to install: {', '.join(failed)}"
         if installed:
             return True, f"Successfully installed: {', '.join(installed)}"
         return True, "No services needed installation"
+
+    def _install_service_with_fallback(self, service_name: str) -> Tuple[bool, str]:
+        """
+        Install a service with multiple fallback methods.
+
+        Returns:
+            Tuple of (success, installation_method)
+        """
+        import shutil
+
+        # Method 1: Try pipx install
+        if shutil.which("pipx"):
+            try:
+                self.logger.debug(f"Attempting to install {service_name} via pipx...")
+                result = subprocess.run(
+                    ["pipx", "install", service_name],
+                    capture_output=True,
+                    text=True,
+                    timeout=120,  # 2 minute timeout
+                    check=False,
+                )
+
+                if result.returncode == 0:
+                    # Verify installation worked
+                    if self._verify_service_installed(service_name, "pipx"):
+                        return True, "pipx"
+
+                    self.logger.warning(
+                        f"pipx install succeeded but verification failed for {service_name}"
+                    )
+                else:
+                    self.logger.debug(f"pipx install failed: {result.stderr}")
+            except subprocess.TimeoutExpired:
+                self.logger.warning(f"pipx install timed out for {service_name}")
+            except Exception as e:
+                self.logger.debug(f"pipx install error: {e}")
+
+        # Method 2: Try uvx (if available)
+        if shutil.which("uvx"):
+            try:
+                self.logger.debug(f"Attempting to install {service_name} via uvx...")
+                result = subprocess.run(
+                    ["uvx", "install", service_name],
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                    check=False,
+                )
+
+                if result.returncode == 0:
+                    if self._verify_service_installed(service_name, "uvx"):
+                        return True, "uvx"
+            except Exception as e:
+                self.logger.debug(f"uvx install error: {e}")
+
+        # Method 3: Try pip install --user
+        try:
+            self.logger.debug(f"Attempting to install {service_name} via pip --user...")
+            result = subprocess.run(
+                [sys.executable, "-m", "pip", "install", "--user", service_name],
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+
+            if result.returncode == 0:
+                if self._verify_service_installed(service_name, "pip"):
+                    return True, "pip --user"
+
+                self.logger.warning(
+                    f"pip install succeeded but verification failed for {service_name}"
+                )
+        except Exception as e:
+            self.logger.debug(f"pip install error: {e}")
+
+        return False, "none"
+
+    def _verify_service_installed(self, service_name: str, method: str) -> bool:
+        """
+        Verify that a service was successfully installed and is functional.
+
+        Args:
+            service_name: Name of the service
+            method: Installation method used
+
+        Returns:
+            True if service is installed and functional
+        """
+        import time
+
+        # Give the installation a moment to settle
+        time.sleep(1)
+
+        # Check if we can find the service
+        service_path = self.detect_service_path(service_name)
+        if not service_path:
+            # Try pipx run as fallback for pipx installations
+            if method == "pipx":
+                try:
+                    result = subprocess.run(
+                        ["pipx", "run", service_name, "--version"],
+                        capture_output=True,
+                        text=True,
+                        timeout=10,
+                        check=False,
+                    )
+                    if result.returncode == 0 or "version" in result.stdout.lower():
+                        self.logger.debug(f"{service_name} accessible via 'pipx run'")
+                        return True
+                except:
+                    pass
+            return False
+
+        # Try to verify it works
+        try:
+            # Different services may need different verification
+            test_commands = [
+                [service_path, "--version"],
+                [service_path, "--help"],
+            ]
+
+            for cmd in test_commands:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                    check=False,
+                )
+
+                output = (result.stdout + result.stderr).lower()
+                # Check for signs of success
+                if result.returncode == 0:
+                    return True
+                # Some tools return non-zero but still work
+                if any(
+                    indicator in output
+                    for indicator in ["version", "usage", "help", service_name.lower()]
+                ):
+                    # Make sure it's not an error message
+                    if not any(
+                        error in output
+                        for error in ["error", "not found", "traceback", "no such"]
+                    ):
+                        return True
+        except Exception as e:
+            self.logger.debug(f"Verification error for {service_name}: {e}")
+
+        return False