claude-mpm 4.14.9__py3-none-any.whl → 4.15.1__py3-none-any.whl

claude_mpm/services/diagnostics/models.py

@@ -6,17 +6,9 @@ consistency across all checks and reporting.
 """
 
 from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
-
-class DiagnosticStatus(Enum):
-    """Status levels for diagnostic results."""
-
-    OK = "ok"
-    WARNING = "warning"
-    ERROR = "error"
-    SKIPPED = "skipped"
+from ...core.enums import OperationResult, ValidationSeverity
 
 
 @dataclass
@@ -25,10 +17,13 @@ class DiagnosticResult:
 
     WHY: Standardized result format ensures consistent reporting
     and makes it easy to aggregate and display results.
+
+    Note: status uses Union[OperationResult, ValidationSeverity] to support both
+    operation results (SUCCESS, SKIPPED) and validation results (WARNING, ERROR).
     """
 
     category: str  # e.g., "Installation", "Agents", "MCP Server"
-    status: DiagnosticStatus
+    status: Union[OperationResult, ValidationSeverity]
     message: str
     details: Dict[str, Any] = field(default_factory=dict)
     fix_command: Optional[str] = None
@@ -50,16 +45,16 @@ class DiagnosticResult:
     @property
     def has_issues(self) -> bool:
         """Check if this result indicates any issues."""
-        return self.status in (DiagnosticStatus.WARNING, DiagnosticStatus.ERROR)
+        return self.status in (ValidationSeverity.WARNING, ValidationSeverity.ERROR)
 
     @property
     def severity_level(self) -> int:
         """Get numeric severity level for sorting."""
         severity_map = {
-            DiagnosticStatus.OK: 0,
-            DiagnosticStatus.SKIPPED: 1,
-            DiagnosticStatus.WARNING: 2,
-            DiagnosticStatus.ERROR: 3,
+            OperationResult.SUCCESS: 0,
+            OperationResult.SKIPPED: 1,
+            ValidationSeverity.WARNING: 2,
+            ValidationSeverity.ERROR: 3,
         }
         return severity_map.get(self.status, 0)
 
@@ -84,13 +79,13 @@ class DiagnosticSummary:
         self.results.append(result)
         self.total_checks += 1
 
-        if result.status == DiagnosticStatus.OK:
+        if result.status == OperationResult.SUCCESS:
             self.ok_count += 1
-        elif result.status == DiagnosticStatus.WARNING:
+        elif result.status == ValidationSeverity.WARNING:
             self.warning_count += 1
-        elif result.status == DiagnosticStatus.ERROR:
+        elif result.status == ValidationSeverity.ERROR:
             self.error_count += 1
-        elif result.status == DiagnosticStatus.SKIPPED:
+        elif result.status == OperationResult.SKIPPED:
             self.skipped_count += 1
 
     @property
@@ -99,13 +94,13 @@ class DiagnosticSummary:
         return self.warning_count > 0 or self.error_count > 0
 
     @property
-    def overall_status(self) -> DiagnosticStatus:
+    def overall_status(self) -> Union[OperationResult, ValidationSeverity]:
         """Get overall system status."""
         if self.error_count > 0:
-            return DiagnosticStatus.ERROR
+            return ValidationSeverity.ERROR
         if self.warning_count > 0:
-            return DiagnosticStatus.WARNING
-        return DiagnosticStatus.OK
+            return ValidationSeverity.WARNING
+        return OperationResult.SUCCESS
 
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for JSON serialization."""

claude_mpm/services/local_ops/__init__.py

@@ -32,9 +32,9 @@ USAGE:
         DeploymentStateManager,
         HealthCheckManager,
         StartConfig,
-        ProcessStatus,
         HealthStatus,
     )
+    from claude_mpm.core.enums import ServiceState
 
     # Initialize managers
     state_manager = DeploymentStateManager(".claude-mpm/deployment-state.json")
@@ -54,6 +54,8 @@ USAGE:
 
     # Start background monitoring
     health_manager.start_monitoring()
+
+Note: ProcessStatus has been consolidated into ServiceState (core.enums) as of Phase 3A Batch 24.
 """
 
 # Re-export data models and interfaces for convenience
@@ -84,7 +86,6 @@ from claude_mpm.services.core.models.process import (
     PROTECTED_PORT_RANGES,
     DeploymentState,
     ProcessInfo,
-    ProcessStatus,
     StartConfig,
     is_port_protected,
 )
@@ -147,7 +148,6 @@ __all__ = [
     "ProcessInfo",
     "ProcessSpawnError",
     # Data models - Process
-    "ProcessStatus",
     "ResourceMonitor",
     "ResourceUsage",
     "RestartAttempt",

claude_mpm/services/local_ops/process_manager.py

@@ -42,6 +42,7 @@ from typing import List, Optional
 
 import psutil
 
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.base import SyncBaseService
 from claude_mpm.services.core.interfaces.process import (
     IDeploymentStateManager,
@@ -50,7 +51,6 @@ from claude_mpm.services.core.interfaces.process import (
 from claude_mpm.services.core.models.process import (
     DeploymentState,
     ProcessInfo,
-    ProcessStatus,
     StartConfig,
     is_port_protected,
 )
@@ -203,7 +203,7 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
                 environment=config.environment,
                 port=allocated_port,
                 started_at=datetime.now(tz=timezone.utc),
-                status=ProcessStatus.RUNNING,
+                status=ServiceState.RUNNING,
                 metadata=config.metadata,
             )
 
@@ -248,13 +248,13 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
             # Process already dead, just update state
             self.log_info(f"Process {deployment.process_id} already dead")
             self.state_manager.update_deployment_status(
-                deployment_id, ProcessStatus.STOPPED
+                deployment_id, ServiceState.STOPPED
             )
             return True
 
         self.log_info(f"Stopping process {deployment.process_id} for {deployment_id}")
         self.state_manager.update_deployment_status(
-            deployment_id, ProcessStatus.STOPPING
+            deployment_id, ServiceState.STOPPING
         )
 
         try:
@@ -262,7 +262,7 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
                 # Force kill immediately
                 self._kill_process_group(process)
                 self.state_manager.update_deployment_status(
-                    deployment_id, ProcessStatus.STOPPED
+                    deployment_id, ServiceState.STOPPED
                 )
                 return True
 
@@ -275,7 +275,7 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
                 if not process.is_running():
                     self.log_info(f"Process {deployment.process_id} stopped gracefully")
                     self.state_manager.update_deployment_status(
-                        deployment_id, ProcessStatus.STOPPED
+                        deployment_id, ServiceState.STOPPED
                     )
                     return True
                 time.sleep(0.1)
@@ -286,14 +286,14 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
             )
             self._kill_process_group(process)
             self.state_manager.update_deployment_status(
-                deployment_id, ProcessStatus.STOPPED
+                deployment_id, ServiceState.STOPPED
             )
             return True
 
         except psutil.NoSuchProcess:
             # Process died during shutdown
             self.state_manager.update_deployment_status(
-                deployment_id, ProcessStatus.STOPPED
+                deployment_id, ServiceState.STOPPED
             )
             return True
 
@@ -370,9 +370,9 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
 
             # Determine status
             if process.is_running():
-                status = ProcessStatus.RUNNING
+                status = ServiceState.RUNNING
             else:
-                status = ProcessStatus.STOPPED
+                status = ServiceState.STOPPED
 
             return ProcessInfo(
                 deployment_id=deployment_id,
@@ -389,13 +389,13 @@ class LocalProcessManager(SyncBaseService, ILocalProcessManager):
             return ProcessInfo(
                 deployment_id=deployment_id,
                 process_id=deployment.process_id,
-                status=ProcessStatus.CRASHED,
+                status=ServiceState.ERROR,  # CRASHED semantically maps to ERROR state
                 port=deployment.port,
                 error_message="Process no longer exists",
             )
 
     def list_processes(
-        self, status_filter: Optional[ProcessStatus] = None
+        self, status_filter: Optional[ServiceState] = None
     ) -> List[ProcessInfo]:
         """
         List all managed processes.

claude_mpm/services/local_ops/state_manager.py

@@ -30,9 +30,10 @@ from typing import Dict, List, Optional
 import psutil
 from filelock import FileLock
 
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.base import SyncBaseService
 from claude_mpm.services.core.interfaces.process import IDeploymentStateManager
-from claude_mpm.services.core.models.process import DeploymentState, ProcessStatus
+from claude_mpm.services.core.models.process import DeploymentState
 
 
 class StateCorruptionError(Exception):
@@ -206,12 +207,12 @@ class DeploymentStateManager(SyncBaseService, IDeploymentStateManager):
         states = self.load_state()
         return list(states.values())
 
-    def get_deployments_by_status(self, status: ProcessStatus) -> List[DeploymentState]:
+    def get_deployments_by_status(self, status: ServiceState) -> List[DeploymentState]:
         """
         Get all deployments with a specific status.
 
         Args:
-            status: ProcessStatus to filter by
+            status: ServiceState to filter by
 
         Returns:
             List of matching DeploymentState objects
@@ -295,14 +296,14 @@ class DeploymentStateManager(SyncBaseService, IDeploymentStateManager):
             return False
 
     def update_deployment_status(
-        self, deployment_id: str, status: ProcessStatus
+        self, deployment_id: str, status: ServiceState
     ) -> bool:
         """
         Update the status of a deployment.
 
         Args:
             deployment_id: Unique deployment identifier
-            status: New ProcessStatus
+            status: New ServiceState
 
         Returns:
             True if updated, False if deployment not found

claude_mpm/services/local_ops/unified_manager.py

@@ -45,12 +45,12 @@ from typing import Any, Dict, List, Optional
 
 import yaml
 
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.base import SyncBaseService
 from claude_mpm.services.core.models.health import DeploymentHealth
 from claude_mpm.services.core.models.process import (
     DeploymentState,
     ProcessInfo,
-    ProcessStatus,
     StartConfig,
 )
 from claude_mpm.services.core.models.restart import RestartConfig, RestartHistory
@@ -384,7 +384,7 @@ class UnifiedLocalOpsManager(SyncBaseService):
 
     def list_deployments(
         self,
-        status_filter: Optional[ProcessStatus] = None,
+        status_filter: Optional[ServiceState] = None,
     ) -> List[DeploymentState]:
         """
         List all deployments.

claude_mpm/services/mcp_config_manager.py

@@ -1145,11 +1145,16 @@ class MCPConfigManager:
 
         # Check each service for issues
         for service_name in self.PIPX_SERVICES:
-            self.logger.info(f"🔍 Checking {service_name} for issues...")
+            # Check if service is enabled in config
+            if not self.should_enable_service(service_name):
+                self.logger.debug(f"Skipping {service_name} (disabled in config)")
+                continue
+
+            self.logger.debug(f"🔍 Checking {service_name} for issues...")
             issue_type = self._detect_service_issue(service_name)
             if issue_type:
                 services_to_fix.append((service_name, issue_type))
-                self.logger.info(f"  ⚠️  Found issue with {service_name}: {issue_type}")
+                self.logger.debug(f"  ⚠️  Found issue with {service_name}: {issue_type}")
             else:
                 self.logger.debug(f"  ✅ {service_name} is functioning correctly")
 

claude_mpm/services/mcp_gateway/core/__init__.py

@@ -5,7 +5,7 @@ MCP Gateway Core Module
 Core interfaces and base classes for the MCP Gateway service.
 """
 
-from .base import BaseMCPService, MCPServiceState
+from .base import BaseMCPService
 from .exceptions import (
     MCPCommunicationError,
     MCPConfigurationError,
@@ -38,7 +38,6 @@ __all__ = [
     # Exceptions
     "MCPException",
     "MCPServerError",
-    "MCPServiceState",
     "MCPToolNotFoundError",
     "MCPValidationError",
 ]

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/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")
@@ -522,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.
+
+    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 +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(
@@ -560,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: