mcp-mesh 0.8.0b9__py3-none-any.whl → 0.8.1__py3-none-any.whl

_mcp_mesh/__init__.py

@@ -31,7 +31,7 @@ from .engine.decorator_registry import (
     get_decorator_stats,
 )
 
-__version__ = "0.8.0b9"
+__version__ = "0.8.1"
 
 # Store reference to runtime processor if initialized
 _runtime_processor = None

_mcp_mesh/engine/dependency_injector.py

@@ -348,6 +348,15 @@ class DependencyInjector:
         logger.debug(f"🤖 Creating LLM injection wrapper for {function_id}")
         return self._llm_injector.create_injection_wrapper(func, function_id)
 
+    def initialize_direct_llm_agents(self) -> None:
+        """
+        Initialize LLM agents that use direct LiteLLM (no mesh delegation).
+
+        This should be called during agent startup to initialize agents that
+        don't need to wait for registry response.
+        """
+        self._llm_injector.initialize_direct_llm_agents()
+
     def create_injection_wrapper(
         self, func: Callable, dependencies: list[str]
     ) -> Callable:

_mcp_mesh/engine/mesh_llm_agent.py

@@ -14,8 +14,12 @@ from typing import Any, Dict, List, Literal, Optional, Union
 from pydantic import BaseModel
 
 from .llm_config import LLMConfig
-from .llm_errors import (LLMAPIError, MaxIterationsError, ResponseParseError,
-                         ToolExecutionError)
+from .llm_errors import (
+    LLMAPIError,
+    MaxIterationsError,
+    ResponseParseError,
+    ToolExecutionError,
+)
 from .provider_handlers import ProviderHandlerRegistry
 from .response_parser import ResponseParser
 from .tool_executor import ToolExecutor
@@ -23,8 +27,7 @@ from .tool_schema_builder import ToolSchemaBuilder
 
 # Import Jinja2 for template rendering
 try:
-    from jinja2 import (Environment, FileSystemLoader, Template,
-                        TemplateSyntaxError)
+    from jinja2 import Environment, FileSystemLoader, Template, TemplateSyntaxError
 except ImportError:
     Environment = None
     FileSystemLoader = None
@@ -633,12 +636,14 @@ IMPORTANT TOOL CALLING RULES:
             # Multi-turn conversation - use provided messages array
             messages = message.copy()
 
-            # Ensure system prompt is prepended if not already present
-            if not messages or messages[0].get("role") != "system":
-                messages.insert(0, {"role": "system", "content": system_content})
-            else:
-                # Replace existing system message with our constructed one
-                messages[0] = {"role": "system", "content": system_content}
+            # Only add/update system message if we have non-empty content
+            # (Claude API rejects empty system messages - though decorator provides default)
+            if system_content:
+                if not messages or messages[0].get("role") != "system":
+                    messages.insert(0, {"role": "system", "content": system_content})
+                else:
+                    # Replace existing system message with our constructed one
+                    messages[0] = {"role": "system", "content": system_content}
 
             # Log conversation history
             logger.info(
@@ -646,10 +651,17 @@ IMPORTANT TOOL CALLING RULES:
             )
         else:
             # Single-turn - build messages array from string
-            messages = [
-                {"role": "system", "content": system_content},
-                {"role": "user", "content": message},
-            ]
+            # Only include system message if non-empty (Claude API rejects empty system messages)
+            if system_content:
+                messages = [
+                    {"role": "system", "content": system_content},
+                    {"role": "user", "content": message},
+                ]
+            else:
+                # Fallback for edge case where system_content is explicitly empty
+                messages = [
+                    {"role": "user", "content": message},
+                ]
 
             logger.info(f"🚀 Starting agentic loop for message: {message[:100]}...")
 
@@ -705,6 +717,16 @@ IMPORTANT TOOL CALLING RULES:
                         if self.model:
                             model_params["model"] = self.model
 
+                        # Issue #459: Include output_schema for provider to apply vendor-specific handling
+                        # (e.g., OpenAI needs response_format, not prompt-based JSON instructions)
+                        if self.output_type is not str and hasattr(
+                            self.output_type, "model_json_schema"
+                        ):
+                            model_params["output_schema"] = (
+                                self.output_type.model_json_schema()
+                            )
+                            model_params["output_type_name"] = self.output_type.__name__
+
                         logger.debug(
                             f"📤 Delegating to mesh provider with handler-prepared params: "
                             f"keys={list(model_params.keys())}"

_mcp_mesh/engine/mesh_llm_agent_injector.py

@@ -65,6 +65,75 @@ class MeshLlmAgentInjector(BaseInjector):
         super().__init__()
         self._llm_agents: dict[str, dict[str, Any]] = {}
 
+    def initialize_direct_llm_agents(self) -> None:
+        """
+        Initialize LLM agents that use direct LiteLLM (no mesh delegation).
+
+        This handles the case where:
+        - provider is a string (e.g., "claude") - direct LiteLLM call
+        - filter is None or empty - no mesh tools needed
+
+        These agents don't need to wait for registry response since all
+        information is available at decorator time.
+        """
+        llm_agents = DecoratorRegistry.get_mesh_llm_agents()
+
+        for function_id, llm_metadata in llm_agents.items():
+            config = llm_metadata.config
+            provider = config.get("provider")
+            filter_config = config.get("filter")
+
+            # Check if this is a direct LiteLLM agent (provider is string, not dict)
+            is_direct_llm = isinstance(provider, str)
+
+            # Check if no tools needed (filter is None or empty)
+            has_no_filter = filter_config is None or (
+                isinstance(filter_config, list) and len(filter_config) == 0
+            )
+
+            if is_direct_llm and has_no_filter:
+                # Skip if already initialized
+                if function_id in self._llm_agents:
+                    continue
+
+                logger.info(
+                    f"🔧 Initializing direct LiteLLM agent for '{function_id}' "
+                    f"(provider={provider}, no filter)"
+                )
+
+                # Initialize empty tools data for direct LiteLLM
+                self._llm_agents[function_id] = {
+                    "config": config,
+                    "output_type": llm_metadata.output_type,
+                    "param_name": llm_metadata.param_name,
+                    "tools_metadata": [],  # No tools for direct LiteLLM
+                    "tools_proxies": {},  # No tool proxies needed
+                    "function": llm_metadata.function,
+                    "provider_proxy": None,  # No mesh delegation
+                }
+
+                # Get the wrapper and update it with LLM agent
+                wrapper = llm_metadata.function
+                if wrapper and hasattr(wrapper, "_mesh_update_llm_agent"):
+                    llm_agent = self._create_llm_agent(function_id)
+                    wrapper._mesh_update_llm_agent(llm_agent)
+                    logger.info(
+                        f"🔄 Updated wrapper with MeshLlmAgent for '{function_id}' (direct LiteLLM mode)"
+                    )
+
+                    # Set factory for per-call context agent creation (template support)
+                    if config.get("is_template", False):
+                        def create_context_agent(
+                            context_value: Any, _func_id: str = function_id
+                        ) -> MeshLlmAgent:
+                            """Factory to create MeshLlmAgent with context for template rendering."""
+                            return self._create_llm_agent(_func_id, context_value=context_value)
+
+                        wrapper._mesh_create_context_agent = create_context_agent
+                        logger.info(
+                            f"🎯 Set context agent factory for template-based function '{function_id}' (direct LiteLLM mode)"
+                        )
+
     def _build_function_name_to_id_mapping(self) -> dict[str, str]:
         """
         Build mapping from function_name to function_id.
@@ -176,16 +245,41 @@ class MeshLlmAgentInjector(BaseInjector):
             f"✅ Set provider proxy for '{function_id}': {provider_proxy.function_name} at {provider_proxy.endpoint} (vendor={vendor})"
         )
 
-        # Re-create and update MeshLlmAgent with new provider (only if tools are also available)
-        # Get the function wrapper from DecoratorRegistry
+        # Re-create and update MeshLlmAgent with new provider
+        # Get the function wrapper and metadata from DecoratorRegistry
         llm_agents = DecoratorRegistry.get_mesh_llm_agents()
         wrapper = None
+        llm_metadata = None
         for agent_func_id, metadata in llm_agents.items():
             if metadata.function_id == function_id:
                 wrapper = metadata.function
+                llm_metadata = metadata
                 break
 
-        # Only update wrapper if we have both tools and provider (tools_metadata indicates tools were processed)
+        # Check if tools are required (filter is specified)
+        has_filter = False
+        if llm_metadata and llm_metadata.config:
+            filter_config = llm_metadata.config.get("filter")
+            has_filter = filter_config is not None and len(filter_config) > 0
+
+        # If no filter specified, initialize empty tools data so we can create LLM agent without tools
+        # This supports simple LLM calls (text generation) that don't need tool calling
+        if not has_filter and "tools_metadata" not in self._llm_agents[function_id]:
+            self._llm_agents[function_id].update(
+                {
+                    "config": llm_metadata.config if llm_metadata else {},
+                    "output_type": llm_metadata.output_type if llm_metadata else None,
+                    "param_name": llm_metadata.param_name if llm_metadata else "llm",
+                    "tools_metadata": [],  # No tools for simple LLM calls
+                    "tools_proxies": {},  # No tool proxies needed
+                    "function": llm_metadata.function if llm_metadata else None,
+                }
+            )
+            logger.info(
+                f"✅ Initialized empty tools for '{function_id}' (no filter specified - simple LLM mode)"
+            )
+
+        # Update wrapper if we have tools data (either from filter matching or initialized empty)
         if (
             wrapper
             and hasattr(wrapper, "_mesh_update_llm_agent")
@@ -194,9 +288,26 @@ class MeshLlmAgentInjector(BaseInjector):
             llm_agent = self._create_llm_agent(function_id)
             wrapper._mesh_update_llm_agent(llm_agent)
             logger.info(
-                f"🔄 Updated wrapper with new MeshLlmAgent (with provider) for '{function_id}'"
+                f"🔄 Updated wrapper with MeshLlmAgent for '{function_id}'"
+                + (" (with tools)" if has_filter else " (simple LLM mode)")
             )
-        elif wrapper and hasattr(wrapper, "_mesh_update_llm_agent"):
+
+            # Set factory for per-call context agent creation (template support)
+            # This is critical for filter=None cases where _process_function_tools isn't called
+            config_dict = llm_metadata.config if llm_metadata else {}
+            if config_dict.get("is_template", False):
+                # Capture function_id by value using default argument to avoid closure issues
+                def create_context_agent(
+                    context_value: Any, _func_id: str = function_id
+                ) -> MeshLlmAgent:
+                    """Factory to create MeshLlmAgent with context for template rendering."""
+                    return self._create_llm_agent(_func_id, context_value=context_value)
+
+                wrapper._mesh_create_context_agent = create_context_agent
+                logger.info(
+                    f"🎯 Set context agent factory for template-based function '{function_id}' (simple LLM mode)"
+                )
+        elif wrapper and hasattr(wrapper, "_mesh_update_llm_agent") and has_filter:
             logger.debug(
                 f"⏳ Provider set for '{function_id}', waiting for tools before updating wrapper"
             )
@@ -432,36 +543,60 @@ class MeshLlmAgentInjector(BaseInjector):
         def inject_llm_agent(func: Callable, args: tuple, kwargs: dict) -> tuple:
             """Inject LLM agent into kwargs if not provided."""
             if param_name not in kwargs or kwargs.get(param_name) is None:
-                # Phase 4: Check if templates are enabled
+                # Get config from runtime data or fallback to decorator registry.
+                # Runtime data (self._llm_agents) is populated during heartbeat and has
+                # tools/provider info. Decorator registry is populated at decorator time
+                # and always has config/context_param. For self-dependency calls that
+                # happen before heartbeat, we need the decorator registry fallback.
+                agent_data = None
+                config_dict = None
+
+                # Try runtime data first (has tools, provider from heartbeat)
                 if function_id in self._llm_agents:
                     agent_data = self._llm_agents[function_id]
-                    config_dict = agent_data["config"]
-                    is_template = config_dict.get("is_template", False)
-
-                    if is_template:
-                        # Templates enabled - create per-call agent with context
-                        # Import signature analyzer for context detection
-                        from .signature_analyzer import get_context_parameter_name
-
-                        # Detect context parameter
-                        context_param_name = config_dict.get("context_param")
-                        context_info = get_context_parameter_name(
-                            func, explicit_name=context_param_name
+                    config_dict = agent_data.get("config")
+
+                # Fallback to decorator registry (always available, has context_param)
+                # This is critical for self-dependency calls that happen before heartbeat
+                if config_dict is None:
+                    llm_agents_registry = DecoratorRegistry.get_mesh_llm_agents()
+                    if function_id in llm_agents_registry:
+                        llm_metadata = llm_agents_registry[function_id]
+                        config_dict = llm_metadata.config
+                        logger.debug(
+                            f"🔄 Using DecoratorRegistry fallback for '{function_id}' config (self-dependency before heartbeat)"
                         )
 
-                        # Extract context value from call
-                        context_value = None
-                        if context_info is not None:
-                            ctx_name, ctx_index = context_info
+                # Check if templates are enabled
+                is_template = config_dict.get("is_template", False) if config_dict else False
+
+                if is_template and config_dict:
+                    # Templates enabled - create per-call agent with context
+                    # Import signature analyzer for context detection
+                    from .signature_analyzer import get_context_parameter_name
 
-                            # Try kwargs first
-                            if ctx_name in kwargs:
-                                context_value = kwargs[ctx_name]
-                            # Then try positional args
-                            elif ctx_index < len(args):
-                                context_value = args[ctx_index]
+                    # Detect context parameter
+                    context_param_name = config_dict.get("context_param")
+                    context_info = get_context_parameter_name(
+                        func, explicit_name=context_param_name
+                    )
 
-                        # Create agent with context for this call
+                    # Extract context value from call
+                    context_value = None
+                    if context_info is not None:
+                        ctx_name, ctx_index = context_info
+
+                        # Try kwargs first
+                        if ctx_name in kwargs:
+                            context_value = kwargs[ctx_name]
+                        # Then try positional args
+                        elif ctx_index < len(args):
+                            context_value = args[ctx_index]
+
+                    # Create agent with context for this call
+                    # Note: _create_llm_agent requires function_id in self._llm_agents
+                    # If not available yet, use cached agent with context_value set directly
+                    if function_id in self._llm_agents:
                         current_agent = self._create_llm_agent(
                             function_id, context_value=context_value
                         )
@@ -469,22 +604,41 @@ class MeshLlmAgentInjector(BaseInjector):
                             f"🤖 Created MeshLlmAgent with context for {func.__name__}.{param_name}"
                         )
                     else:
-                        # No template - use cached agent (existing behavior)
+                        # Runtime data not yet available - use cached agent but log warning
+                        # The cached agent may have been created without context
                         current_agent = wrapper._mesh_llm_agent
                         if current_agent is not None:
-                            logger.debug(
-                                f"🤖 Injected MeshLlmAgent into {func.__name__}.{param_name}"
-                            )
+                            # Update context on the cached agent if possible
+                            if hasattr(current_agent, "_context_value"):
+                                current_agent._context_value = context_value
+                                logger.debug(
+                                    f"🤖 Updated context on cached MeshLlmAgent for {func.__name__}.{param_name}"
+                                )
+                            else:
+                                logger.debug(
+                                    f"🤖 Injected cached MeshLlmAgent into {func.__name__}.{param_name} (context may not be applied)"
+                                )
                         else:
                             logger.warning(
                                 f"⚠️ MeshLlmAgent for {func.__name__}.{param_name} is None (tools not yet received from registry)"
                             )
+                elif config_dict:
+                    # No template - use cached agent (existing behavior)
+                    current_agent = wrapper._mesh_llm_agent
+                    if current_agent is not None:
+                        logger.debug(
+                            f"🤖 Injected MeshLlmAgent into {func.__name__}.{param_name}"
+                        )
+                    else:
+                        logger.warning(
+                            f"⚠️ MeshLlmAgent for {func.__name__}.{param_name} is None (tools not yet received from registry)"
+                        )
                 else:
-                    # No agent data - use cached (backward compatibility)
+                    # No config found anywhere - use cached (backward compatibility)
                     current_agent = wrapper._mesh_llm_agent
                     if current_agent is None:
                         logger.warning(
-                            f"⚠️ MeshLlmAgent for {func.__name__}.{param_name} is None (tools not yet received from registry)"
+                            f"⚠️ MeshLlmAgent for {func.__name__}.{param_name} is None (no config found)"
                         )
 
                 kwargs[param_name] = current_agent

_mcp_mesh/pipeline/api_heartbeat/rust_api_heartbeat.py

@@ -104,9 +104,10 @@ def _build_api_agent_spec(context: dict[str, Any], service_id: str = None) -> An
         # Build dependency specs
         deps = []
         for dep_cap in dependencies:
+            # Tags must be serialized to JSON string (Rust core expects string, not list)
             dep_spec = core.DependencySpec(
                 capability=dep_cap,
-                tags=[],
+                tags=json.dumps([]),
                 version=None,
             )
             deps.append(dep_spec)
@@ -136,6 +137,7 @@ def _build_api_agent_spec(context: dict[str, Any], service_id: str = None) -> An
         http_port=http_port,
         http_host=http_host,
         namespace=namespace,
+        agent_type="api",  # API services only consume capabilities, not provide them
         tools=tools if tools else None,
         llm_agents=None,  # API services don't have LLM agents
         heartbeat_interval=heartbeat_interval,
@@ -272,6 +274,8 @@ async def _handle_api_dependency_change(
                 )
                 if not current_service_id:
                     # Use config resolver for consistent env var handling
+                    from ...shared.config_resolver import get_config_value
+
                     current_service_id = get_config_value("MCP_MESH_AGENT_ID")
 
                 is_self_dependency = (

_mcp_mesh/pipeline/mcp_heartbeat/rust_heartbeat.py

@@ -117,9 +117,12 @@ def _build_agent_spec(context: dict[str, Any]) -> Any:
         # Build dependency specs
         deps = []
         for dep_info in tool_metadata.get("dependencies", []):
+            # Serialize tags to JSON to support nested arrays for OR alternatives
+            # e.g., ["addition", ["python", "typescript"]] -> addition AND (python OR typescript)
+            tags_json = json.dumps(dep_info.get("tags", []))
             dep_spec = core.DependencySpec(
                 capability=dep_info.get("capability", ""),
-                tags=dep_info.get("tags", []),
+                tags=tags_json,
                 version=dep_info.get("version"),
             )
             deps.append(dep_spec)
@@ -269,6 +272,14 @@ async def _handle_mesh_event(event: Any, context: dict[str, Any]) -> None:
     if event_type == "agent_registered":
         logger.info(f"Agent registered with ID: {event.agent_id}")
 
+        # Initialize direct LiteLLM agents that don't need mesh delegation
+        # These agents have provider="string" and filter=None, so all info is
+        # available at decorator time - no need to wait for registry response
+        from ...engine.dependency_injector import get_global_injector
+
+        injector = get_global_injector()
+        injector.initialize_direct_llm_agents()
+
     elif event_type == "registration_failed":
         logger.error(f"Agent registration failed: {event.error}")
 

{mcp_mesh-0.8.0b9.dist-info → mcp_mesh-0.8.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-mesh
-Version: 0.8.0b9
+Version: 0.8.1
 Summary: Kubernetes-native platform for distributed MCP applications
 Project-URL: Homepage, https://github.com/dhyansraj/mcp-mesh
 Project-URL: Documentation, https://github.com/dhyansraj/mcp-mesh/tree/main/docs
@@ -18,6 +18,8 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
@@ -30,7 +32,7 @@ Requires-Dist: fastmcp<3.0.0,>=2.8.0
 Requires-Dist: httpx<1.0.0,>=0.25.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: litellm>=1.30.0
-Requires-Dist: mcp-mesh-core>=0.8.0b9
+Requires-Dist: mcp-mesh-core>=0.8.1
 Requires-Dist: mcp<2.0.0,>=1.9.0
 Requires-Dist: prometheus-client<1.0.0,>=0.19.0
 Requires-Dist: pydantic<3.0.0,>=2.4.0

{mcp_mesh-0.8.0b9.dist-info → mcp_mesh-0.8.1.dist-info}/RECORD

@@ -1,16 +1,16 @@
-_mcp_mesh/__init__.py,sha256=Pi7UIWRma8F9zTC-gcmeT5ApFCxpepQYRYMvWRVfDtE,2721
+_mcp_mesh/__init__.py,sha256=lXD1eCAZirQON6iPLZyBM5AagyH7bXFrcvB9EUDQv4w,2719
 _mcp_mesh/reload.py,sha256=5Yll9n0bqxM7pmTjfAaKWg-WT_Vi0YTh0_UNWbCNCIQ,6217
 _mcp_mesh/reload_runner.py,sha256=SgQKzzO2yHfSUBq8s3SpAnovWA0rveimVNaxeLCEo_0,1310
 _mcp_mesh/engine/__init__.py,sha256=U_6Kw3vA_3RiNK0Oln5c5C7WvA9lSONV22wWzfxYHNw,2975
 _mcp_mesh/engine/async_mcp_client.py,sha256=Sz-rXTkb1Mng_f0SpLqLuOdPJ8vZjv3DFy0i8yYOqYk,8792
 _mcp_mesh/engine/base_injector.py,sha256=qzRLZqFP2VvEFagVovkpdldvDmm3VwPHm6tHwV58a2k,5648
 _mcp_mesh/engine/decorator_registry.py,sha256=cch2QdQ6bKjHKEGi1XWp1YcLLO3uI2YlxwWBO7Np65E,28229
-_mcp_mesh/engine/dependency_injector.py,sha256=kjRUA4Lyj9zfYJ67NuFjx9YSdZEc3QtxTTpy3ww8YTg,31584
+_mcp_mesh/engine/dependency_injector.py,sha256=p_W7pJNnGNGvixiv14CsjRV5If7Ll1VdV9BEU9cde1g,31923
 _mcp_mesh/engine/http_wrapper.py,sha256=Simd6IEsLO2FXQOuf1WEx57SBN6DSr5RzphXnk0asHM,24152
 _mcp_mesh/engine/llm_config.py,sha256=95bOsGWro5E1JGq7oZtEYhVdrzcIJqjht_r5vEdJVz4,2049
 _mcp_mesh/engine/llm_errors.py,sha256=h7BiI14u-jL8vtvBfFbFDDrN7gIw8PQjXIl5AP1SBuA,3276
-_mcp_mesh/engine/mesh_llm_agent.py,sha256=sVh7lPnvixDVJ-p1ONzbeakiEzhsl0HmdmrLPZA2FzQ,34237
-_mcp_mesh/engine/mesh_llm_agent_injector.py,sha256=CHfyXWBjRPdsWtV5LTr1TsVPqKu6H0I0xZ2e62MB1p4,28820
+_mcp_mesh/engine/mesh_llm_agent.py,sha256=am4TG2Dd0KkgtZe0EJsVkkRi9srfbANEpO0cPS8m4w4,35320
+_mcp_mesh/engine/mesh_llm_agent_injector.py,sha256=nukBt-xE6XoWVwUY9OFjFFhoBDSmh6OVn6wKeAkgaEA,37031
 _mcp_mesh/engine/response_parser.py,sha256=g3VNoFJotaLrOAS0pL_OTCrv9t9XQe9Iiz1plsm28bQ,10280
 _mcp_mesh/engine/self_dependency_proxy.py,sha256=OkKt0-B_ADnJlWtHiHItoZCBZ7Su0iz2unEPFfXvrs4,3302
 _mcp_mesh/engine/session_aware_client.py,sha256=QejKag5zYNos5BVffQvNXFMECHFMLNOv78By4e_JzQE,10589
@@ -29,7 +29,7 @@ _mcp_mesh/engine/provider_handlers/provider_handler_registry.py,sha256=klBZW8iX6
 _mcp_mesh/pipeline/__init__.py,sha256=MgPwpwbiD62ND4HXKKNGcnreDk-TvPmQOs5WmjtHQ3M,1263
 _mcp_mesh/pipeline/api_heartbeat/__init__.py,sha256=qGjEgxbGJFSl9Qm3bwu3X5yizAMbN4WpFtIUekDSFuU,690
 _mcp_mesh/pipeline/api_heartbeat/api_lifespan_integration.py,sha256=h0mTmLyPlGDqomSHpbW7S-AZNz1Tyvg1kpy9aeWkQsU,3879
-_mcp_mesh/pipeline/api_heartbeat/rust_api_heartbeat.py,sha256=vrld873jS2zCfJCndldx2XLDjxp_bRY7qq9CNBqZ8wI,15579
+_mcp_mesh/pipeline/api_heartbeat/rust_api_heartbeat.py,sha256=7Dv3lGTn2n2WrDpXoWqxUlqi6NwjPRH17-GVbsUckgE,15843
 _mcp_mesh/pipeline/api_startup/__init__.py,sha256=eivolkSKot2bJTWP2BV8-RKRT1Zm7SGQYuEUiTxusOQ,577
 _mcp_mesh/pipeline/api_startup/api_pipeline.py,sha256=I9-Q0o2py5oAHZO2DJOeTD1uZo1-Dpn258k5Tr0dv9o,2474
 _mcp_mesh/pipeline/api_startup/api_server_setup.py,sha256=72oCMkCzRfxYrE5sfFJbr57BYJwRSyKxBMISTOHmKyc,14919
@@ -38,7 +38,7 @@ _mcp_mesh/pipeline/api_startup/middleware_integration.py,sha256=J7Ux_nJ1VsMqVzl5
 _mcp_mesh/pipeline/api_startup/route_collection.py,sha256=WPr4hRPLIWnNIJCoRHZ141ph9tAa_-Pm_j2TiCuWS4k,2002
 _mcp_mesh/pipeline/api_startup/route_integration.py,sha256=qq1AVaWna-CWEXyehyDL3EyeYKgo5aMtei8uBNdvkZ8,12448
 _mcp_mesh/pipeline/mcp_heartbeat/__init__.py,sha256=mhDcSquoHkhRItqgbM8iFfAKC2m7qMW_0smqtUgSl-w,389
-_mcp_mesh/pipeline/mcp_heartbeat/rust_heartbeat.py,sha256=Y0VWtgmfM_PINHoA5abjUAlyXrMdTkfr4c05NMWtA9M,26392
+_mcp_mesh/pipeline/mcp_heartbeat/rust_heartbeat.py,sha256=G4BTGrEaeX3c_PHKqgV-A76dBbAnEbMeoAcHkNXIuXc,27010
 _mcp_mesh/pipeline/mcp_startup/__init__.py,sha256=qy960dnAoHLXMcL_y_rcro9Km2AoCVzC7_CxMwao564,1166
 _mcp_mesh/pipeline/mcp_startup/configuration.py,sha256=OnumIPRVBTne2OEU2VWLZovLKvWcNF9iJVQtlVwuim0,2805
 _mcp_mesh/pipeline/mcp_startup/decorator_collection.py,sha256=RHC6MHtfP9aP0hZ-IJjISZu72e0Pml3LU0qr7dc284w,2294
@@ -76,10 +76,10 @@ _mcp_mesh/tracing/trace_context_helper.py,sha256=A0UipvDExePaX-E-4SAp4M8n8uwed9P
 _mcp_mesh/tracing/utils.py,sha256=GWwfvab0tYGr9QAe_zgZjZxgDKTTs0p5Mf8w6WJeWC0,4486
 _mcp_mesh/utils/fastmcp_schema_extractor.py,sha256=fttO1EABbf4GWKjE9V5DimwbhzGY9DbfGWQ2ak4SRnE,17264
 mesh/__init__.py,sha256=avMnUHkNAK7VgON2OhXkrFB290gr1HErghmTZpOXr-U,4207
-mesh/decorators.py,sha256=3h3tEhKWrlxBDYjP7vVM7iMPy7nx1oVSWVqzugC6WPM,67580
-mesh/helpers.py,sha256=1Y7V6aQvpV8BKfEeeKfjwPJ5g9FjMCzSNifs3se1jkA,12935
+mesh/decorators.py,sha256=Xru9NoOolmdm-awGuuQkUgBb-s5bq9UF4p5QdVidAvI,71374
+mesh/helpers.py,sha256=UrYclIZzpOgoMQO-qWjeSshCdHCLokpByzuIUt5L7KM,15551
 mesh/types.py,sha256=vr0CKyPbP6lHgxj9kh_GMSLo3xkJ66PFPV_opfRb1H4,17772
-mcp_mesh-0.8.0b9.dist-info/METADATA,sha256=-M8ClhDxH5Y4v4lCg882IS6ebAzgNXTvG-nQrGG_Mzw,5040
-mcp_mesh-0.8.0b9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mcp_mesh-0.8.0b9.dist-info/licenses/LICENSE,sha256=_EBQHRQThv9FPOLc5eFOUdeeRO0mYwChC7cx60dM1tM,1078
-mcp_mesh-0.8.0b9.dist-info/RECORD,,
+mcp_mesh-0.8.1.dist-info/METADATA,sha256=xcCC3wocWG7g8uNDNDNzm2_NIrqIA_jmXBtbv4xQmKY,5138
+mcp_mesh-0.8.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mcp_mesh-0.8.1.dist-info/licenses/LICENSE,sha256=_EBQHRQThv9FPOLc5eFOUdeeRO0mYwChC7cx60dM1tM,1078
+mcp_mesh-0.8.1.dist-info/RECORD,,

mesh/decorators.py

@@ -26,6 +26,25 @@ _runtime_processor: Any | None = None
 _SHARED_AGENT_ID: str | None = None
 
 
+def _find_available_port() -> int:
+    """
+    Find an available port by binding to port 0 and getting the OS-assigned port.
+
+    This is used when http_port=0 is specified to auto-assign a port.
+    Works reliably on all platforms (macOS, Linux, Windows) without external tools.
+
+    Returns:
+        int: An available port number
+    """
+    import socket
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        s.listen(1)
+        port = s.getsockname()[1]
+    return port
+
+
 def _start_uvicorn_immediately(http_host: str, http_port: int):
     """
     Start basic uvicorn server immediately to prevent Python interpreter shutdown.
@@ -76,8 +95,75 @@ def _start_uvicorn_immediately(http_host: str, http_port: int):
             app = FastAPI(title="MCP Mesh Agent (Starting)")
             logger.debug("📦 IMMEDIATE UVICORN: Created minimal FastAPI app")
 
-        # Add trace context middleware for distributed tracing BEFORE app starts
-        # This must be done before uvicorn.run() since middleware can't be added after start
+        # Add middleware to strip trace arguments from tool calls BEFORE app starts
+        # This must be done unconditionally because meshctl --trace sends trace args
+        # regardless of agent's tracing configuration
+        try:
+            import json as json_module
+
+            class TraceArgumentStripperMiddleware:
+                """Pure ASGI middleware to strip trace arguments from tool calls.
+
+                This middleware ALWAYS runs to strip _trace_id and _parent_span from
+                MCP tool arguments, preventing Pydantic validation errors when
+                meshctl --trace is used with agents that don't have tracing enabled.
+                """
+
+                def __init__(self, app):
+                    self.app = app
+
+                async def __call__(self, scope, receive, send):
+                    if scope["type"] != "http":
+                        await self.app(scope, receive, send)
+                        return
+
+                    async def receive_with_trace_stripping():
+                        message = await receive()
+                        if message["type"] == "http.request":
+                            body = message.get("body", b"")
+                            if body:
+                                try:
+                                    payload = json_module.loads(body.decode("utf-8"))
+                                    if payload.get("method") == "tools/call":
+                                        arguments = payload.get("params", {}).get(
+                                            "arguments", {}
+                                        )
+                                        # Strip trace context fields from arguments
+                                        if (
+                                            "_trace_id" in arguments
+                                            or "_parent_span" in arguments
+                                        ):
+                                            arguments.pop("_trace_id", None)
+                                            arguments.pop("_parent_span", None)
+                                            modified_body = json_module.dumps(
+                                                payload
+                                            ).encode("utf-8")
+                                            logger.debug(
+                                                "[TRACE] Stripped trace fields from arguments"
+                                            )
+                                            return {
+                                                **message,
+                                                "body": modified_body,
+                                            }
+                                except Exception as e:
+                                    logger.debug(
+                                        f"[TRACE] Failed to process body for stripping: {e}"
+                                    )
+                        return message
+
+                    await self.app(scope, receive_with_trace_stripping, send)
+
+            app.add_middleware(TraceArgumentStripperMiddleware)
+            logger.debug(
+                "📦 IMMEDIATE UVICORN: Added trace argument stripper middleware"
+            )
+        except Exception as e:
+            logger.warning(
+                f"⚠️ IMMEDIATE UVICORN: Failed to add trace argument stripper middleware: {e}"
+            )
+
+        # Add trace context middleware for distributed tracing (optional)
+        # This handles trace propagation and header injection when tracing is enabled
         try:
             import os
 
@@ -152,11 +238,11 @@ def _start_uvicorn_immediately(http_host: str, http_port: int):
                         except Exception as e:
                             logger.warning(f"Failed to set trace context: {e}")
 
-                        # Create body-modifying receive wrapper to strip trace fields from arguments
-                        # This handles the case where trace context is passed in JSON-RPC arguments
+                        # Create receive wrapper to extract trace context from arguments
+                        # Note: Argument stripping is handled by TraceArgumentStripperMiddleware
                         import json as json_module
 
-                        async def receive_with_trace_stripping():
+                        async def receive_with_trace_extraction():
                             message = await receive()
                             if message["type"] == "http.request":
                                 body = message.get("body", b"")
@@ -207,29 +293,14 @@ def _start_uvicorn_immediately(http_host: str, http_port: int):
                                                         parent_span = (
                                                             current_trace.parent_span
                                                         )
+                                                    logger.debug(
+                                                        f"[TRACE] Extracted trace context from arguments: trace_id={arg_trace_id}"
+                                                    )
                                                 except Exception:
                                                     pass
-
-                                            # Strip trace context fields from arguments
-                                            if (
-                                                "_trace_id" in arguments
-                                                or "_parent_span" in arguments
-                                            ):
-                                                arguments.pop("_trace_id", None)
-                                                arguments.pop("_parent_span", None)
-                                                modified_body = json_module.dumps(
-                                                    payload
-                                                ).encode("utf-8")
-                                                logger.debug(
-                                                    "[TRACE] Stripped trace fields from arguments"
-                                                )
-                                                return {
-                                                    **message,
-                                                    "body": modified_body,
-                                                }
                                     except Exception as e:
                                         logger.debug(
-                                            f"[TRACE] Failed to process body: {e}"
+                                            f"[TRACE] Failed to process body for extraction: {e}"
                                         )
                             return message
 
@@ -249,7 +320,7 @@ def _start_uvicorn_immediately(http_host: str, http_port: int):
                             await send(message)
 
                         await self.app(
-                            scope, receive_with_trace_stripping, send_with_trace_headers
+                            scope, receive_with_trace_extraction, send_with_trace_headers
                         )
 
                 app.add_middleware(TraceContextMiddleware)
@@ -306,6 +377,13 @@ def _start_uvicorn_immediately(http_host: str, http_port: int):
         # which is handled upstream in the @mesh.agent decorator
         port = http_port
 
+        # Handle http_port=0: find an available port BEFORE starting uvicorn
+        # This is more reliable than detecting the port after uvicorn starts
+        # and works on all platforms (Linux containers don't have lsof installed)
+        if port == 0:
+            port = _find_available_port()
+            logger.info(f"🎯 IMMEDIATE UVICORN: Auto-assigned port {port} for agent")
+
         logger.debug(
             f"🚀 IMMEDIATE UVICORN: Starting uvicorn server on {http_host}:{port}"
         )
@@ -370,53 +448,8 @@ def _start_uvicorn_immediately(http_host: str, http_port: int):
         # Give server a moment to start
         time.sleep(1)
 
-        # Detect actual port if port=0 (auto-assign)
-        actual_port = port
-        if port == 0:
-            import socket
-
-            # Try to detect actual port by scanning for listening sockets
-            try:
-                import subprocess
-
-                # Use lsof to find the port bound by this process
-                result = subprocess.run(
-                    ["lsof", "-i", "-P", "-n", f"-p{os.getpid()}"],
-                    capture_output=True,
-                    text=True,
-                    timeout=5,
-                )
-                for line in result.stdout.split("\n"):
-                    if "LISTEN" in line and "python" in line.lower():
-                        # Parse port from line like "python  1234  user  5u  IPv4 ... TCP *:54321 (LISTEN)"
-                        parts = line.split()
-                        for part in parts:
-                            if ":" in part and "(LISTEN)" not in part:
-                                try:
-                                    port_str = part.split(":")[-1]
-                                    detected_port = int(port_str)
-                                    if detected_port > 0:
-                                        actual_port = detected_port
-                                        logger.info(
-                                            f"🎯 IMMEDIATE UVICORN: Detected auto-assigned port {actual_port}"
-                                        )
-                                        # Update server_info with actual port
-                                        server_info["port"] = actual_port
-                                        server_info["requested_port"] = (
-                                            0  # Remember original request
-                                        )
-                                        break
-                                except (ValueError, IndexError):
-                                    pass
-                        if actual_port > 0:
-                            break
-            except Exception as e:
-                logger.warning(
-                    f"⚠️ IMMEDIATE UVICORN: Could not detect auto-assigned port: {e}"
-                )
-
         logger.debug(
-            f"✅ IMMEDIATE UVICORN: Uvicorn server running on {http_host}:{actual_port} (daemon thread)"
+            f"✅ IMMEDIATE UVICORN: Uvicorn server running on {http_host}:{port} (daemon thread)"
         )
 
         # Set up registry context for shutdown cleanup (use defaults initially)
@@ -585,12 +618,25 @@ def tool(
                         raise ValueError("dependency capability must be a string")
 
                     # Validate optional dependency fields
+                    # Tags can be strings or arrays of strings (OR alternatives)
+                    # e.g., ["required", ["python", "typescript"]] = required AND (python OR typescript)
                     dep_tags = dep.get("tags", [])
                     if not isinstance(dep_tags, list):
                         raise ValueError("dependency tags must be a list")
                     for tag in dep_tags:
-                        if not isinstance(tag, str):
-                            raise ValueError("all dependency tags must be strings")
+                        if isinstance(tag, str):
+                            continue  # Simple tag - OK
+                        elif isinstance(tag, list):
+                            # OR alternative - validate inner tags are all strings
+                            for inner_tag in tag:
+                                if not isinstance(inner_tag, str):
+                                    raise ValueError(
+                                        "OR alternative tags must be strings"
+                                    )
+                        else:
+                            raise ValueError(
+                                "tags must be strings or arrays of strings (OR alternatives)"
+                            )
 
                     dep_version = dep.get("version")
                     if dep_version is not None and not isinstance(dep_version, str):
@@ -708,7 +754,7 @@ def agent(
     http_port: int = 0,
     enable_http: bool = True,
     namespace: str = "default",
-    health_interval: int = 5,  # Will be overridden by centralized defaults
+    heartbeat_interval: int = 5,
     health_check: Callable[[], Awaitable[Any]] | None = None,
     health_check_ttl: int = 15,
     auto_run: bool = True,  # Changed to True by default!
@@ -733,7 +779,7 @@ def agent(
             Environment variable: MCP_MESH_HTTP_ENABLED (takes precedence)
         namespace: Agent namespace (default: "default")
             Environment variable: MCP_MESH_NAMESPACE (takes precedence)
-        health_interval: Health check interval in seconds (default: 30)
+        heartbeat_interval: Heartbeat interval in seconds (default: 5)
             Environment variable: MCP_MESH_HEALTH_INTERVAL (takes precedence)
         health_check: Optional async function that returns HealthStatus
             Called before heartbeat and on /health endpoint with TTL caching
@@ -750,7 +796,7 @@ def agent(
         MCP_MESH_HTTP_PORT: Override http_port parameter (integer, 0-65535)
         MCP_MESH_HTTP_ENABLED: Override enable_http parameter (boolean: true/false)
         MCP_MESH_NAMESPACE: Override namespace parameter (string)
-        MCP_MESH_HEALTH_INTERVAL: Override health_interval parameter (integer, ≥1)
+        MCP_MESH_HEALTH_INTERVAL: Override heartbeat_interval parameter (integer, ≥1)
         MCP_MESH_AUTO_RUN: Override auto_run parameter (boolean: true/false)
         MCP_MESH_AUTO_RUN_INTERVAL: Override auto_run_interval parameter (integer, ≥1)
 
@@ -801,10 +847,10 @@ def agent(
         if not isinstance(namespace, str):
             raise ValueError("namespace must be a string")
 
-        if not isinstance(health_interval, int):
-            raise ValueError("health_interval must be an integer")
-        if health_interval < 1:
-            raise ValueError("health_interval must be at least 1 second")
+        if not isinstance(heartbeat_interval, int):
+            raise ValueError("heartbeat_interval must be an integer")
+        if heartbeat_interval < 1:
+            raise ValueError("heartbeat_interval must be at least 1 second")
 
         if not isinstance(auto_run, bool):
             raise ValueError("auto_run must be a boolean")
@@ -859,9 +905,9 @@ def agent(
         # Import centralized defaults
         from _mcp_mesh.shared.defaults import MeshDefaults
 
-        final_health_interval = get_config_value(
+        final_heartbeat_interval = get_config_value(
             "MCP_MESH_HEALTH_INTERVAL",
-            override=health_interval,
+            override=heartbeat_interval,
             default=MeshDefaults.HEALTH_INTERVAL,
             rule=ValidationRule.NONZERO_RULE,
         )
@@ -892,7 +938,7 @@ def agent(
             "http_port": final_http_port,
             "enable_http": final_enable_http,
             "namespace": final_namespace,
-            "health_interval": final_health_interval,
+            "heartbeat_interval": final_heartbeat_interval,
             "health_check": health_check,
             "health_check_ttl": health_check_ttl,
             "auto_run": final_auto_run,
@@ -1063,12 +1109,25 @@ def route(
                         raise ValueError("dependency capability must be a string")
 
                     # Validate optional dependency fields
+                    # Tags can be strings or arrays of strings (OR alternatives)
+                    # e.g., ["required", ["python", "typescript"]] = required AND (python OR typescript)
                     dep_tags = dep.get("tags", [])
                     if not isinstance(dep_tags, list):
                         raise ValueError("dependency tags must be a list")
                     for tag in dep_tags:
-                        if not isinstance(tag, str):
-                            raise ValueError("all dependency tags must be strings")
+                        if isinstance(tag, str):
+                            continue  # Simple tag - OK
+                        elif isinstance(tag, list):
+                            # OR alternative - validate inner tags are all strings
+                            for inner_tag in tag:
+                                if not isinstance(inner_tag, str):
+                                    raise ValueError(
+                                        "OR alternative tags must be strings"
+                                    )
+                        else:
+                            raise ValueError(
+                                "tags must be strings or arrays of strings (OR alternatives)"
+                            )
 
                     dep_version = dep.get("version")
                     if dep_version is not None and not isinstance(dep_version, str):
@@ -1354,6 +1413,34 @@ def llm(
                 rule=ValidationRule.STRING_RULE,
             )
 
+        # Resolve model with env var override
+        resolved_model = get_config_value(
+            "MESH_LLM_MODEL",
+            override=model,
+            default=None,
+            rule=ValidationRule.STRING_RULE,
+        )
+
+        # Warn about missing configuration parameters
+        if not system_prompt and not system_prompt_file:
+            logger.warning(
+                f"⚠️ @mesh.llm: No 'system_prompt' specified for function '{func.__name__}'. "
+                f"Using default: 'You are a helpful assistant.' "
+                f"Consider adding a custom system_prompt for better results."
+            )
+
+        if isinstance(provider, str) and provider == "claude" and not resolved_model:
+            logger.warning(
+                f"⚠️ @mesh.llm: No 'model' specified for function '{func.__name__}'. "
+                f"The LLM provider will use its default model. "
+                f"Consider specifying a model explicitly (e.g., model='anthropic/claude-sonnet-4-5')."
+            )
+
+        # Use default system prompt if not provided
+        effective_system_prompt = (
+            system_prompt if system_prompt else "You are a helpful assistant."
+        )
+
         resolved_config = {
             "filter": filter,
             "filter_mode": get_config_value(
@@ -1363,12 +1450,7 @@ def llm(
                 rule=ValidationRule.STRING_RULE,
             ),
             "provider": resolved_provider,
-            "model": get_config_value(
-                "MESH_LLM_MODEL",
-                override=model,
-                default=None,
-                rule=ValidationRule.STRING_RULE,
-            ),
+            "model": resolved_model,
             "api_key": api_key,  # Will be resolved from provider-specific env vars later
             "max_iterations": get_config_value(
                 "MESH_LLM_MAX_ITERATIONS",
@@ -1376,7 +1458,7 @@ def llm(
                 default=10,
                 rule=ValidationRule.NONZERO_RULE,
             ),
-            "system_prompt": system_prompt,
+            "system_prompt": effective_system_prompt,
             "system_prompt_file": system_prompt_file,
             # Phase 1: Template metadata
             "is_template": is_template,

mesh/helpers.py

@@ -214,6 +214,58 @@ def llm_provider(
                             f"(requested by consumer)"
                         )
 
+            # Issue #459: Handle output_schema for vendor-specific structured output
+            # Convert to response_format for vendors that support it
+            output_schema = model_params_copy.pop("output_schema", None)
+            output_type_name = model_params_copy.pop("output_type_name", None)
+
+            # Vendors that support structured output via response_format
+            supported_structured_output_vendors = (
+                "openai",
+                "azure",  # Azure OpenAI uses same format as OpenAI
+                "gemini",
+                "vertex_ai",  # Vertex AI Gemini uses same format as Gemini
+                "anthropic",
+            )
+
+            if output_schema:
+                if vendor in supported_structured_output_vendors:
+                    # Apply vendor-specific response_format for structured output
+                    from _mcp_mesh.engine.provider_handlers import make_schema_strict
+
+                    if vendor == "anthropic":
+                        # Claude: doesn't require all properties in 'required', uses strict=False
+                        schema = make_schema_strict(
+                            output_schema, add_all_required=False
+                        )
+                        strict_mode = False
+                    else:
+                        # OpenAI/Azure/Gemini/Vertex: require all properties in 'required', uses strict=True
+                        schema = make_schema_strict(
+                            output_schema, add_all_required=True
+                        )
+                        strict_mode = True
+
+                    model_params_copy["response_format"] = {
+                        "type": "json_schema",
+                        "json_schema": {
+                            "name": output_type_name or "Response",
+                            "schema": schema,
+                            "strict": strict_mode,
+                        },
+                    }
+                    logger.debug(
+                        f"🎯 Applied {vendor} response_format for structured output: "
+                        f"{output_type_name} (strict={strict_mode})"
+                    )
+                else:
+                    # Vendor doesn't support structured output - warn user
+                    logger.warning(
+                        f"⚠️ Structured output schema '{output_type_name or 'Response'}' "
+                        f"was provided but vendor '{vendor}' does not support response_format. "
+                        f"The schema will be ignored and the LLM may return unstructured output."
+                    )
+
             # Build litellm.completion arguments
             completion_args: dict[str, Any] = {
                 "model": effective_model,