claude-mpm 4.14.9__py3-none-any.whl → 4.15.0__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/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:

claude_mpm/services/mcp_gateway/tools/health_check_tool.py

@@ -26,7 +26,7 @@ from typing import Any, Dict
 import psutil
 
 from claude_mpm.config.paths import paths
-from claude_mpm.core.enums import OperationResult, ServiceState
+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,
@@ -220,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")
 
@@ -233,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")
 
@@ -249,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")
 
@@ -263,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
@@ -303,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
@@ -354,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
@@ -402,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
@@ -414,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"
 
@@ -437,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/unified/analyzer_strategies/code_analyzer.py

@@ -196,7 +196,7 @@ class CodeAnalyzerStrategy(AnalyzerStrategy):
         total_metrics = {}
         for file_path in code_files:
             file_result = self._analyze_file(file_path, options)
-            if file_result["status"] == "success":
+            if file_result["status"] == OperationResult.SUCCESS:
                 results["files"].append(file_result)
 
                 # Aggregate metrics
@@ -427,7 +427,7 @@ class CodeAnalyzerStrategy(AnalyzerStrategy):
         """Extract key metrics from analysis results."""
         metrics = {}
 
-        if analysis_result.get("status") != "success":
+        if analysis_result.get("status") != OperationResult.SUCCESS:
             return metrics
 
         # Extract relevant metrics

claude_mpm/services/unified/analyzer_strategies/security_analyzer.py

@@ -302,7 +302,7 @@ class SecurityAnalyzerStrategy(AnalyzerStrategy):
 
                 file_result = self._analyze_file(file_path, options)
                 if (
-                    file_result["status"] == "success"
+                    file_result["status"] == OperationResult.SUCCESS
                     and file_result["vulnerabilities"]
                 ):
                     results["files"].append(file_result)
@@ -646,7 +646,7 @@ class SecurityAnalyzerStrategy(AnalyzerStrategy):
         """Extract key metrics from analysis results."""
         metrics = {}
 
-        if analysis_result.get("status") != "success":
+        if analysis_result.get("status") != OperationResult.SUCCESS:
             return metrics
 
         if analysis_result.get("type") == "file":

claude_mpm/services/unified/deployment_strategies/local.py

@@ -19,7 +19,7 @@ from typing import Any, Dict, List, Optional
 
 import yaml
 
-from claude_mpm.core.enums import OperationResult
+from claude_mpm.core.enums import HealthStatus, OperationResult
 from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.services.unified.strategies import StrategyMetadata, StrategyPriority
 
@@ -289,10 +289,10 @@ class LocalDeploymentStrategy(DeploymentStrategy):
 
             # Check if any file is missing
             if any(not check for check in health["checks"].values()):
-                health["status"] = "degraded"
+                health["status"] = HealthStatus.DEGRADED
 
         else:
-            health["status"] = "unhealthy"
+            health["status"] = HealthStatus.UNHEALTHY
 
         return health
 

claude_mpm/services/unified/deployment_strategies/utils.py

@@ -23,7 +23,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-from claude_mpm.core.enums import OperationResult
+from claude_mpm.core.enums import HealthStatus, OperationResult
 from claude_mpm.core.logging_utils import get_logger
 
 logger = get_logger(__name__)
@@ -293,14 +293,14 @@ def verify_deployment_health(
 
         # Determine overall status
         if all(health["checks"].values()):
-            health["status"] = "healthy"
+            health["status"] = HealthStatus.HEALTHY
         elif any(health["checks"].values()):
-            health["status"] = "degraded"
+            health["status"] = HealthStatus.DEGRADED
         else:
-            health["status"] = "unhealthy"
+            health["status"] = HealthStatus.UNHEALTHY
 
     except Exception as e:
-        health["status"] = "error"
+        health["status"] = HealthStatus.UNKNOWN
         health["errors"].append(str(e))
 
     return health

claude_mpm/services/unified/deployment_strategies/vercel.py

@@ -13,7 +13,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from claude_mpm.core.enums import OperationResult
+from claude_mpm.core.enums import HealthStatus, OperationResult
 from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.services.unified.strategies import StrategyMetadata, StrategyPriority
 
@@ -314,7 +314,7 @@ class VercelDeploymentStrategy(DeploymentStrategy):
         }
 
         if not deployment_url:
-            health["status"] = "unhealthy"
+            health["status"] = HealthStatus.UNHEALTHY
             health["error"] = "No deployment URL"
             return health
 
@@ -342,14 +342,14 @@ class VercelDeploymentStrategy(DeploymentStrategy):
 
             # Determine overall status
             if all(health["checks"].values()):
-                health["status"] = "healthy"
+                health["status"] = HealthStatus.HEALTHY
             elif any(health["checks"].values()):
-                health["status"] = "degraded"
+                health["status"] = HealthStatus.DEGRADED
             else:
-                health["status"] = "unhealthy"
+                health["status"] = HealthStatus.UNHEALTHY
 
         except Exception as e:
-            health["status"] = "unhealthy"
+            health["status"] = HealthStatus.UNHEALTHY
             health["error"] = str(e)
 
         return health

claude_mpm/services/unified/unified_analyzer.py

@@ -25,7 +25,7 @@ Features:
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
-from claude_mpm.core.enums import ServiceState, ValidationSeverity
+from claude_mpm.core.enums import OperationResult, ServiceState, ValidationSeverity
 from claude_mpm.core.logging_utils import get_logger
 
 from .interfaces import (
@@ -344,8 +344,8 @@ class UnifiedAnalyzer(IAnalyzerService, IUnifiedService):
 
             if not result1.success or not result2.success:
                 return {
-                    "success": False,
-                    "error": "Failed to analyze one or both targets",
+                    OperationResult.SUCCESS.value: False,
+                    OperationResult.ERROR.value: "Failed to analyze one or both targets",
                 }
 
             # Compare metrics
@@ -355,7 +355,7 @@ class UnifiedAnalyzer(IAnalyzerService, IUnifiedService):
             finding_diff = self._compare_findings(result1.findings, result2.findings)
 
             return {
-                "success": True,
+                OperationResult.SUCCESS.value: True,
                 "target1": str(target1),
                 "target2": str(target2),
                 "metric_differences": metric_diff,
@@ -379,7 +379,10 @@ class UnifiedAnalyzer(IAnalyzerService, IUnifiedService):
 
         except Exception as e:
             self._logger.error(f"Comparison error: {e!s}")
-            return {"success": False, "error": str(e)}
+            return {
+                OperationResult.SUCCESS.value: False,
+                OperationResult.ERROR.value: str(e),
+            }
 
     def get_recommendations(
         self, analysis_result: AnalysisResult

claude_mpm/services/unified/unified_deployment.py

@@ -305,7 +305,7 @@ class UnifiedDeploymentService(IDeploymentService, IUnifiedService):
             }
 
             # Update metrics
-            if result.get("success", False):
+            if result.get(OperationResult.SUCCESS.value, False):
                 self._metrics["successful_deployments"] += 1
                 deployed_path = Path(target) / Path(source).name
 
@@ -319,7 +319,7 @@ class UnifiedDeploymentService(IDeploymentService, IUnifiedService):
             self._metrics["failed_deployments"] += 1
             return DeploymentResult(
                 success=False,
-                message=result.get("error", "Deployment failed"),
+                message=result.get(OperationResult.ERROR.value, "Deployment failed"),
                 metadata=result,
             )
 

{claude_mpm-4.14.9.dist-info → claude_mpm-4.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.14.9
+Version: 4.15.0
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team