claude-mpm 4.14.6__py3-none-any.whl → 4.21.0__py3-none-any.whl

claude_mpm/services/mcp_gateway/tools/external_mcp_services.py

@@ -2,12 +2,22 @@
 External MCP Services Integration
 ==================================
 
-Manages installation and basic setup of external MCP services like mcp-vector-search
+Manages detection and setup of external MCP services like mcp-vector-search
 and mcp-browser. These services run as separate MCP servers in Claude Code,
 not as part of the Claude MPM MCP Gateway.
 
-Note: As of the latest architecture, external services are registered as separate
-MCP servers in Claude Code configuration, not as tools within the gateway.
+IMPORTANT: External services are NOT auto-installed. Users must manually install
+them using pipx or pip. This gives users explicit control over which optional
+services they want to enable.
+
+Installation:
+    pipx install mcp-vector-search
+    pipx install mcp-browser
+    pipx install kuzu-memory
+    pipx install mcp-ticketer
+
+Note: External services are registered as separate MCP servers in Claude Code
+configuration, not as tools within the gateway.
 """
 
 import json
@@ -20,7 +30,12 @@ from claude_mpm.services.mcp_gateway.tools.base_adapter import BaseToolAdapter
 
 
 class ExternalMCPService(BaseToolAdapter):
-    """Base class for external MCP service integration."""
+    """Base class for external MCP service integration.
+
+    External services are detected if already installed but are NOT
+    automatically installed. Users must install them manually using
+    pipx or pip to enable these optional features.
+    """
 
     def __init__(self, service_name: str, package_name: str):
         """
@@ -65,27 +80,37 @@ class ExternalMCPService(BaseToolAdapter):
         )
 
     async def initialize(
-        self, auto_install: bool = True, interactive: bool = True
+        self, auto_install: bool = False, interactive: bool = False
     ) -> bool:
         """Initialize the external service.
 
+        NOTE: Auto-installation is disabled by default (v4.9.0+). Users must
+        manually install external services using pipx or pip.
+
         Args:
-            auto_install: Whether to automatically install if not found
-            interactive: Whether to prompt user for installation preferences
+            auto_install: Whether to automatically install if not found (default: False)
+                         Deprecated - will be removed in future versions
+            interactive: Whether to prompt user for installation preferences (default: False)
+                        Only used if auto_install=True
         """
         try:
             # Check if package is installed
             self._is_installed = await self._check_installation()
 
             if not self._is_installed and auto_install:
-                self.logger.info(
-                    f"{self.package_name} not installed - attempting installation"
+                # This path is deprecated but kept for backward compatibility
+                self.logger.warning(
+                    f"Auto-installation is deprecated. Please install {self.package_name} manually: "
+                    f"pipx install {self.package_name}"
                 )
                 await self._install_package(interactive=interactive)
                 self._is_installed = await self._check_installation()
 
             if not self._is_installed:
-                self.logger.warning(f"{self.package_name} is not available")
+                self.logger.debug(
+                    f"{self.package_name} is not available. "
+                    f"Install manually with: pipx install {self.package_name}"
+                )
                 return False
 
             self.logger.info(f"{self.package_name} is available")
@@ -136,12 +161,17 @@ class ExternalMCPService(BaseToolAdapter):
 
             if interactive:
                 # Show user-friendly installation prompt
-                print(f"\n⚠️  {self.package_name} not found")
-                print("This package enables enhanced functionality (optional).")
-                print("\nInstallation options:")
-                print("1. Install via pip (recommended for this project)")
-                print("2. Install via pipx (isolated, system-wide)")
-                print("3. Skip (continue without this package)")
+                print(f"\n⚠️  {self.package_name} not found", file=sys.stderr)
+                print(
+                    "This package enables enhanced functionality (optional).",
+                    file=sys.stderr,
+                )
+                print("\nInstallation options:", file=sys.stderr)
+                print(
+                    "1. Install via pip (recommended for this project)", file=sys.stderr
+                )
+                print("2. Install via pipx (isolated, system-wide)", file=sys.stderr)
+                print("3. Skip (continue without this package)", file=sys.stderr)
 
                 try:
                     choice = input("\nChoose option (1/2/3) [1]: ").strip() or "1"
@@ -155,7 +185,7 @@ class ExternalMCPService(BaseToolAdapter):
                         )
                         return False
                 except (EOFError, KeyboardInterrupt):
-                    print("\nInstallation cancelled")
+                    print("\nInstallation cancelled", file=sys.stderr)
                     return False
             else:
                 # Non-interactive: default to pip
@@ -176,7 +206,7 @@ class ExternalMCPService(BaseToolAdapter):
     async def _install_via_pip(self) -> bool:
         """Install package via pip."""
         try:
-            print(f"\n📦 Installing {self.package_name} via pip...")
+            print(f"\n📦 Installing {self.package_name} via pip...", file=sys.stderr)
             result = subprocess.run(
                 [sys.executable, "-m", "pip", "install", self.package_name],
                 capture_output=True,
@@ -186,21 +216,21 @@ class ExternalMCPService(BaseToolAdapter):
             )
 
             if result.returncode == 0:
-                print(f"✓ Successfully installed {self.package_name}")
+                print(f"✓ Successfully installed {self.package_name}", file=sys.stderr)
                 self.logger.info(f"Successfully installed {self.package_name} via pip")
                 return True
 
             error_msg = result.stderr.strip() if result.stderr else "Unknown error"
-            print(f"✗ Installation failed: {error_msg}")
+            print(f"✗ Installation failed: {error_msg}", file=sys.stderr)
             self.logger.error(f"Failed to install {self.package_name}: {error_msg}")
             return False
 
         except subprocess.TimeoutExpired:
-            print("✗ Installation timed out")
+            print("✗ Installation timed out", file=sys.stderr)
             self.logger.error(f"Installation of {self.package_name} timed out")
             return False
         except Exception as e:
-            print(f"✗ Installation error: {e}")
+            print(f"✗ Installation error: {e}", file=sys.stderr)
             self.logger.error(f"Error installing {self.package_name}: {e}")
             return False
 
@@ -217,12 +247,12 @@ class ExternalMCPService(BaseToolAdapter):
             )
 
             if pipx_check.returncode != 0:
-                print("✗ pipx is not installed")
-                print("Install pipx first: python -m pip install pipx")
+                print("✗ pipx is not installed", file=sys.stderr)
+                print("Install pipx first: python -m pip install pipx", file=sys.stderr)
                 self.logger.error("pipx not available for installation")
                 return False
 
-            print(f"\n📦 Installing {self.package_name} via pipx...")
+            print(f"\n📦 Installing {self.package_name} via pipx...", file=sys.stderr)
             result = subprocess.run(
                 ["pipx", "install", self.package_name],
                 capture_output=True,
@@ -232,26 +262,26 @@ class ExternalMCPService(BaseToolAdapter):
             )
 
             if result.returncode == 0:
-                print(f"✓ Successfully installed {self.package_name}")
+                print(f"✓ Successfully installed {self.package_name}", file=sys.stderr)
                 self.logger.info(f"Successfully installed {self.package_name} via pipx")
                 return True
 
             error_msg = result.stderr.strip() if result.stderr else "Unknown error"
-            print(f"✗ Installation failed: {error_msg}")
+            print(f"✗ Installation failed: {error_msg}", file=sys.stderr)
             self.logger.error(f"Failed to install {self.package_name}: {error_msg}")
             return False
 
         except FileNotFoundError:
-            print("✗ pipx command not found")
-            print("Install pipx first: python -m pip install pipx")
+            print("✗ pipx command not found", file=sys.stderr)
+            print("Install pipx first: python -m pip install pipx", file=sys.stderr)
             self.logger.error("pipx command not found")
             return False
         except subprocess.TimeoutExpired:
-            print("✗ Installation timed out")
+            print("✗ Installation timed out", file=sys.stderr)
             self.logger.error(f"Installation of {self.package_name} timed out")
             return False
         except Exception as e:
-            print(f"✗ Installation error: {e}")
+            print(f"✗ Installation error: {e}", file=sys.stderr)
             self.logger.error(f"Error installing {self.package_name}: {e}")
             return False
 
@@ -522,13 +552,20 @@ class MCPBrowserService(ExternalMCPService):
 class ExternalMCPServiceManager:
     """Manager for external MCP services.
 
-    This manager is responsible for checking and installing Python packages
-    for external MCP services. The actual registration of these services
-    happens in Claude Code configuration as separate MCP servers.
+    This manager is responsible for detecting (but NOT installing) Python packages
+    for external MCP services. The actual registration of these services happens
+    in Claude Code configuration as separate MCP servers.
+
+    IMPORTANT: As of v4.9.0, this manager NO LONGER auto-installs missing services.
+    Users must manually install external services using pipx or pip:
+        - pipx install mcp-vector-search
+        - pipx install mcp-browser
+        - pipx install kuzu-memory
+        - pipx install mcp-ticketer
 
-    Note: This class is maintained for backward compatibility and package
-    management. The actual tool registration is handled by separate MCP
-    server instances in Claude Code.
+    Note: This class is maintained for backward compatibility and service detection.
+    The actual tool registration is handled by separate MCP server instances in
+    Claude Code.
     """
 
     def __init__(self):
@@ -539,20 +576,34 @@ class ExternalMCPServiceManager:
     async def initialize_services(self) -> List[ExternalMCPService]:
         """Initialize all external MCP services.
 
-        This method checks if external service packages are installed
-        and attempts to install them if missing. It does NOT register
-        them as tools in the gateway - they run as separate MCP servers.
+        This method checks if external service packages are already installed
+        and registers them if available. It does NOT auto-install missing services.
+
+        External MCP services (mcp-vector-search, mcp-browser, kuzu-memory, mcp-ticketer)
+        must be manually installed by users. This gives users explicit control over
+        which services they want to use.
+
+        Installation instructions:
+        - mcp-vector-search: pipx install mcp-vector-search
+        - mcp-browser: pipx install mcp-browser
+        - kuzu-memory: pipx install kuzu-memory
+        - mcp-ticketer: pipx install mcp-ticketer
+
+        Services run as separate MCP servers in Claude Code, not as tools within
+        the gateway.
         """
         # Create service instances
-        # Note: kuzu-memory is configured via MCPConfigManager and runs as a separate MCP server
-        # It doesn't need to be included here since it's already set up through the MCP config
+        # Note: kuzu-memory and mcp-ticketer are configured via MCPConfigManager
+        # and run as separate MCP servers. They don't need to be included here
+        # since they're already set up through the MCP config.
         services = [MCPVectorSearchService(), MCPBrowserService()]
 
-        # Initialize each service
+        # Initialize each service (check if installed, but DO NOT auto-install)
         initialized_services = []
         for service in services:
             try:
-                if await service.initialize():
+                # Pass auto_install=False to prevent automatic installation
+                if await service.initialize(auto_install=False, interactive=False):
                     initialized_services.append(service)
                     if self.logger:
                         self.logger.info(
@@ -560,7 +611,8 @@ class ExternalMCPServiceManager:
                         )
                 elif self.logger:
                     self.logger.debug(
-                        f"Service not available (optional): {service.service_name}"
+                        f"Service not available (optional): {service.service_name}. "
+                        f"Install manually with: pipx install {service.package_name}"
                     )
             except Exception as e:
                 if self.logger:

claude_mpm/services/mcp_gateway/tools/health_check_tool.py

@@ -26,6 +26,7 @@ from typing import Any, Dict
 import psutil
 
 from claude_mpm.config.paths import paths
+from claude_mpm.core.enums import HealthStatus, OperationResult, ServiceState
 from claude_mpm.core.logger import get_logger
 from claude_mpm.services.mcp_gateway.core.interfaces import (
     MCPToolDefinition,
@@ -168,20 +169,20 @@ class HealthCheckTool(BaseToolAdapter):
                 if i < len(check_results):
                     if isinstance(check_results[i], Exception):
                         results["checks"][check_name] = {
-                            "status": "error",
+                            "status": OperationResult.ERROR,
                             "error": str(check_results[i]),
                         }
                     else:
                         results["checks"][check_name] = check_results[i]
                 else:
                     results["checks"][check_name] = {
-                        "status": "timeout",
+                        "status": OperationResult.TIMEOUT,
                         "error": "Check timed out",
                     }
 
         except asyncio.TimeoutError:
             results["checks"]["timeout"] = {
-                "status": "error",
+                "status": OperationResult.ERROR,
                 "error": f"Health checks timed out after {timeout} seconds",
             }
 
@@ -194,7 +195,7 @@ class HealthCheckTool(BaseToolAdapter):
     async def _check_system_health(self, detailed: bool) -> Dict[str, Any]:
         """Check system health (CPU, memory, disk, etc.)."""
         check_result = {
-            "status": "healthy",
+            "status": ServiceState.RUNNING,
             "checks": {},
             "warnings": [],
             "errors": [],
@@ -219,7 +220,7 @@ class HealthCheckTool(BaseToolAdapter):
 
             if memory_usage > 90:
                 check_result["errors"].append("High memory usage detected")
-                check_result["status"] = "unhealthy"
+                check_result["status"] = HealthStatus.UNHEALTHY
             elif memory_usage > 80:
                 check_result["warnings"].append("Elevated memory usage")
 
@@ -232,7 +233,7 @@ class HealthCheckTool(BaseToolAdapter):
 
             if cpu_usage > 95:
                 check_result["errors"].append("High CPU usage detected")
-                check_result["status"] = "unhealthy"
+                check_result["status"] = HealthStatus.UNHEALTHY
             elif cpu_usage > 80:
                 check_result["warnings"].append("Elevated CPU usage")
 
@@ -248,7 +249,7 @@ class HealthCheckTool(BaseToolAdapter):
 
                 if disk_usage_percent > 95:
                     check_result["errors"].append("Disk space critically low")
-                    check_result["status"] = "unhealthy"
+                    check_result["status"] = HealthStatus.UNHEALTHY
                 elif disk_usage_percent > 85:
                     check_result["warnings"].append("Disk space running low")
 
@@ -262,7 +263,7 @@ class HealthCheckTool(BaseToolAdapter):
             }
 
         except Exception as e:
-            check_result["status"] = "error"
+            check_result["status"] = HealthStatus.UNHEALTHY
             check_result["errors"].append(f"System health check failed: {e}")
 
         return check_result
@@ -270,7 +271,7 @@ class HealthCheckTool(BaseToolAdapter):
     async def _check_gateway_health(self, detailed: bool) -> Dict[str, Any]:
         """Check MCP Gateway health."""
         check_result = {
-            "status": "healthy",
+            "status": ServiceState.RUNNING,
             "checks": {},
             "warnings": [],
             "errors": [],
@@ -302,10 +303,10 @@ class HealthCheckTool(BaseToolAdapter):
 
             if not mcp_dir.exists():
                 check_result["errors"].append("MCP directory does not exist")
-                check_result["status"] = "unhealthy"
+                check_result["status"] = HealthStatus.UNHEALTHY
 
         except Exception as e:
-            check_result["status"] = "error"
+            check_result["status"] = HealthStatus.UNHEALTHY
             check_result["errors"].append(f"Gateway health check failed: {e}")
 
         return check_result
@@ -313,7 +314,7 @@ class HealthCheckTool(BaseToolAdapter):
     async def _check_tools_health(self, detailed: bool) -> Dict[str, Any]:
         """Check MCP tools health."""
         check_result = {
-            "status": "healthy",
+            "status": ServiceState.RUNNING,
             "checks": {},
             "warnings": [],
             "errors": [],
@@ -353,11 +354,11 @@ class HealthCheckTool(BaseToolAdapter):
                 )
 
             if len(available_essential) == 0:
-                check_result["status"] = "unhealthy"
+                check_result["status"] = HealthStatus.UNHEALTHY
                 check_result["errors"].append("No essential tools available")
 
         except Exception as e:
-            check_result["status"] = "error"
+            check_result["status"] = HealthStatus.UNHEALTHY
             check_result["errors"].append(f"Tools health check failed: {e}")
 
         return check_result
@@ -365,7 +366,7 @@ class HealthCheckTool(BaseToolAdapter):
     async def _check_config_health(self, detailed: bool) -> Dict[str, Any]:
         """Check configuration health."""
         check_result = {
-            "status": "healthy",
+            "status": ServiceState.RUNNING,
             "checks": {},
             "warnings": [],
             "errors": [],
@@ -401,7 +402,7 @@ class HealthCheckTool(BaseToolAdapter):
             }
 
         except Exception as e:
-            check_result["status"] = "error"
+            check_result["status"] = HealthStatus.UNHEALTHY
             check_result["errors"].append(f"Config health check failed: {e}")
 
         return check_result
@@ -413,13 +414,13 @@ class HealthCheckTool(BaseToolAdapter):
 
         statuses = [check.get("status", "unknown") for check in checks.values()]
 
-        if "error" in statuses:
-            return "error"
-        if "unhealthy" in statuses:
+        # Check for unhealthy (handle both string and enum)
+        if HealthStatus.UNHEALTHY in statuses or "unhealthy" in statuses:
             return "unhealthy"
         if "warning" in statuses:
             return "warning"
-        if all(status == "healthy" for status in statuses):
+        # Check for healthy (handle both string and enum)
+        if all(status in (HealthStatus.HEALTHY, "healthy") for status in statuses):
             return "healthy"
         return "unknown"
 
@@ -436,19 +437,20 @@ class HealthCheckTool(BaseToolAdapter):
         for check_name, check_result in checks.items():
             status = check_result.get("status", "unknown")
 
-            if status == "healthy":
+            # Check for healthy (handle both string and enum)
+            if status in (HealthStatus.HEALTHY, "healthy"):
                 summary["healthy"] += 1
-            elif status in ["warning", "unhealthy"]:
+            elif status in ["warning", HealthStatus.UNHEALTHY, "unhealthy"]:
                 summary["warnings"] += 1
                 # Collect warning messages
                 warnings = check_result.get("warnings", [])
                 for warning in warnings:
                     summary["issues"].append(f"{check_name}: {warning}")
-            elif status == "error":
-                summary["errors"] += 1
-                # Collect error messages
-                errors = check_result.get("errors", [])
-                for error in errors:
-                    summary["issues"].append(f"{check_name}: {error}")
+                # Collect error messages if status is unhealthy
+                if status in (HealthStatus.UNHEALTHY, "unhealthy"):
+                    summary["errors"] += 1
+                    errors = check_result.get("errors", [])
+                    for error in errors:
+                        summary["issues"].append(f"{check_name}: {error}")
 
         return summary

claude_mpm/services/memory_hook_service.py

@@ -11,6 +11,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 from typing import Any, Dict
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.interfaces import MemoryHookInterface
 
 
@@ -463,5 +464,7 @@ class MemoryHookService(BaseService, MemoryHookInterface):
             "hook_service_available": self.hook_service is not None,
             "memory_enabled": self.is_memory_enabled(),
             "total_hooks": len(self.registered_hooks),
-            "status": "active" if self.registered_hooks else "inactive",
+            "status": (
+                ServiceState.RUNNING if self.registered_hooks else ServiceState.IDLE
+            ),
         }

claude_mpm/services/monitor/daemon_manager.py

@@ -31,6 +31,7 @@ import time
 from pathlib import Path
 from typing import Optional, Tuple
 
+from ...core.enums import OperationResult
 from ...core.logging_config import get_logger
 
 
@@ -906,7 +907,7 @@ class DaemonManager:
                     with self.startup_status_file.open() as f:
                         status = f.read().strip()
 
-                    if status == "success":
+                    if status == OperationResult.SUCCESS:
                         # Cleanup status file
                         Path(self.startup_status_file).unlink(missing_ok=True)
                         return True
@@ -936,7 +937,7 @@ class DaemonManager:
                 # Don't check if file exists - we need to write to it regardless
                 # The parent created it and is waiting for us to update it
                 with self.startup_status_file.open("w") as f:
-                    f.write("success")
+                    f.write(OperationResult.SUCCESS)
                     f.flush()  # Ensure it's written immediately
                     os.fsync(f.fileno())  # Force write to disk
             except Exception:

claude_mpm/services/monitor/handlers/dashboard.py

@@ -18,6 +18,7 @@ from typing import Dict, Set
 
 import socketio
 
+from ....core.enums import ServiceState
 from ....core.logging_config import get_logger
 
 
@@ -128,7 +129,7 @@ class DashboardHandler:
         try:
             status = {
                 "service": "unified-monitor",
-                "status": "running",
+                "status": ServiceState.RUNNING,
                 "clients_connected": len(self.connected_clients),
                 "uptime": asyncio.get_event_loop().time(),
                 "features": {

claude_mpm/services/monitor/handlers/hooks.py

@@ -19,6 +19,7 @@ from typing import Dict, List
 
 import socketio
 
+from ....core.enums import ServiceState
 from ....core.logging_config import get_logger
 
 
@@ -170,7 +171,7 @@ class HookHandler:
             session_info = {
                 "session_id": session_id,
                 "start_time": asyncio.get_event_loop().time(),
-                "status": "active",
+                "status": ServiceState.RUNNING,
                 "event_count": 0,
                 "last_activity": asyncio.get_event_loop().time(),
                 "metadata": data.get("metadata", {}),

claude_mpm/services/monitor/management/lifecycle.py

@@ -23,6 +23,7 @@ import time
 from pathlib import Path
 from typing import Optional, Tuple
 
+from ....core.enums import OperationResult
 from ....core.logging_config import get_logger
 
 
@@ -388,7 +389,7 @@ class DaemonLifecycle:
                     with self.startup_status_file.open() as f:
                         status = f.read().strip()
 
-                    if status == "success":
+                    if status == OperationResult.SUCCESS:
                         # Child started successfully
                         self._cleanup_status_file()
                         return True
@@ -438,7 +439,7 @@ class DaemonLifecycle:
         if self.startup_status_file:
             try:
                 with self.startup_status_file.open("w") as f:
-                    f.write("success")
+                    f.write(OperationResult.SUCCESS)
             except Exception as e:
                 self.logger.error(f"Failed to report startup success: {e}")
 

claude_mpm/services/monitor/server.py

@@ -26,6 +26,7 @@ from typing import Dict, Optional
 import socketio
 from aiohttp import web
 
+from ...core.enums import ServiceState
 from ...core.logging_config import get_logger
 from ...dashboard.api.simple_directory import list_directory
 from .event_emitter import get_event_emitter
@@ -333,7 +334,7 @@ class UnifiedMonitorServer:
 
                 return web.json_response(
                     {
-                        "status": "healthy",
+                        "status": ServiceState.RUNNING,
                         "service": "claude-mpm-monitor",  # Important: must match what is_our_service() checks
                         "version": version,
                         "port": self.port,

claude_mpm/services/session_management_service.py

@@ -17,6 +17,7 @@ from datetime import timezone
 from typing import Any, Dict, List, Optional
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import OperationResult, ServiceState
 from claude_mpm.services.core.interfaces import SessionManagementInterface
 
 
@@ -223,7 +224,7 @@ class SessionManagementService(BaseService, SessionManagementInterface):
             "id": session_id,
             "config": session_config,
             "start_time": time.time(),
-            "status": "active",
+            "status": ServiceState.RUNNING,
             "type": session_config.get("type", "interactive"),
         }
 
@@ -267,7 +268,7 @@ class SessionManagementService(BaseService, SessionManagementInterface):
             return self.active_sessions[session_id].copy()
         return {
             "id": session_id,
-            "status": "not_found",
+            "status": OperationResult.ERROR,
             "error": "Session not found",
         }