fix: hud build and hud analyze distinguish between http mode and stdio (#370)

* support http mode for mcp analyze

* misc: more robust coverage for docker command

* nit: ruff

* misc: clean up shell prefix

* misc: bump version number

* fix: ruff

* ruff

* fix: add timeout for http mode client aenter

Author: Parth220

hud/cli/analyze.py

@@ -439,6 +439,22 @@ async def analyze_environment_from_mcp_config(
     await _analyze_with_config(mcp_config, output_format, verbose)
 
 
+def _prepare_mcp_config(mcp_config: dict[str, Any]) -> dict[str, Any]:
+    """Inject ``auth: None`` into URL-based server entries.
+
+    FastMCPClient attempts OAuth discovery on servers that expose a ``url``
+    field.  For local / dev servers this causes hangs or connection errors.
+    Setting ``auth`` to ``None`` disables the discovery probe.
+    """
+    patched: dict[str, Any] = {}
+    for key, value in mcp_config.items():
+        if isinstance(value, dict) and "url" in value and "auth" not in value:
+            patched[key] = {**value, "auth": None}
+        else:
+            patched[key] = value
+    return patched
+
+
 async def _analyze_with_config(
     mcp_config: dict[str, Any], output_format: str, verbose: bool
 ) -> None:
@@ -455,7 +471,8 @@ async def _analyze_with_config(
 
         from hud.cli.utils.mcp import analyze_environment as mcp_analyze
 
-        client = FastMCPClient(transport=mcp_config)
+        config = _prepare_mcp_config(mcp_config)
+        client = FastMCPClient(transport=config)
 
         try:
             await client.__aenter__()

hud/cli/build.py

@@ -461,107 +461,119 @@ def collect_runtime_metadata(image: str, *, verbose: bool = False) -> dict[str,
 async def analyze_mcp_environment(
     image: str, verbose: bool = False, env_vars: dict[str, str] | None = None
 ) -> dict[str, Any]:
-    """Analyze an MCP environment to extract metadata."""
+    """Analyze an MCP environment to extract metadata.
+
+    Supports both stdio (default) and HTTP transport.  The transport is
+    auto-detected from the image's CMD directive.
+    """
+    from fastmcp import Client as FastMCPClient
+
+    from hud.cli.utils.docker import (
+        DEFAULT_HTTP_PORT,
+        build_env_flags,
+        detect_transport,
+        stop_container,
+    )
+    from hud.cli.utils.mcp import analyze_environment
+
     hud_console = HUDConsole()
     env_vars = env_vars or {}
+    transport_mode, container_port = detect_transport(image)
+    is_http = transport_mode == "http"
+    container_name: str | None = None
+    initialized = False
+    client: Any = None
 
-    # Build Docker command to run the image, injecting any provided env vars
-    from hud.cli.utils.docker import build_env_flags
+    try:
+        # --- transport-specific setup ---
+        if is_http:
+            from hud.cli.utils.logging import find_free_port
+            from hud.cli.utils.mcp import wait_for_http_server
+
+            port = container_port or DEFAULT_HTTP_PORT
+            host_port = find_free_port(port)
+            if host_port is None:
+                from hud.shared.exceptions import HudException
+
+                raise HudException(f"No free port found starting from {port}")
+
+            container_name = f"hud-build-analyze-{os.getpid()}"
+            docker_cmd = [
+                "docker",
+                "run",
+                "-d",
+                "--rm",
+                "--name",
+                container_name,
+                "-p",
+                f"{host_port}:{port}",
+                *build_env_flags(env_vars),
+                image,
+            ]
+            hud_console.dim_info("Command:", " ".join(docker_cmd))
+            hud_console.info(f"HTTP transport detected — mapping port {host_port}:{port}")
 
-    docker_cmd = ["docker", "run", "--rm", "-i", *build_env_flags(env_vars), image]
+            try:
+                proc = await asyncio.to_thread(
+                    subprocess.run,
+                    docker_cmd,
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                    timeout=30,
+                )
+            except subprocess.CalledProcessError as e:
+                from hud.shared.exceptions import HudException
 
-    # Show full docker command being used for analysis
-    hud_console.dim_info("Command:", " ".join(docker_cmd))
+                hud_console.error(f"Failed to start container: {e.stderr.strip()}")
+                raise HudException("Failed to start Docker container for HTTP analysis") from e
 
-    # Create MCP config consistently with analyze helpers
-    from hud.cli.analyze import parse_docker_command
+            if verbose:
+                hud_console.info(f"Container started: {proc.stdout.strip()[:12]}")
 
-    mcp_config = parse_docker_command(docker_cmd)
-    # Extract server name for display (first key in mcp_config)
-    server_name = next(iter(mcp_config.keys()), None)
+            server_url = f"http://localhost:{host_port}/mcp"
+            if verbose:
+                hud_console.info(f"Waiting for server at {server_url} ...")
 
-    # Initialize client and measure timing
-    from fastmcp import Client as FastMCPClient
+            mcp_config: dict[str, Any] = {"hud": {"url": server_url, "auth": None}}
+            server_name = "hud"
+        else:
+            docker_cmd = ["docker", "run", "--rm", "-i", *build_env_flags(env_vars), image]
+            hud_console.dim_info("Command:", " ".join(docker_cmd))
 
-    from hud.cli.utils.mcp import analyze_environment
+            from hud.cli.analyze import parse_docker_command
 
-    start_time = time.time()
-    client = FastMCPClient(transport=mcp_config)
-    initialized = False
+            mcp_config = parse_docker_command(docker_cmd)
+            server_name = next(iter(mcp_config.keys()), None)
+
+        # --- shared: connect, analyze, build result ---
+        start_time = time.time()
+        client = FastMCPClient(transport=mcp_config)
 
-    try:
         if verbose:
             hud_console.info("Initializing MCP client...")
 
-        # Add timeout to fail fast instead of hanging (60 seconds)
-        await asyncio.wait_for(client.__aenter__(), timeout=60.0)
+        if is_http:
+            await wait_for_http_server(  # type: ignore[possibly-undefined]
+                server_url, timeout_seconds=60.0
+            )
+            await asyncio.wait_for(client.__aenter__(), timeout=60.0)
+        else:
+            await asyncio.wait_for(client.__aenter__(), timeout=60.0)
+
         initialized = True
         initialize_ms = int((time.time() - start_time) * 1000)
 
-        # Delegate to standard analysis helper
         full_analysis = await analyze_environment(client, verbose, server_name=server_name)
-
-        # Normalize and enrich with internalTools if a hub map is present
-        tools_list = full_analysis.get("tools", [])
-        hub_map = full_analysis.get("hub_tools", {}) or full_analysis.get("hubTools", {})
-
-        normalized_tools: list[dict[str, Any]] = []
-        internal_total = 0
-        for t in tools_list:
-            # Extract core fields (support object or dict forms)
-            if hasattr(t, "name"):
-                name = getattr(t, "name", None)
-                description = getattr(t, "description", None)
-                input_schema = getattr(t, "inputSchema", None)
-                existing_internal = getattr(t, "internalTools", None)
-            else:
-                name = t.get("name")
-                description = t.get("description")
-                # accept either inputSchema or input_schema
-                input_schema = t.get("inputSchema") or t.get("input_schema")
-                # accept either internalTools or internal_tools
-                existing_internal = t.get("internalTools") or t.get("internal_tools")
-
-            tool_entry: dict[str, Any] = {"name": name}
-            if description:
-                tool_entry["description"] = description
-            if input_schema:
-                tool_entry["inputSchema"] = input_schema
-
-            # Merge internal tools: preserve any existing declaration and add hub_map[name]
-            merged_internal: list[str] = []
-            if isinstance(existing_internal, list):
-                merged_internal.extend([str(x) for x in existing_internal])
-            if isinstance(hub_map, dict) and name in hub_map and isinstance(hub_map[name], list):
-                merged_internal.extend([str(x) for x in hub_map[name]])
-            if merged_internal:
-                # Deduplicate while preserving order
-                merged_internal = list(dict.fromkeys(merged_internal))
-                tool_entry["internalTools"] = merged_internal
-                internal_total += len(merged_internal)
-
-            normalized_tools.append(tool_entry)
-
-        result = {
-            "initializeMs": initialize_ms,
-            "toolCount": len(tools_list),
-            "internalToolCount": internal_total,
-            "tools": normalized_tools,
-            "success": True,
-        }
-        if hub_map:
-            result["hub_tools"] = hub_map
-        # Include prompts and resources from analysis
-        if full_analysis.get("prompts"):
-            result["prompts"] = full_analysis["prompts"]
-        if full_analysis.get("resources"):
-            result["resources"] = full_analysis["resources"]
-        if "scenarios" in full_analysis:
-            result["scenarios"] = full_analysis["scenarios"]
-        return result
+        return _build_analysis_result(full_analysis, initialize_ms)
     except TimeoutError:
         from hud.shared.exceptions import HudException
 
+        if is_http:
+            hud_console.error("MCP server did not become ready/initialize within 60 seconds")
+            if container_name:
+                hud_console.info("Check container logs: docker logs " + container_name)
+            raise HudException("MCP server HTTP readiness timeout") from None
         hud_console.error("MCP server initialization timed out after 60 seconds")
         hud_console.info(
             "The server likely crashed during startup - check stderr logs with 'hud debug'"
@@ -570,16 +582,70 @@ async def analyze_mcp_environment(
     except Exception as e:
         from hud.shared.exceptions import HudException
 
-        # Convert to HudException for better error messages and hints
+        if isinstance(e, HudException):
+            raise
         raise HudException from e
     finally:
-        # Only shutdown if we successfully initialized
-        if initialized and client.is_connected():
-            try:
+        if initialized and client is not None:
+            with contextlib.suppress(Exception):
                 await client.close()
-            except Exception:
-                # Ignore shutdown errors
-                hud_console.warning("Failed to shutdown MCP client")
+        if container_name:
+            stop_container(container_name)
+
+
+def _build_analysis_result(full_analysis: dict[str, Any], initialize_ms: int) -> dict[str, Any]:
+    """Normalize the raw analysis dict into the build-lock result format."""
+    tools_list = full_analysis.get("tools", [])
+    hub_map = full_analysis.get("hub_tools", {}) or full_analysis.get("hubTools", {})
+
+    normalized_tools: list[dict[str, Any]] = []
+    internal_total = 0
+    for t in tools_list:
+        if hasattr(t, "name"):
+            name = getattr(t, "name", None)
+            description = getattr(t, "description", None)
+            input_schema = getattr(t, "inputSchema", None)
+            existing_internal = getattr(t, "internalTools", None)
+        else:
+            name = t.get("name")
+            description = t.get("description")
+            input_schema = t.get("inputSchema") or t.get("input_schema")
+            existing_internal = t.get("internalTools") or t.get("internal_tools")
+
+        tool_entry: dict[str, Any] = {"name": name}
+        if description:
+            tool_entry["description"] = description
+        if input_schema:
+            tool_entry["inputSchema"] = input_schema
+
+        merged_internal: list[str] = []
+        if isinstance(existing_internal, list):
+            merged_internal.extend([str(x) for x in existing_internal])
+        if isinstance(hub_map, dict) and name in hub_map and isinstance(hub_map[name], list):
+            merged_internal.extend([str(x) for x in hub_map[name]])
+        if merged_internal:
+            merged_internal = list(dict.fromkeys(merged_internal))
+            tool_entry["internalTools"] = merged_internal
+            internal_total += len(merged_internal)
+
+        normalized_tools.append(tool_entry)
+
+    result: dict[str, Any] = {
+        "initializeMs": initialize_ms,
+        "toolCount": len(tools_list),
+        "internalToolCount": internal_total,
+        "tools": normalized_tools,
+        "success": True,
+    }
+    if hub_map:
+        result["hub_tools"] = hub_map
+    if full_analysis.get("prompts"):
+        result["prompts"] = full_analysis["prompts"]
+    if full_analysis.get("resources"):
+        result["resources"] = full_analysis["resources"]
+    if "scenarios" in full_analysis:
+        result["scenarios"] = full_analysis["scenarios"]
+    return result
 
 
 def build_docker_image(

hud/cli/tests/test_analyze_module.py

@@ -6,6 +6,7 @@
 import pytest
 
 from hud.cli.analyze import (
+    _prepare_mcp_config,
     analyze_environment,
     analyze_environment_from_config,
     analyze_environment_from_mcp_config,
@@ -125,3 +126,42 @@ async def test_analyze_environment_from_mcp_config(MockClient, mock_mcp_analyze)
     mcp_config = {"local": {"command": "docker", "args": ["run", "img"]}}
     await analyze_environment_from_mcp_config(mcp_config, output_format="json", verbose=False)
     assert client.__aenter__.awaited and client.close.awaited
+
+
+@patch("hud.cli.utils.mcp.analyze_environment")
+@patch("fastmcp.Client")
+async def test_analyze_environment_from_mcp_config_http(MockClient, mock_mcp_analyze):
+    """HTTP transport (hud dev) should inject auth=None to skip OAuth discovery."""
+    client = MagicMock()
+    client.__aenter__ = AsyncMock(return_value=client)
+    client.is_connected = MagicMock(return_value=True)
+    client.close = AsyncMock()
+    MockClient.return_value = client
+    mock_mcp_analyze.return_value = {"tools": [], "resources": []}
+
+    mcp_config = {"hud": {"url": "http://localhost:8000/mcp"}}
+    await analyze_environment_from_mcp_config(mcp_config, output_format="json", verbose=False)
+    assert client.__aenter__.awaited and client.close.awaited
+    # Verify that _prepare_mcp_config injected auth=None
+    call_kwargs = MockClient.call_args
+    transport_arg = call_kwargs.kwargs.get("transport") or call_kwargs.args[0]
+    assert transport_arg["hud"]["auth"] is None
+
+
+def test_prepare_mcp_config_injects_auth_for_url():
+    """URL-based entries get auth=None; stdio entries are left alone."""
+    cfg = {
+        "hud": {"url": "http://localhost:8000/mcp"},
+        "local": {"command": "docker", "args": ["run", "img"]},
+    }
+    result = _prepare_mcp_config(cfg)
+    assert result["hud"]["auth"] is None
+    assert result["hud"]["url"] == "http://localhost:8000/mcp"
+    assert "auth" not in result["local"]
+
+
+def test_prepare_mcp_config_preserves_explicit_auth():
+    """If auth is already set, don't overwrite it."""
+    cfg = {"hud": {"url": "http://localhost:8000/mcp", "auth": "bearer-token"}}
+    result = _prepare_mcp_config(cfg)
+    assert result["hud"]["auth"] == "bearer-token"