mcp-mesh 0.8.0b9__py3-none-any.whl → 0.9.0b1__py3-none-any.whl

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

@@ -6,7 +6,7 @@ mesh decorators to simplify common patterns like zero-code LLM providers.
 """
 
 import logging
-from typing import Any, Dict, List, Optional
+from typing import Any, Optional
 
 from _mcp_mesh.shared.logging_config import format_log_value
 
@@ -214,10 +214,55 @@ def llm_provider(
                             f"(requested by consumer)"
                         )
 
+            # Get vendor handler once - used for both structured output and system prompt formatting
+            from _mcp_mesh.engine.provider_handlers import ProviderHandlerRegistry
+
+            handler = ProviderHandlerRegistry.get_handler(vendor)
+
+            # Issue #459: Handle output_schema for vendor-specific structured output
+            # Use provider handler pattern for vendor-specific behavior
+            output_schema = model_params_copy.pop("output_schema", None)
+            output_type_name = model_params_copy.pop("output_type_name", None)
+
+            if output_schema:
+                # Include messages so handler can modify system prompt (e.g., HINT mode injection)
+                model_params_copy["messages"] = request.messages
+                handler.apply_structured_output(
+                    output_schema, output_type_name, model_params_copy
+                )
+                # Remove messages to avoid duplication in completion_args
+                model_params_copy.pop("messages", None)
+                logger.debug(
+                    f"🎯 Applied {vendor} structured output via handler: "
+                    f"{output_type_name}"
+                )
+
+            # Use vendor handler to format system prompt when tools are present
+            messages = request.messages
+            if request.tools:
+
+                # Find and format system message
+                formatted_messages = []
+                for msg in messages:
+                    if msg.get("role") == "system":
+                        # Format system prompt with vendor-specific instructions
+                        base_prompt = msg.get("content", "")
+                        formatted_content = handler.format_system_prompt(
+                            base_prompt=base_prompt,
+                            tool_schemas=request.tools,
+                            output_type=str,  # Provider returns raw string
+                        )
+                        formatted_messages.append(
+                            {"role": "system", "content": formatted_content}
+                        )
+                    else:
+                        formatted_messages.append(msg)
+                messages = formatted_messages
+
             # Build litellm.completion arguments
             completion_args: dict[str, Any] = {
                 "model": effective_model,
-                "messages": request.messages,
+                "messages": messages,
                 **litellm_kwargs,
             }