mcp-mesh 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

_mcp_mesh/pipeline/api_heartbeat/api_lifespan_integration.py

@@ -0,0 +1,147 @@
+"""
+FastAPI lifespan integration for API heartbeat pipeline.
+
+Handles the execution of API heartbeat pipeline as a background task
+during FastAPI application lifespan for @mesh.route decorator services.
+"""
+
+import asyncio
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+async def api_heartbeat_lifespan_task(heartbeat_config: dict[str, Any]) -> None:
+    """
+    API heartbeat task that runs in FastAPI lifespan using pipeline architecture.
+
+    Args:
+        heartbeat_config: Configuration containing service_id, interval, 
+                         and context for API heartbeat execution
+    """
+    service_id = heartbeat_config["service_id"]
+    interval = heartbeat_config["interval"]  # Already validated by get_config_value in setup
+    context = heartbeat_config["context"]
+    standalone_mode = heartbeat_config.get("standalone_mode", False)
+
+    # Check if running in standalone mode
+    if standalone_mode:
+        logger.info(
+            f"💓 Starting API heartbeat pipeline in standalone mode for service '{service_id}' "
+            f"(no registry communication)"
+        )
+        return  # For now, skip heartbeat in standalone mode
+
+    # Create API heartbeat orchestrator for pipeline execution
+    from .api_heartbeat_orchestrator import APIHeartbeatOrchestrator
+
+    api_heartbeat_orchestrator = APIHeartbeatOrchestrator()
+
+    logger.info(f"💓 Starting API heartbeat pipeline task for service '{service_id}'")
+
+    try:
+        while True:
+            try:
+                # Execute API heartbeat pipeline
+                success = await api_heartbeat_orchestrator.execute_api_heartbeat(
+                    service_id, context
+                )
+
+                if not success:
+                    # Log failure but continue to next cycle (pipeline handles detailed logging)
+                    logger.debug(
+                        f"💔 API heartbeat pipeline failed for service '{service_id}' - "
+                        f"continuing to next cycle"
+                    )
+
+            except Exception as e:
+                # Log pipeline execution error but continue to next cycle for resilience
+                logger.error(
+                    f"❌ API heartbeat pipeline execution error for service '{service_id}': {e}"
+                )
+                # Continue to next cycle - heartbeat should be resilient
+
+            # Wait for next heartbeat interval
+            await asyncio.sleep(interval)
+
+    except asyncio.CancelledError:
+        logger.info(f"🛑 API heartbeat pipeline task cancelled for service '{service_id}'")
+        raise
+
+
+def create_api_lifespan_handler(heartbeat_config: dict[str, Any]) -> Any:
+    """
+    Create a FastAPI lifespan context manager that runs API heartbeat pipeline.
+
+    Args:
+        heartbeat_config: Configuration for API heartbeat execution
+
+    Returns:
+        Async context manager for FastAPI lifespan
+    """
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def api_lifespan(app):
+        """FastAPI lifespan context manager with API heartbeat integration."""
+        service_id = heartbeat_config.get("service_id", "unknown")
+        logger.info(f"🚀 Starting FastAPI lifespan for service '{service_id}'")
+
+        # Start API heartbeat task
+        heartbeat_task = asyncio.create_task(
+            api_heartbeat_lifespan_task(heartbeat_config)
+        )
+
+        try:
+            # Yield control to FastAPI
+            yield
+        finally:
+            # Cleanup: cancel heartbeat task
+            logger.info(f"🛑 Shutting down FastAPI lifespan for service '{service_id}'")
+            heartbeat_task.cancel()
+            
+            try:
+                await heartbeat_task
+            except asyncio.CancelledError:
+                logger.info(f"✅ API heartbeat task cancelled for service '{service_id}'")
+
+    return api_lifespan
+
+
+def integrate_api_heartbeat_with_fastapi(
+    fastapi_app: Any, heartbeat_config: dict[str, Any]
+) -> None:
+    """
+    Integrate API heartbeat pipeline with FastAPI lifespan events.
+
+    Args:
+        fastapi_app: FastAPI application instance
+        heartbeat_config: Configuration for heartbeat execution
+    """
+    service_id = heartbeat_config.get("service_id", "unknown")
+    
+    try:
+        # Check if FastAPI app already has a lifespan handler
+        existing_lifespan = getattr(fastapi_app, "router.lifespan_context", None)
+        
+        if existing_lifespan is not None:
+            logger.warning(
+                f"⚠️ FastAPI app already has lifespan handler - "
+                f"API heartbeat integration may conflict for service '{service_id}'"
+            )
+
+        # Create and set the lifespan handler
+        api_lifespan = create_api_lifespan_handler(heartbeat_config)
+        fastapi_app.router.lifespan_context = api_lifespan
+
+        logger.info(
+            f"🔗 API heartbeat integrated with FastAPI lifespan for service '{service_id}'"
+        )
+
+    except Exception as e:
+        logger.error(
+            f"❌ Failed to integrate API heartbeat with FastAPI lifespan "
+            f"for service '{service_id}': {e}"
+        )
+        raise

_mcp_mesh/pipeline/api_heartbeat/api_registry_connection.py

@@ -0,0 +1,97 @@
+"""
+API registry connection step for API heartbeat pipeline.
+
+Prepares registry communication for FastAPI service heartbeat operations.
+Simpler than MCP registry connection since API services don't require
+complex dependency resolution.
+"""
+
+import logging
+from typing import Any
+
+from ..shared.base_step import PipelineStep
+from ..shared.pipeline_types import PipelineResult
+
+logger = logging.getLogger(__name__)
+
+
+class APIRegistryConnectionStep(PipelineStep):
+    """
+    Prepare registry connection for API service heartbeat.
+    
+    Ensures registry client is available and properly configured for
+    FastAPI service registration and health monitoring.
+    """
+
+    def __init__(self, required: bool = True):
+        super().__init__(
+            name="api-registry-connection",
+            required=required,
+        )
+
+    async def execute(self, context: dict[str, Any]) -> PipelineResult:
+        """
+        Prepare registry connection for API heartbeat operations.
+
+        Args:
+            context: Pipeline context containing agent_config and registration_data
+
+        Returns:
+            PipelineResult with registry_wrapper in context
+        """
+        self.logger.info("🔗 [DEBUG] Preparing API registry connection for heartbeat")
+
+        try:
+            # Check if registry_wrapper already exists in context
+            registry_wrapper = context.get("registry_wrapper")
+            
+            if registry_wrapper is not None:
+                self.logger.debug("✅ Registry wrapper already available in context")
+                return PipelineResult(
+                    message="Registry connection already established",
+                    context={"registry_wrapper": registry_wrapper}
+                )
+
+            # Get registry configuration from context
+            agent_config = context.get("agent_config", {})
+            registration_data = context.get("registration_data", {})
+            
+            registry_url = (
+                agent_config.get("registry_url") 
+                or registration_data.get("registry_url")
+                or "http://localhost:8000"  # Default fallback
+            )
+
+            self.logger.debug(f"🔍 Using registry URL: {registry_url}")
+
+            # Create registry client wrapper
+            from ...generated.mcp_mesh_registry_client.api_client import ApiClient
+            from ...generated.mcp_mesh_registry_client.configuration import Configuration
+            from ...shared.registry_client_wrapper import RegistryClientWrapper
+
+            config = Configuration(host=registry_url)
+            api_client = ApiClient(configuration=config)
+            registry_wrapper = RegistryClientWrapper(api_client)
+
+            self.logger.info(f"🔗 API registry connection prepared: {registry_url}")
+
+            return PipelineResult(
+                message=f"Registry connection prepared for {registry_url}",
+                context={
+                    "registry_wrapper": registry_wrapper,
+                    "registry_url": registry_url,
+                }
+            )
+
+        except Exception as e:
+            error_msg = f"Failed to prepare API registry connection: {e}"
+            self.logger.error(f"❌ {error_msg}")
+
+            from ..shared.pipeline_types import PipelineStatus
+            result = PipelineResult(
+                status=PipelineStatus.FAILED,
+                message=error_msg,
+                context=context
+            )
+            result.add_error(str(e))
+            return result

_mcp_mesh/pipeline/api_startup/__init__.py

@@ -0,0 +1,20 @@
+"""
+API Startup pipeline components for MCP Mesh.
+
+Handles @mesh.route decorator collection, FastAPI app discovery,
+and dependency injection setup during API service initialization.
+"""
+
+from .api_pipeline import APIPipeline
+from .api_server_setup import APIServerSetupStep
+from .fastapi_discovery import FastAPIAppDiscoveryStep
+from .route_collection import RouteCollectionStep
+from .route_integration import RouteIntegrationStep
+
+__all__ = [
+    "RouteCollectionStep",
+    "FastAPIAppDiscoveryStep",
+    "RouteIntegrationStep",
+    "APIServerSetupStep",
+    "APIPipeline",
+]

_mcp_mesh/pipeline/api_startup/api_pipeline.py

@@ -0,0 +1,61 @@
+"""
+API pipeline for MCP Mesh FastAPI integration.
+
+Provides structured execution of API operations with proper error handling
+and logging. Handles @mesh.route decorator collection, FastAPI app discovery,
+route integration, and service registration.
+"""
+
+import logging
+
+from ..shared.mesh_pipeline import MeshPipeline
+from .api_server_setup import APIServerSetupStep
+from .fastapi_discovery import FastAPIAppDiscoveryStep
+from .route_collection import RouteCollectionStep
+from .route_integration import RouteIntegrationStep
+
+logger = logging.getLogger(__name__)
+
+
+class APIPipeline(MeshPipeline):
+    """
+    Specialized pipeline for API operations.
+
+    Executes the core API integration steps in sequence:
+    1. Route collection (@mesh.route decorators)
+    2. FastAPI app discovery (find user's FastAPI instances)
+    3. Route integration (apply dependency injection)
+    4. API server setup (service registration metadata)
+
+    Unlike MCP agents, API services are consumers so we focus on:
+    - Dependency injection into route handlers
+    - Service registration for health monitoring
+    - NO server creation or binding (user owns FastAPI app)
+    """
+
+    def __init__(self, name: str = "api-pipeline"):
+        super().__init__(name=name)
+        self._setup_api_steps()
+
+    def _setup_api_steps(self) -> None:
+        """Setup the API pipeline steps."""
+        # Essential API integration steps
+        steps = [
+            RouteCollectionStep(),          # Collect @mesh.route decorators
+            FastAPIAppDiscoveryStep(),      # Find user's FastAPI app instances
+            RouteIntegrationStep(),         # Apply dependency injection to routes
+            APIServerSetupStep(),           # Prepare service registration metadata
+            # Note: Heartbeat integration will be added in next phase
+            # Note: User controls FastAPI server startup (uvicorn/gunicorn)
+        ]
+
+        self.add_steps(steps)
+        self.logger.debug(f"API pipeline configured with {len(steps)} steps")
+        
+        # Log the pipeline strategy
+        self.logger.info(
+            f"🌐 [DEBUG] API Pipeline initialized: dependency injection for @mesh.route decorators"
+        )
+        self.logger.debug(
+            f"📋 Pipeline steps: {[step.name for step in steps]}"
+        )

_mcp_mesh/pipeline/api_startup/api_server_setup.py

@@ -0,0 +1,292 @@
+import logging
+import uuid
+from typing import Any, Dict, Optional
+
+from ...shared.config_resolver import ValidationRule, get_config_value
+from ...shared.defaults import MeshDefaults
+from ...shared.host_resolver import HostResolver
+from ..shared import PipelineResult, PipelineStatus, PipelineStep
+
+
+class APIServerSetupStep(PipelineStep):
+    """
+    Minimal API server setup for FastAPI integration.
+    
+    This step prepares the binding configuration and service registration
+    metadata for the user's existing FastAPI application. It does NOT create
+    or modify the FastAPI app - it only prepares the configuration needed
+    to run the app with uvicorn and register it with the mesh registry.
+    
+    Our job is ONLY dependency injection - the user owns their FastAPI app.
+    """
+
+    def __init__(self):
+        super().__init__(
+            name="api-server-setup",
+            required=True,
+            description="Prepare binding config and service registration for existing FastAPI app",
+        )
+
+    async def execute(self, context: dict[str, Any]) -> PipelineResult:
+        """Setup API server configuration."""
+        self.logger.debug("Setting up API server configuration...")
+
+        result = PipelineResult(message="API server setup completed")
+
+        try:
+            # Verify we have FastAPI apps to work with
+            fastapi_apps = context.get("fastapi_apps", {})
+            integration_results = context.get("integration_results", {})
+            
+            if not fastapi_apps:
+                result.status = PipelineStatus.FAILED
+                result.message = "No FastAPI applications found"
+                result.add_error("Cannot setup API server without existing FastAPI app")
+                self.logger.error(
+                    "❌ No FastAPI applications found. API pipeline requires "
+                    "an existing FastAPI app with @mesh.route decorators."
+                )
+                return result
+
+            # For now, we only support single FastAPI app
+            # TODO: Future enhancement could support multiple apps
+            if len(fastapi_apps) > 1:
+                self.logger.warning(
+                    f"⚠️ Multiple FastAPI apps found ({len(fastapi_apps)}), "
+                    f"using the first one. Multi-app support coming in future."
+                )
+
+            # Get the primary FastAPI app
+            primary_app_id = list(fastapi_apps.keys())[0]
+            primary_app_info = fastapi_apps[primary_app_id]
+            primary_app = primary_app_info["instance"]
+            
+            self.logger.info(
+                f"🎯 Using FastAPI app: '{primary_app_info['title']}' as primary app"
+            )
+
+            # Prepare display configuration for registry (NOT binding configuration)
+            display_config = self._prepare_display_config()
+            
+            # Prepare service registration metadata
+            service_metadata = self._prepare_service_metadata(
+                primary_app_info, integration_results.get(primary_app_id, {}), display_config
+            )
+            
+            # Prepare heartbeat configuration
+            heartbeat_config = self._prepare_heartbeat_config(
+                primary_app_info, display_config, service_metadata
+            )
+            
+            # Store configuration in context
+            result.add_context("primary_fastapi_app", primary_app)
+            result.add_context("fastapi_app", primary_app)  # For heartbeat compatibility
+            result.add_context("api_display_config", display_config)
+            result.add_context("display_config", display_config)  # For heartbeat compatibility
+            result.add_context("api_service_metadata", service_metadata)
+            result.add_context("service_type", "api")  # Important for registry registration
+            result.add_context("heartbeat_config", heartbeat_config)
+            
+            # Update result message
+            integrated_routes = integration_results.get(primary_app_id, {}).get("integrated_count", 0)
+            result.message = (
+                f"API server config prepared for '{primary_app_info['title']}' "
+                f"with {integrated_routes} dependency-injected routes"
+            )
+
+            self.logger.info(
+                f"✅ API server setup: {primary_app_info['title']} ready "
+                f"(registry display: {display_config['display_host']}:{display_config['display_port']})"
+            )
+
+        except Exception as e:
+            result.status = PipelineStatus.FAILED
+            result.message = f"API server setup failed: {e}"
+            result.add_error(str(e))
+            self.logger.error(f"❌ API server setup failed: {e}")
+
+        return result
+
+    def _prepare_display_config(self) -> Dict[str, Any]:
+        """
+        Prepare display configuration for service registration.
+        
+        This is ONLY for registry display purposes since FastAPI services
+        are consumers (nobody needs to communicate TO them in mesh network).
+        Users configure their actual uvicorn host/port separately.
+        """
+        # Get external host for display (what others would see this service as)
+        external_host = HostResolver.get_external_host()
+        
+        # Get port for display - users can override via env var
+        display_port = get_config_value(
+            "MCP_MESH_HTTP_PORT", 
+            default=8080,  # FastAPI convention
+            rule=ValidationRule.PORT_RULE,
+        )
+        
+        # Also check if user provided host override
+        display_host = get_config_value(
+            "MCP_MESH_HTTP_HOST",
+            default=external_host,
+            rule=ValidationRule.STRING_RULE,
+        )
+        
+        display_config = {
+            "display_host": display_host,
+            "display_port": display_port,
+            "external_host": external_host,
+        }
+        
+        self.logger.debug(
+            f"📍 Display config: {display_host}:{display_port} "
+            f"(for registry display only - user controls actual uvicorn binding)"
+        )
+        
+        return display_config
+
+    def _prepare_service_metadata(
+        self, app_info: Dict[str, Any], integration_results: Dict[str, Any], display_config: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Prepare service registration metadata for mesh registry.
+        
+        This metadata tells the mesh registry about our API service
+        and what capabilities it provides (routes, not MCP tools).
+        """
+        # Extract route information for registry
+        route_capabilities = []
+        route_details = integration_results.get("route_details", {})
+        
+        for route_name, details in route_details.items():
+            if details.get("status") == "integrated":
+                # Create capability entry for each dependency-injected route
+                capability_info = {
+                    "name": route_name,
+                    "type": "api_route", 
+                    "dependencies": details.get("dependencies", []),
+                    "dependency_count": details.get("dependency_count", 0),
+                }
+                route_capabilities.append(capability_info)
+        
+        # Build service metadata
+        service_metadata = {
+            "service_name": app_info.get("title", "FastAPI Service"),
+            "service_version": app_info.get("version", "1.0.0"),
+            "service_type": "api",  # Distinguishes from MCP agents
+            "capabilities": route_capabilities,
+            "total_routes": len(app_info.get("routes", [])),
+            "integrated_routes": integration_results.get("integrated_count", 0),
+            "framework": "fastapi",
+            "integration_method": "mesh_route_decorators",
+            # Display info for registry (NOT actual binding)
+            "display_host": display_config["display_host"],
+            "display_port": display_config["display_port"],
+            "external_host": display_config["external_host"],
+        }
+        
+        self.logger.debug(
+            f"📋 Service metadata: {service_metadata['service_name']} "
+            f"({len(route_capabilities)} capabilities)"
+        )
+        
+        return service_metadata
+
+    def _prepare_heartbeat_config(
+        self, app_info: Dict[str, Any], display_config: Dict[str, Any], service_metadata: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Prepare heartbeat configuration for API service.
+        
+        This configuration will be used to start the heartbeat pipeline
+        for periodic service registration and health monitoring.
+        """
+        # Generate service ID using same logic as MCP agents
+        service_id = self._generate_api_service_id(app_info)
+        
+        # Get heartbeat interval using centralized defaults (consistent with MCP heartbeat)
+        from ...shared.defaults import MeshDefaults
+        
+        heartbeat_interval = get_config_value(
+            "MCP_MESH_HEALTH_INTERVAL",
+            default=MeshDefaults.HEALTH_INTERVAL,
+            rule=ValidationRule.NONZERO_RULE,
+        )
+        
+        # Check if standalone mode (no registry communication)
+        standalone_mode = get_config_value(
+            "MCP_MESH_STANDALONE",
+            default=False,
+            rule=ValidationRule.TRUTHY_RULE,
+        )
+        
+        heartbeat_config = {
+            "service_id": service_id,
+            "interval": heartbeat_interval,
+            "standalone_mode": standalone_mode,
+            "context": {
+                # Context will be populated during heartbeat execution
+                # with current pipeline context including fastapi_app, display_config, etc.
+            }
+        }
+        
+        self.logger.info(
+            f"💓 API heartbeat config created: service_id='{service_id}', "
+            f"interval={heartbeat_interval}s, standalone={standalone_mode}"
+        )
+        
+        return heartbeat_config
+
+    def _generate_api_service_id(self, app_info: Dict[str, Any]) -> str:
+        """
+        Generate API service ID using same UUID logic as MCP agents.
+        
+        Logic:
+        - If no name provided: "api-{uuid8}"
+        - If name doesn't contain "api": "{name}-api-{uuid8}"  
+        - If name contains "api": "{name}-{uuid8}"
+        
+        Args:
+            app_info: FastAPI app information containing title
+            
+        Returns:
+            Generated service ID with UUID suffix
+        """
+        # Get service name from app title or use default
+        service_name = app_info.get("title", "")
+        
+        # Clean the service name (similar to MCP agent logic)
+        if service_name:
+            # Convert to lowercase and replace spaces/special chars with hyphens
+            cleaned_name = service_name.lower().replace(" ", "-").replace("_", "-")
+            # Remove any double hyphens and strip
+            cleaned_name = "-".join(part for part in cleaned_name.split("-") if part)
+        else:
+            cleaned_name = ""
+        
+        # Apply the UUID suffix logic similar to MCP agents
+        uuid_suffix = str(uuid.uuid4())[:8]
+        
+        if not cleaned_name:
+            # No name provided: use "api-{uuid8}"
+            service_id = f"api-{uuid_suffix}"
+        elif "api" in cleaned_name.lower():
+            # Name contains "api": use "{name}-{uuid8}"
+            service_id = f"{cleaned_name}-{uuid_suffix}"
+        else:
+            # Name doesn't contain "api": use "{name}-api-{uuid8}"
+            service_id = f"{cleaned_name}-api-{uuid_suffix}"
+        
+        self.logger.debug(
+            f"Generated API service ID: '{service_id}' from app title: '{service_name}'"
+        )
+        
+        return service_id
+
+    def _is_http_enabled(self) -> bool:
+        """Check if HTTP transport is enabled."""
+        return get_config_value(
+            "MCP_MESH_HTTP_ENABLED",
+            default=True,
+            rule=ValidationRule.TRUTHY_RULE,
+        )