mcp-mesh 0.5.7__py3-none-any.whl → 0.6.0__py3-none-any.whl

_mcp_mesh/pipeline/api_heartbeat/api_dependency_resolution.py

@@ -413,85 +413,22 @@ class APIDependencyResolutionStep(PipelineStep):
         """
         Determine which proxy type to use for API route handlers.
 
-        For API services, we need to check the parameter types used in FastAPI route handlers
-        that depend on this capability. This is different from MCP tools because route handlers
-        are wrapped differently.
-
-        Logic:
-        1. Check if any API route handlers use McpAgent for this capability
-        2. If yes → use FullMCPProxy
-        3. Otherwise → use MCPClientProxy (for McpMeshAgent or untyped)
+        Since McpAgent has been removed, all API route handlers now use MCPClientProxy
+        for McpMeshAgent parameters.
 
         Args:
             capability: The capability name to check
             injector: The dependency injector instance
 
         Returns:
-            "FullMCPProxy" or "MCPClientProxy"
+            "MCPClientProxy"
         """
-        try:
-            # Get functions that depend on this capability
-            if capability not in injector._dependency_mapping:
-                self.logger.debug(
-                    f"🔍 No API route handlers depend on capability '{capability}', using MCPClientProxy"
-                )
-                return "MCPClientProxy"
-
-            affected_function_ids = injector._dependency_mapping[capability]
-
-            # Scan ALL route handlers to detect ANY McpAgent usage
-            mcpagent_functions = []
-            mcpmeshagent_functions = []
-
-            for func_id in affected_function_ids:
-                if func_id in injector._function_registry:
-                    wrapper_func = injector._function_registry[func_id]
-
-                    # Get stored parameter types from wrapper (same pattern as MCP)
-                    if hasattr(wrapper_func, "_mesh_parameter_types") and hasattr(
-                        wrapper_func, "_mesh_dependencies"
-                    ):
-                        parameter_types = wrapper_func._mesh_parameter_types
-                        dependencies = wrapper_func._mesh_dependencies
-                        mesh_positions = wrapper_func._mesh_positions
-
-                        # Find which parameter position corresponds to this capability
-                        for dep_index, dep_name in enumerate(dependencies):
-                            if dep_name == capability and dep_index < len(
-                                mesh_positions
-                            ):
-                                param_position = mesh_positions[dep_index]
-
-                                # Check the parameter type at this position
-                                if param_position in parameter_types:
-                                    param_type = parameter_types[param_position]
-                                    if param_type == "McpAgent":
-                                        mcpagent_functions.append(func_id)
-                                    elif param_type == "McpMeshAgent":
-                                        mcpmeshagent_functions.append(func_id)
-
-            # Make deterministic decision based on complete analysis
-            if mcpagent_functions:
-                self.logger.debug(
-                    f"🔍 Found McpAgent in API route handlers {mcpagent_functions} for capability '{capability}' → using FullMCPProxy"
-                )
-                if mcpmeshagent_functions:
-                    self.logger.info(
-                        f"ℹ️ API capability '{capability}' used by both McpAgent {mcpagent_functions} and McpMeshAgent {mcpmeshagent_functions} → upgrading ALL to FullMCPProxy"
-                    )
-                return "FullMCPProxy"
-            else:
-                # Only McpMeshAgent or untyped parameters
-                self.logger.debug(
-                    f"🔍 Only McpMeshAgent/untyped API route handlers {mcpmeshagent_functions} for capability '{capability}' → using MCPClientProxy"
-                )
-                return "MCPClientProxy"
-
-        except Exception as e:
-            self.logger.warning(
-                f"⚠️ Failed to determine proxy type for API capability '{capability}': {e}"
-            )
-            return "MCPClientProxy"  # Safe default
+        # Note: This method always returns "MCPClientProxy" since McpAgent was removed.
+        # All McpMeshAgent parameters use MCPClientProxy.
+        self.logger.debug(
+            f"🔍 API route handlers for capability '{capability}' → using MCPClientProxy"
+        )
+        return "MCPClientProxy"
 
     def _create_proxy_for_api(
         self,

_mcp_mesh/pipeline/mcp_heartbeat/heartbeat_pipeline.py

@@ -15,6 +15,7 @@ from ..shared.mesh_pipeline import MeshPipeline
 from .dependency_resolution import DependencyResolutionStep
 from .fast_heartbeat_check import FastHeartbeatStep
 from .heartbeat_send import HeartbeatSendStep
+from .llm_tools_resolution import LLMToolsResolutionStep
 from .registry_connection import RegistryConnectionStep
 
 logger = logging.getLogger(__name__)
@@ -24,13 +25,14 @@ class HeartbeatPipeline(MeshPipeline):
     """
     Specialized pipeline for heartbeat operations with fast optimization.
 
-    Executes the four core heartbeat steps in sequence:
+    Executes the five core heartbeat steps in sequence:
     1. Registry connection preparation
     2. Fast heartbeat check (HEAD request)
     3. Heartbeat sending (conditional POST request)
     4. Dependency resolution (conditional)
+    5. LLM tools resolution (conditional)
 
-    Steps 3 and 4 only run if fast heartbeat indicates changes are needed.
+    Steps 3, 4, and 5 only run if fast heartbeat indicates changes are needed.
     Provides optimization for NO_CHANGES and resilience for error conditions.
     """
 
@@ -45,6 +47,7 @@ class HeartbeatPipeline(MeshPipeline):
             FastHeartbeatStep(),
             HeartbeatSendStep(required=True),
             DependencyResolutionStep(),
+            LLMToolsResolutionStep(),
         ]
 
         self.add_steps(steps)
@@ -142,7 +145,7 @@ class HeartbeatPipeline(MeshPipeline):
             ]  # RegistryConnectionStep, FastHeartbeatStep
             conditional_steps = self.steps[
                 2:
-            ]  # HeartbeatSendStep, DependencyResolutionStep
+            ]  # HeartbeatSendStep, DependencyResolutionStep, LLMToolsResolutionStep
 
             # Execute mandatory steps
             for step in mandatory_steps:

_mcp_mesh/pipeline/mcp_heartbeat/llm_tools_resolution.py

@@ -0,0 +1,222 @@
+"""
+LLM tools resolution step for MCP Mesh pipeline.
+
+Handles processing llm_tools from registry response and updating
+the LLM agent injection system.
+"""
+
+import json
+import logging
+from typing import Any
+
+from ...engine.dependency_injector import get_global_injector
+from ..shared import PipelineResult, PipelineStatus, PipelineStep
+
+logger = logging.getLogger(__name__)
+
+# Global state for LLM tools hash tracking across heartbeat cycles
+_last_llm_tools_hash = None
+
+
+class LLMToolsResolutionStep(PipelineStep):
+    """
+    Processes LLM tools from registry response.
+
+    Takes the llm_tools data from the heartbeat response and updates
+    the LLM agent injection system. This enables LLM agents to receive
+    auto-filtered, up-to-date tool lists based on their llm_filter configuration.
+
+    The registry applies filtering logic and returns matching tools with
+    full schemas that can be used by LLM agents.
+    """
+
+    def __init__(self):
+        super().__init__(
+            name="llm-tools-resolution",
+            required=False,  # Optional - only needed for LLM agents
+            description="Process LLM tools resolution from registry",
+        )
+
+    async def execute(self, context: dict[str, Any]) -> PipelineResult:
+        """Process LLM tools resolution with hash-based change detection."""
+        self.logger.debug("Processing LLM tools resolution...")
+
+        result = PipelineResult(message="LLM tools resolution processed")
+
+        try:
+            # Get heartbeat response
+            heartbeat_response = context.get("heartbeat_response")
+
+            if heartbeat_response is None:
+                result.status = PipelineStatus.SUCCESS
+                result.message = "No heartbeat response - completed successfully"
+                self.logger.debug("ℹ️ No heartbeat response to process - this is normal")
+                return result
+
+            # Use hash-based change detection and processing logic
+            await self.process_llm_tools_from_heartbeat(heartbeat_response)
+
+            # Extract LLM tools count for context
+            llm_tools = heartbeat_response.get("llm_tools", {})
+            function_count = len(llm_tools)
+            tool_count = sum(
+                len(tools) if isinstance(tools, list) else 0
+                for tools in llm_tools.values()
+            )
+
+            # Store processed LLM tools info for context
+            result.add_context("llm_function_count", function_count)
+            result.add_context("llm_tool_count", tool_count)
+            result.add_context("llm_tools", llm_tools)
+
+            result.message = "LLM tools resolution completed (efficient hash-based)"
+
+            if function_count > 0:
+                self.logger.info(
+                    f"🤖 LLM tools resolved: {function_count} functions, {tool_count} tools"
+                )
+
+            self.logger.debug(
+                "🤖 LLM tools resolution step completed using hash-based change detection"
+            )
+
+        except Exception as e:
+            result.status = PipelineStatus.FAILED
+            result.message = f"LLM tools resolution failed: {e}"
+            result.add_error(str(e))
+            self.logger.error(f"❌ LLM tools resolution failed: {e}")
+
+        return result
+
+    def _extract_llm_tools_state(
+        self, heartbeat_response: dict[str, Any]
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Extract LLM tools state structure from heartbeat response.
+
+        Preserves array structure and order from registry.
+
+        Returns:
+            {function_id: [{function_name, capability, endpoint, input_schema, ...}, ...]}
+        """
+        llm_tools = heartbeat_response.get("llm_tools", {})
+
+        if not isinstance(llm_tools, dict):
+            self.logger.warning(f"llm_tools is not a dict, type={type(llm_tools)}")
+            return {}
+
+        # Return as-is since registry already provides the correct structure
+        # Filter out non-dict or non-list values for safety
+        state = {}
+        for function_id, tools in llm_tools.items():
+            if isinstance(tools, list):
+                state[function_id] = tools
+
+        return state
+
+    def _hash_llm_tools_state(self, state: dict) -> str:
+        """Create hash of LLM tools state structure."""
+        import hashlib
+
+        # Convert to sorted JSON string for consistent hashing
+        state_json = json.dumps(state, sort_keys=True)
+
+        hash_value = hashlib.sha256(state_json.encode()).hexdigest()[:16]
+
+        return hash_value
+
+    async def process_llm_tools_from_heartbeat(
+        self, heartbeat_response: dict[str, Any]
+    ) -> None:
+        """Process heartbeat response to update LLM agent injection.
+
+        Uses hash-based comparison to efficiently detect when ANY LLM tools change
+        and then updates ALL affected LLM agents in one operation.
+
+        Resilience logic:
+        - No response (connection error, 5xx) → Skip entirely (keep existing tools)
+        - 2xx response with empty llm_tools → Clear all LLM tools
+        - 2xx response with partial llm_tools → Update to match registry exactly
+        """
+        try:
+            if not heartbeat_response:
+                # No response from registry (connection error, timeout, 5xx)
+                # → Skip entirely for resilience (keep existing LLM tools)
+                self.logger.debug(
+                    "No heartbeat response - skipping LLM tools processing for resilience"
+                )
+                return
+
+            # Extract current LLM tools state
+            current_state = self._extract_llm_tools_state(heartbeat_response)
+
+            # IMPORTANT: Empty state from successful response means "no LLM tools"
+            # This is different from "no response" which means "keep existing for resilience"
+
+            # Hash the current state (including empty state)
+            current_hash = self._hash_llm_tools_state(current_state)
+
+            # Compare with previous state (use global variable)
+            global _last_llm_tools_hash
+            if current_hash == _last_llm_tools_hash:
+                self.logger.debug(
+                    f"🔄 LLM tools state unchanged (hash: {current_hash}), skipping processing"
+                )
+                return
+
+            # State changed - determine what changed
+            function_count = len(current_state)
+            total_tools = sum(len(tools) for tools in current_state.values())
+
+            if _last_llm_tools_hash is None:
+                if function_count > 0:
+                    self.logger.info(
+                        f"🤖 Initial LLM tools state detected: {function_count} functions, {total_tools} tools"
+                    )
+                else:
+                    self.logger.info(
+                        "🤖 Initial LLM tools state detected: no LLM tools"
+                    )
+            else:
+                self.logger.info(
+                    f"🤖 LLM tools state changed (hash: {_last_llm_tools_hash} → {current_hash})"
+                )
+                if function_count > 0:
+                    self.logger.info(
+                        f"🤖 Updating LLM tools for {function_count} functions ({total_tools} total tools)"
+                    )
+                else:
+                    self.logger.info(
+                        "🤖 Registry reports no LLM tools - clearing all existing LLM tools"
+                    )
+
+            injector = get_global_injector()
+
+            # Determine if this is initial processing or an update
+            if _last_llm_tools_hash is None:
+                # Initial processing - use process_llm_tools
+                self.logger.debug(
+                    "🤖 Initial LLM tools processing - calling process_llm_tools()"
+                )
+                injector.process_llm_tools(current_state)
+            else:
+                # Update - use update_llm_tools
+                self.logger.debug("🤖 LLM tools update - calling update_llm_tools()")
+                injector.update_llm_tools(current_state)
+
+            # Store new hash for next comparison (use global variable)
+            _last_llm_tools_hash = current_hash
+
+            if function_count > 0:
+                self.logger.info(
+                    f"✅ Successfully processed LLM tools for {function_count} functions ({total_tools} tools, state hash: {current_hash})"
+                )
+            else:
+                self.logger.info(
+                    f"✅ LLM tools state synchronized (no tools, state hash: {current_hash})"
+                )
+
+        except Exception as e:
+            self.logger.error(
+                f"❌ Failed to process LLM tools from heartbeat: {e}", exc_info=True
+            )
+            # Don't raise - this should not break the heartbeat loop

_mcp_mesh/pipeline/mcp_startup/fastmcpserver_discovery.py

@@ -57,6 +57,13 @@ class FastMCPServerDiscoveryStep(PipelineStep):
             result.add_context("fastmcp_server_count", len(discovered_servers))
             result.add_context("fastmcp_total_functions", total_registered_functions)
 
+            # Store server info in DecoratorRegistry for heartbeat schema extraction (Phase 2)
+            from ...engine.decorator_registry import DecoratorRegistry
+
+            # Convert server_info list to dict for easier lookup
+            server_info_dict = {info["server_name"]: info for info in server_info}
+            DecoratorRegistry.store_fastmcp_server_info(server_info_dict)
+
             result.message = (
                 f"Discovered {len(discovered_servers)} FastMCP servers "
                 f"with {total_registered_functions} total functions"

_mcp_mesh/pipeline/mcp_startup/heartbeat_preparation.py

@@ -9,6 +9,7 @@ from ...engine.decorator_registry import DecoratorRegistry
 from ...engine.signature_analyzer import validate_mesh_dependencies
 from ...shared.config_resolver import ValidationRule, get_config_value
 from ...shared.support_types import HealthStatus, HealthStatusType
+from ...utils.fastmcp_schema_extractor import FastMCPSchemaExtractor
 from ..shared import PipelineResult, PipelineStatus, PipelineStep
 
 
@@ -39,8 +40,17 @@ class HeartbeatPreparationStep(PipelineStep):
             agent_config = DecoratorRegistry.get_resolved_agent_config()
             agent_id = agent_config["agent_id"]
 
-            # Build tools list for registration
-            tools_list = self._build_tools_list(mesh_tools)
+            # Get FastMCP server info from context (set by fastmcp-server-discovery step)
+            fastmcp_server_info = context.get("fastmcp_server_info", [])
+
+            # Convert server_info list to dict for schema extractor
+            fastmcp_servers = {}
+            for server_info in fastmcp_server_info:
+                server_name = server_info.get("server_name", "unknown")
+                fastmcp_servers[server_name] = server_info
+
+            # Build tools list for registration (with FastMCP schemas)
+            tools_list = self._build_tools_list(mesh_tools, fastmcp_servers)
 
             # Build agent registration payload
             registration_data = self._build_registration_payload(
@@ -71,8 +81,10 @@ class HeartbeatPreparationStep(PipelineStep):
 
         return result
 
-    def _build_tools_list(self, mesh_tools: dict[str, Any]) -> list[dict[str, Any]]:
-        """Build tools list from mesh_tools, validating function signatures."""
+    def _build_tools_list(
+        self, mesh_tools: dict[str, Any], fastmcp_servers: dict[str, Any] = None
+    ) -> list[dict[str, Any]]:
+        """Build tools list from mesh_tools, validating function signatures and extracting schemas."""
         tools_list = []
         skipped_tools = []
 
@@ -93,6 +105,53 @@ class HeartbeatPreparationStep(PipelineStep):
                     skipped_tools.append(func_name)
                     continue
 
+            # Extract inputSchema from FastMCP tool (if available)
+            # First try matching with FastMCP servers, then fallback to direct attribute
+            input_schema = FastMCPSchemaExtractor.extract_from_fastmcp_servers(
+                current_function, fastmcp_servers
+            )
+            if input_schema is None:
+                input_schema = FastMCPSchemaExtractor.extract_input_schema(
+                    current_function
+                )
+
+            # Check if this function has @mesh.llm decorator (Phase 3)
+            llm_filter_data = None
+            llm_agents = DecoratorRegistry.get_mesh_llm_agents()
+            self.logger.info(
+                f"🤖 Checking for LLM filter: function={func_name}, total_llm_agents_registered={len(llm_agents)}"
+            )
+
+            for llm_agent_id, llm_metadata in llm_agents.items():
+                if llm_metadata.function.__name__ == func_name:
+                    # Found matching LLM agent - extract filter config
+                    raw_filter = llm_metadata.config.get("filter")
+                    filter_mode = llm_metadata.config.get("filter_mode", "all")
+
+                    # Normalize filter to array format (OpenAPI schema requirement)
+                    if raw_filter is None:
+                        normalized_filter = []
+                    elif isinstance(raw_filter, str):
+                        normalized_filter = [raw_filter]
+                    elif isinstance(raw_filter, dict):
+                        normalized_filter = [raw_filter]
+                    elif isinstance(raw_filter, list):
+                        normalized_filter = raw_filter
+                    else:
+                        self.logger.warning(
+                            f"⚠️ Invalid filter type for {func_name}: {type(raw_filter)}"
+                        )
+                        normalized_filter = []
+
+                    llm_filter_data = {
+                        "filter": normalized_filter,
+                        "filter_mode": filter_mode,
+                    }
+                    self.logger.info(
+                        f"🤖 LLM filter found for {func_name}: {len(normalized_filter)} filters, mode={filter_mode}, raw_filter={raw_filter}"
+                    )
+                    break
+
             # Build tool registration data
             tool_data = {
                 "function_name": func_name,
@@ -101,6 +160,8 @@ class HeartbeatPreparationStep(PipelineStep):
                 "version": metadata.get("version", "1.0.0"),
                 "description": metadata.get("description"),
                 "dependencies": self._process_dependencies(dependencies),
+                "input_schema": input_schema,  # Add inputSchema for LLM integration (Phase 2)
+                "llm_filter": llm_filter_data,  # Add LLM filter for LLM integration (Phase 3)
             }
 
             # Add debug pointer information only if debug flag is enabled

_mcp_mesh/pipeline/mcp_startup/startup_pipeline.py

@@ -49,9 +49,9 @@ class StartupPipeline(MeshPipeline):
         steps = [
             DecoratorCollectionStep(),
             ConfigurationStep(),
-            HeartbeatPreparationStep(),  # Prepare heartbeat payload structure
+            FastMCPServerDiscoveryStep(),  # Discover user's FastMCP instances (MOVED UP for Phase 2)
+            HeartbeatPreparationStep(),  # Prepare heartbeat payload structure (can now access FastMCP schemas)
             ServerDiscoveryStep(),  # Discover existing uvicorn servers from immediate startup
-            FastMCPServerDiscoveryStep(),  # Discover user's FastMCP instances
             HeartbeatLoopStep(),  # Setup background heartbeat config (handles no registry gracefully)
             FastAPIServerSetupStep(),  # Setup FastAPI app with background heartbeat
             # Note: Registry connection is handled in heartbeat pipeline for retry behavior

_mcp_mesh/shared/registry_client_wrapper.py

@@ -7,7 +7,7 @@ that handles conversion between simple Python dicts and Pydantic models.
 
 import logging
 from datetime import UTC, datetime
-from typing import Any, Dict, Optional
+from typing import Any, Optional
 
 from _mcp_mesh.generated.mcp_mesh_registry_client.api.agents_api import AgentsApi
 from _mcp_mesh.generated.mcp_mesh_registry_client.api_client import ApiClient
@@ -72,7 +72,7 @@ class RegistryClientWrapper:
                 )
 
             registration_json = json.dumps(registration_dict, indent=2, default=str)
-            self.logger.debug(
+            self.logger.info(
                 f"🔍 Full heartbeat registration payload:\n{registration_json}"
             )
 
@@ -80,7 +80,9 @@ class RegistryClientWrapper:
             response = self.agents_api.send_heartbeat(agent_registration)
 
             # Convert response to dict
-            return self._response_to_dict(response)
+            response_dict = self._response_to_dict(response)
+
+            return response_dict
 
         except Exception as e:
             self.logger.error(
@@ -332,6 +334,7 @@ class RegistryClientWrapper:
 
         # Import here to avoid circular imports
         from _mcp_mesh.engine.decorator_registry import DecoratorRegistry
+        from _mcp_mesh.utils.fastmcp_schema_extractor import FastMCPSchemaExtractor
 
         # Get current tools from registry
         mesh_tools = DecoratorRegistry.get_mesh_tools()
@@ -374,7 +377,58 @@ class RegistryClientWrapper:
                 k: v for k, v in metadata.items() if k not in standard_fields
             }
 
-            # Create tool registration with kwargs support
+            # Extract inputSchema from FastMCP tool (Phase 2: Schema Collection)
+            # First try to get FastMCP server info from DecoratorRegistry
+            fastmcp_servers = DecoratorRegistry.get_fastmcp_server_info()
+            input_schema = None
+
+            if fastmcp_servers:
+                # Try comprehensive extraction using server context
+                input_schema = FastMCPSchemaExtractor.extract_from_fastmcp_servers(
+                    decorated_func.function, fastmcp_servers
+                )
+
+            # Fallback to direct attribute check if server lookup didn't work
+            if input_schema is None:
+                input_schema = FastMCPSchemaExtractor.extract_input_schema(
+                    decorated_func.function
+                )
+
+            # Extract llm_filter from @mesh.llm decorator (Phase 3: LLM Integration)
+            llm_agents = DecoratorRegistry.get_mesh_llm_agents()
+            llm_filter_data = None
+
+            for llm_agent_id, llm_metadata in llm_agents.items():
+                # Match by function name (decorated_func.function is the wrapper, need to check original)
+                if llm_metadata.function.__name__ == func_name:
+                    # Found matching LLM agent - extract filter config
+                    raw_filter = llm_metadata.config.get("filter")
+                    filter_mode = llm_metadata.config.get("filter_mode", "all")
+
+                    # Normalize filter to array format
+                    if raw_filter is None:
+                        normalized_filter = []
+                    elif isinstance(raw_filter, list):
+                        normalized_filter = raw_filter
+                    elif isinstance(raw_filter, dict):
+                        # Single dict filter like {'capability': 'date_service'}
+                        normalized_filter = [raw_filter]
+                    elif isinstance(raw_filter, str):
+                        normalized_filter = [raw_filter] if raw_filter else []
+                    else:
+                        normalized_filter = []
+
+                    llm_filter_data = {
+                        "filter": normalized_filter,
+                        "filter_mode": filter_mode,
+                    }
+
+                    self.logger.debug(
+                        f"🤖 Extracted llm_filter for {func_name}: {len(normalized_filter)} filters, mode={filter_mode}"
+                    )
+                    break
+
+            # Create tool registration with llm_filter as separate top-level field (not in kwargs)
             tool_reg = MeshToolRegistration(
                 function_name=func_name,
                 capability=metadata.get("capability"),
@@ -382,6 +436,8 @@ class RegistryClientWrapper:
                 version=metadata.get("version", "1.0.0"),
                 dependencies=dep_registrations,
                 description=metadata.get("description"),
+                llm_filter=llm_filter_data,  # Pass llm_filter as top-level parameter
+                input_schema=input_schema,  # Pass inputSchema as top-level parameter (not in kwargs)
                 kwargs=kwargs_data if kwargs_data else None,
             )
             tools.append(tool_reg)