claude-mpm 4.13.2__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/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,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/model/__init__.py

@@ -0,0 +1,147 @@
+"""
+Model Services Package for Claude MPM Framework
+================================================
+
+WHY: Provides hybrid local/cloud content processing with intelligent routing
+and automatic fallback. Enables privacy-preserving local model execution via
+Ollama with cloud fallback to Claude for reliability.
+
+ARCHITECTURE:
+- Interfaces: Core contracts for model providers and routing (IModelProvider, IModelRouter)
+- Base Provider: Common functionality for all providers (BaseModelProvider)
+- Providers: Ollama (local) and Claude (cloud) implementations
+- Router: Intelligent routing with fallback logic (ModelRouter)
+- Configuration: Centralized config management (model_config.py)
+
+USAGE:
+
+    Basic Usage with Auto-Routing:
+    ```python
+    from claude_mpm.services.model import ModelRouter
+    from claude_mpm.services.core.interfaces.model import ModelCapability
+
+    # Create router with default config (auto mode)
+    router = ModelRouter()
+    await router.initialize()
+
+    # Analyze content (tries Ollama first, falls back to Claude)
+    response = await router.analyze_content(
+        content="Your article text here...",
+        task=ModelCapability.SEO_ANALYSIS
+    )
+
+    if response.success:
+        print(f"Analysis by {response.provider}:")
+        print(response.result)
+    ```
+
+    Direct Provider Usage:
+    ```python
+    from claude_mpm.services.model import OllamaProvider
+
+    # Use Ollama directly
+    provider = OllamaProvider(config={
+        "host": "http://localhost:11434"
+    })
+
+    if await provider.is_available():
+        response = await provider.analyze_content(
+            content="Text to analyze",
+            task=ModelCapability.READABILITY
+        )
+    ```
+
+    Configuration-Based Setup:
+    ```python
+    from claude_mpm.config.model_config import ModelConfigManager
+    from claude_mpm.services.model import ModelRouter
+
+    # Load config from file
+    config = ModelConfigManager.load_config(".claude/configuration.yaml")
+    router_config = ModelConfigManager.get_router_config(config)
+
+    # Create router with loaded config
+    router = ModelRouter(config=router_config)
+    await router.initialize()
+    ```
+
+PROVIDER STRATEGIES:
+- AUTO: Try Ollama first, fallback to Claude (default)
+- OLLAMA: Local-only, fail if unavailable (privacy mode)
+- CLAUDE: Cloud-only, always use Claude
+- PRIVACY: Like OLLAMA with privacy-focused messages
+
+RECOMMENDED MODELS (Ollama):
+- SEO Analysis: llama3.3:70b - Comprehensive SEO insights
+- Readability: gemma2:9b - Fast, accurate readability scoring
+- Grammar: qwen3:14b - Specialized grammar checking
+- Summarization: mistral:7b - Concise, effective summaries
+- Keyword Extraction: seoassistant - SEO-specialized model
+
+CONFIGURATION:
+See claude_mpm.config.model_config for detailed configuration options.
+
+Example configuration.yaml:
+```yaml
+content_agent:
+  model_provider: auto
+
+  ollama:
+    enabled: true
+    host: http://localhost:11434
+    fallback_to_cloud: true
+    models:
+      seo_analysis: llama3.3:70b
+      readability: gemma2:9b
+
+  claude:
+    enabled: true
+    model: claude-3-5-sonnet-20241022
+```
+
+PHASE 1 STATUS (Current):
+✅ Core interfaces and contracts defined
+✅ Base provider with common functionality
+✅ Ollama provider with direct API integration
+✅ Claude provider (Phase 1: mock responses)
+✅ Router with intelligent fallback logic
+✅ Configuration management with validation
+⏳ Claude API integration (Phase 2)
+⏳ Content agent integration (Phase 2)
+"""
+
+# Re-export interfaces for convenience
+from claude_mpm.services.core.interfaces.model import (
+    IModelProvider,
+    IModelRouter,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+)
+from claude_mpm.services.model.base_provider import BaseModelProvider
+from claude_mpm.services.model.claude_provider import ClaudeProvider
+from claude_mpm.services.model.model_router import ModelRouter, RoutingStrategy
+from claude_mpm.services.model.ollama_provider import OllamaProvider
+
+__all__ = [  # noqa: RUF022 - Semantic grouping preferred over alphabetical
+    # Base classes
+    "BaseModelProvider",
+    # Providers
+    "ClaudeProvider",
+    "OllamaProvider",
+    # Router
+    "ModelRouter",
+    "RoutingStrategy",
+    # Interfaces
+    "IModelProvider",
+    "IModelRouter",
+    # Data types
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
+]
+
+# Version and metadata
+__version__ = "1.0.0"
+__phase__ = "1"
+__status__ = "Core Infrastructure Complete"