claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/services/mcp_gateway/core/base.py

@@ -8,25 +8,12 @@ Part of ISS-0034: Infrastructure Setup - MCP Gateway Project Foundation
 """
 
 import asyncio
-from enum import Enum
 from typing import Any, Dict, Optional
 
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.base import BaseService
 
 
-class MCPServiceState(Enum):
-    """MCP service lifecycle states."""
-
-    UNINITIALIZED = "uninitialized"
-    INITIALIZING = "initializing"
-    INITIALIZED = "initialized"
-    STARTING = "starting"
-    RUNNING = "running"
-    STOPPING = "stopping"
-    STOPPED = "stopped"
-    ERROR = "error"
-
-
 class BaseMCPService(BaseService):
     """
     Base class for all MCP Gateway services.
@@ -53,7 +40,7 @@ class BaseMCPService(BaseService):
             config: Service-specific configuration
         """
         super().__init__(service_name or "MCPService", config)
-        self._state = MCPServiceState.UNINITIALIZED
+        self._state = ServiceState.UNINITIALIZED
         self._health_status = {
             "healthy": False,
             "state": self._state.value,
@@ -76,13 +63,13 @@ class BaseMCPService(BaseService):
         """
         async with self._state_lock:
             if self._state not in [
-                MCPServiceState.UNINITIALIZED,
-                MCPServiceState.STOPPED,
+                ServiceState.UNINITIALIZED,
+                ServiceState.STOPPED,
             ]:
                 self.log_warning(f"Cannot initialize from state {self._state.value}")
                 return False
 
-            self._state = MCPServiceState.INITIALIZING
+            self._state = ServiceState.INITIALIZING
             self.log_info("Initializing MCP service")
 
         try:
@@ -91,13 +78,13 @@ class BaseMCPService(BaseService):
 
             async with self._state_lock:
                 if success:
-                    self._state = MCPServiceState.INITIALIZED
+                    self._state = ServiceState.INITIALIZED
                     self._initialized = True
                     self._health_status["healthy"] = True
                     self._health_status["state"] = self._state.value
                     self.log_info("MCP service initialized successfully")
                 else:
-                    self._state = MCPServiceState.ERROR
+                    self._state = ServiceState.ERROR
                     self._health_status["healthy"] = False
                     self._health_status["state"] = self._state.value
                     self.log_error("MCP service initialization failed")
@@ -106,7 +93,7 @@ class BaseMCPService(BaseService):
 
         except Exception as e:
             async with self._state_lock:
-                self._state = MCPServiceState.ERROR
+                self._state = ServiceState.ERROR
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self._health_status["details"]["error"] = str(e)
@@ -134,11 +121,11 @@ class BaseMCPService(BaseService):
             True if startup successful
         """
         async with self._state_lock:
-            if self._state != MCPServiceState.INITIALIZED:
+            if self._state != ServiceState.INITIALIZED:
                 self.log_warning(f"Cannot start from state {self._state.value}")
                 return False
 
-            self._state = MCPServiceState.STARTING
+            self._state = ServiceState.STARTING
             self.log_info("Starting MCP service")
 
         try:
@@ -146,12 +133,12 @@ class BaseMCPService(BaseService):
 
             async with self._state_lock:
                 if success:
-                    self._state = MCPServiceState.RUNNING
+                    self._state = ServiceState.RUNNING
                     self._health_status["healthy"] = True
                     self._health_status["state"] = self._state.value
                     self.log_info("MCP service started successfully")
                 else:
-                    self._state = MCPServiceState.ERROR
+                    self._state = ServiceState.ERROR
                     self._health_status["healthy"] = False
                     self._health_status["state"] = self._state.value
                     self.log_error("MCP service startup failed")
@@ -160,7 +147,7 @@ class BaseMCPService(BaseService):
 
         except Exception as e:
             async with self._state_lock:
-                self._state = MCPServiceState.ERROR
+                self._state = ServiceState.ERROR
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self._health_status["details"]["error"] = str(e)
@@ -188,18 +175,18 @@ class BaseMCPService(BaseService):
         Subclasses should override _do_shutdown() for custom shutdown logic.
         """
         async with self._state_lock:
-            if self._state in [MCPServiceState.STOPPED, MCPServiceState.STOPPING]:
+            if self._state in [ServiceState.STOPPED, ServiceState.STOPPING]:
                 self.log_warning(f"Already in state {self._state.value}")
                 return
 
-            self._state = MCPServiceState.STOPPING
+            self._state = ServiceState.STOPPING
             self.log_info("Shutting down MCP service")
 
         try:
             await self._do_shutdown()
 
             async with self._state_lock:
-                self._state = MCPServiceState.STOPPED
+                self._state = ServiceState.STOPPED
                 self._shutdown = True
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
@@ -207,7 +194,7 @@ class BaseMCPService(BaseService):
 
         except Exception as e:
             async with self._state_lock:
-                self._state = MCPServiceState.ERROR
+                self._state = ServiceState.ERROR
                 self._health_status["healthy"] = False
                 self._health_status["state"] = self._state.value
                 self._health_status["details"]["error"] = str(e)
@@ -232,7 +219,7 @@ class BaseMCPService(BaseService):
         self.log_info("Restarting MCP service")
 
         # Shutdown if running
-        if self._state == MCPServiceState.RUNNING:
+        if self._state == ServiceState.RUNNING:
             await self.shutdown()
 
         # Re-initialize

claude_mpm/services/mcp_gateway/main.py

@@ -314,6 +314,36 @@ class MCPGatewayOrchestrator:
             except Exception as e:
                 self.logger.warning(f"Could not load document summarizer: {e}")
 
+        # Kuzu-Memory Service (now a required dependency)
+        try:
+            from .tools.kuzu_memory_service import KuzuMemoryService
+
+            tools.append(KuzuMemoryService())
+            self.logger.info("KuzuMemoryService added to built-in tools")
+        except Exception as e:
+            self.logger.warning(f"Could not load KuzuMemoryService: {e}")
+
+        # MCP Vector Search Service (optional - will auto-install on first use)
+        try:
+            from .tools.external_mcp_services import MCPVectorSearchService
+
+            vector_search = MCPVectorSearchService()
+            # Try to initialize without interactive prompts during gateway startup
+            # This will only succeed if already installed
+            init_success = await vector_search.initialize(
+                auto_install=False, interactive=False
+            )
+
+            if init_success:
+                tools.append(vector_search)
+                self.logger.info("MCPVectorSearchService added to built-in tools")
+            else:
+                self.logger.debug(
+                    "mcp-vector-search not installed - will be available via auto-install on first use"
+                )
+        except Exception as e:
+            self.logger.debug(f"Could not load MCPVectorSearchService: {e}")
+
         # Ticket tools removed - mcp-ticketer provides ticket functionality
 
         if not tools:

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):
         """
@@ -64,21 +79,38 @@ class ExternalMCPService(BaseToolAdapter):
             execution_time=0.0,
         )
 
-    async def initialize(self) -> bool:
-        """Initialize the external service."""
+    async def initialize(
+        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 (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:
-                self.logger.debug(
-                    f"{self.package_name} not installed - will attempt automatic installation if needed"
+            if not self._is_installed and auto_install:
+                # 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()
+                await self._install_package(interactive=interactive)
                 self._is_installed = await self._check_installation()
 
             if not self._is_installed:
-                self.logger.error(f"Failed to install {self.package_name}")
+                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")
@@ -90,9 +122,21 @@ class ExternalMCPService(BaseToolAdapter):
 
     async def _check_installation(self) -> bool:
         """Check if the package is installed."""
+        # First check if importable (faster and more reliable)
+        import_name = self.package_name.replace("-", "_")
+        try:
+            import importlib.util
+
+            spec = importlib.util.find_spec(import_name)
+            if spec is not None:
+                return True
+        except (ImportError, ModuleNotFoundError, ValueError):
+            pass
+
+        # Fallback: try running as module
         try:
             result = subprocess.run(
-                [sys.executable, "-m", self.package_name.replace("-", "_"), "--help"],
+                [sys.executable, "-m", import_name, "--help"],
                 capture_output=True,
                 text=True,
                 timeout=5,
@@ -106,25 +150,133 @@ class ExternalMCPService(BaseToolAdapter):
         ):
             return False
 
-    async def _install_package(self) -> bool:
-        """Install the package using pip."""
+    async def _install_package(self, interactive: bool = True) -> bool:
+        """Install the package using pip or pipx.
+
+        Args:
+            interactive: Whether to prompt user for installation method choice
+        """
         try:
-            self.logger.info(f"Installing {self.package_name}...")
+            install_method = None
+
+            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)")
+
+                try:
+                    choice = input("\nChoose option (1/2/3) [1]: ").strip() or "1"
+                    if choice == "1":
+                        install_method = "pip"
+                    elif choice == "2":
+                        install_method = "pipx"
+                    else:
+                        self.logger.info(
+                            f"Skipping installation of {self.package_name}"
+                        )
+                        return False
+                except (EOFError, KeyboardInterrupt):
+                    print("\nInstallation cancelled")
+                    return False
+            else:
+                # Non-interactive: default to pip
+                install_method = "pip"
+
+            # Install using selected method
+            if install_method == "pip":
+                return await self._install_via_pip()
+            if install_method == "pipx":
+                return await self._install_via_pipx()
+
+            return False
+
+        except Exception as e:
+            self.logger.error(f"Error installing {self.package_name}: {e}")
+            return False
+
+    async def _install_via_pip(self) -> bool:
+        """Install package via pip."""
+        try:
+            print(f"\n📦 Installing {self.package_name} via pip...")
             result = subprocess.run(
                 [sys.executable, "-m", "pip", "install", self.package_name],
                 capture_output=True,
                 text=True,
-                timeout=30,
+                timeout=120,
                 check=False,
             )
 
             if result.returncode == 0:
-                self.logger.info(f"Successfully installed {self.package_name}")
+                print(f"✓ Successfully installed {self.package_name}")
+                self.logger.info(f"Successfully installed {self.package_name} via pip")
                 return True
-            self.logger.error(f"Failed to install {self.package_name}: {result.stderr}")
+
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            print(f"✗ Installation failed: {error_msg}")
+            self.logger.error(f"Failed to install {self.package_name}: {error_msg}")
+            return False
+
+        except subprocess.TimeoutExpired:
+            print("✗ Installation timed out")
+            self.logger.error(f"Installation of {self.package_name} timed out")
+            return False
+        except Exception as e:
+            print(f"✗ Installation error: {e}")
+            self.logger.error(f"Error installing {self.package_name}: {e}")
+            return False
+
+    async def _install_via_pipx(self) -> bool:
+        """Install package via pipx."""
+        try:
+            # Check if pipx is available
+            pipx_check = subprocess.run(
+                ["pipx", "--version"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+
+            if pipx_check.returncode != 0:
+                print("✗ pipx is not installed")
+                print("Install pipx first: python -m pip install pipx")
+                self.logger.error("pipx not available for installation")
+                return False
+
+            print(f"\n📦 Installing {self.package_name} via pipx...")
+            result = subprocess.run(
+                ["pipx", "install", self.package_name],
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+            )
+
+            if result.returncode == 0:
+                print(f"✓ Successfully installed {self.package_name}")
+                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}")
+            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")
+            self.logger.error("pipx command not found")
+            return False
+        except subprocess.TimeoutExpired:
+            print("✗ Installation timed out")
+            self.logger.error(f"Installation of {self.package_name} timed out")
+            return False
         except Exception as e:
+            print(f"✗ Installation error: {e}")
             self.logger.error(f"Error installing {self.package_name}: {e}")
             return False
 
@@ -395,13 +547,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.
 
-    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.
+    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 service detection.
+    The actual tool registration is handled by separate MCP server instances in
+    Claude Code.
     """
 
     def __init__(self):
@@ -412,20 +571,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(
@@ -433,7 +606,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: