refactor: replace ValidationOptions with validate_structured_outputs boolean parameter per PR feedback

Author: lorenss-m

PR_DESCRIPTION.md

@@ -0,0 +1,41 @@
+# Fix: Propagate HTTP errors to client
+
+## Motivation and Context
+HTTP request failures were not being properly communicated to clients, causing silent failures. This fix ensures errors are sent through the read stream so clients are notified when requests fail.
+
+## How Has This Been Tested?
+Has been tested in production environments (used by https://github.com/hud-evals/hud-python with a remote server).
+
+## Breaking Changes
+None - this is a backwards-compatible error handling improvement.
+
+## Types of changes
+- [x] Bug fix (non-breaking change which fixes an issue)
+
+## Checklist
+- [x] I have read the [MCP Documentation](https://modelcontextprotocol.io)
+- [x] My code follows the repository's style guidelines
+- [x] New and existing tests pass locally
+- [x] I have added appropriate error handling
+- [x] Documentation not needed for this internal fix
+
+## Additional context
+This change wraps the `handle_request_async` function in a try-catch block and sends any exceptions to `ctx.read_stream_writer` to ensure proper error propagation in the streamable HTTP transport layer.
+
+### Example scenario where this fix is critical:
+
+**HTTP Error Codes (502, 503, 504, etc.)**
+```python
+# Without this fix: Client hangs when server returns 502 Bad Gateway
+# With this fix: Client receives the HTTP error
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.client.session import ClientSession
+
+async with streamablehttp_client(server_url) as (read_stream, write_stream):
+    async with ClientSession(read_stream, write_stream) as session:
+        await session.initialize()
+        try:
+            result = await session.call_tool("api_operation", arguments={})
+        except Exception as e:
+            print(f"Error received: {e}")  # Now properly catches 502, 503, 504 errors
+```

src/hud_mcp/__init__.py

@@ -0,0 +1,116 @@
+from .client.session import ClientSession
+from .client.session_group import ClientSessionGroup
+from .client.stdio import StdioServerParameters, stdio_client
+from .server.session import ServerSession
+from .server.stdio import stdio_server
+from .shared.exceptions import McpError
+from .types import (
+    CallToolRequest,
+    ClientCapabilities,
+    ClientNotification,
+    ClientRequest,
+    ClientResult,
+    CompleteRequest,
+    CreateMessageRequest,
+    CreateMessageResult,
+    ErrorData,
+    GetPromptRequest,
+    GetPromptResult,
+    Implementation,
+    IncludeContext,
+    InitializedNotification,
+    InitializeRequest,
+    InitializeResult,
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    ListPromptsRequest,
+    ListPromptsResult,
+    ListResourcesRequest,
+    ListResourcesResult,
+    ListToolsResult,
+    LoggingLevel,
+    LoggingMessageNotification,
+    Notification,
+    PingRequest,
+    ProgressNotification,
+    PromptsCapability,
+    ReadResourceRequest,
+    ReadResourceResult,
+    Resource,
+    ResourcesCapability,
+    ResourceUpdatedNotification,
+    RootsCapability,
+    SamplingMessage,
+    ServerCapabilities,
+    ServerNotification,
+    ServerRequest,
+    ServerResult,
+    SetLevelRequest,
+    StopReason,
+    SubscribeRequest,
+    Tool,
+    ToolsCapability,
+    UnsubscribeRequest,
+)
+from .types import (
+    Role as SamplingRole,
+)
+
+__all__ = [
+    "CallToolRequest",
+    "ClientCapabilities",
+    "ClientNotification",
+    "ClientRequest",
+    "ClientResult",
+    "ClientSession",
+    "ClientSessionGroup",
+    "CreateMessageRequest",
+    "CreateMessageResult",
+    "ErrorData",
+    "GetPromptRequest",
+    "GetPromptResult",
+    "Implementation",
+    "IncludeContext",
+    "InitializeRequest",
+    "InitializeResult",
+    "InitializedNotification",
+    "JSONRPCError",
+    "JSONRPCRequest",
+    "ListPromptsRequest",
+    "ListPromptsResult",
+    "ListResourcesRequest",
+    "ListResourcesResult",
+    "ListToolsResult",
+    "LoggingLevel",
+    "LoggingMessageNotification",
+    "McpError",
+    "Notification",
+    "PingRequest",
+    "ProgressNotification",
+    "PromptsCapability",
+    "ReadResourceRequest",
+    "ReadResourceResult",
+    "ResourcesCapability",
+    "ResourceUpdatedNotification",
+    "Resource",
+    "RootsCapability",
+    "SamplingMessage",
+    "SamplingRole",
+    "ServerCapabilities",
+    "ServerNotification",
+    "ServerRequest",
+    "ServerResult",
+    "ServerSession",
+    "SetLevelRequest",
+    "StdioServerParameters",
+    "StopReason",
+    "SubscribeRequest",
+    "Tool",
+    "ToolsCapability",
+    "UnsubscribeRequest",
+    "stdio_client",
+    "stdio_server",
+    "CompleteRequest",
+    "JSONRPCResponse",
+]

src/hud_mcp/cli/__init__.py

@@ -0,0 +1,6 @@
+"""FastMCP CLI package."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

src/hud_mcp/cli/claude.py

@@ -0,0 +1,148 @@
+"""Claude app integration utilities."""
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+MCP_PACKAGE = "mcp[cli]"
+
+
+def get_claude_config_path() -> Path | None:
+    """Get the Claude config directory based on platform."""
+    if sys.platform == "win32":
+        path = Path(Path.home(), "AppData", "Roaming", "Claude")
+    elif sys.platform == "darwin":
+        path = Path(Path.home(), "Library", "Application Support", "Claude")
+    elif sys.platform.startswith("linux"):
+        path = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"), "Claude")
+    else:
+        return None
+
+    if path.exists():
+        return path
+    return None
+
+
+def get_uv_path() -> str:
+    """Get the full path to the uv executable."""
+    uv_path = shutil.which("uv")
+    if not uv_path:
+        logger.error(
+            "uv executable not found in PATH, falling back to 'uv'. Please ensure uv is installed and in your PATH"
+        )
+        return "uv"  # Fall back to just "uv" if not found
+    return uv_path
+
+
+def update_claude_config(
+    file_spec: str,
+    server_name: str,
+    *,
+    with_editable: Path | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+) -> bool:
+    """Add or update a FastMCP server in Claude's configuration.
+
+    Args:
+        file_spec: Path to the server file, optionally with :object suffix
+        server_name: Name for the server in Claude's config
+        with_editable: Optional directory to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables. These are merged with
+            any existing variables, with new values taking precedence.
+
+    Raises:
+        RuntimeError: If Claude Desktop's config directory is not found, indicating
+            Claude Desktop may not be installed or properly set up.
+    """
+    config_dir = get_claude_config_path()
+    uv_path = get_uv_path()
+    if not config_dir:
+        raise RuntimeError(
+            "Claude Desktop config directory not found. Please ensure Claude Desktop"
+            " is installed and has been run at least once to initialize its config."
+        )
+
+    config_file = config_dir / "claude_desktop_config.json"
+    if not config_file.exists():
+        try:
+            config_file.write_text("{}")
+        except Exception:
+            logger.exception(
+                "Failed to create Claude config file",
+                extra={
+                    "config_file": str(config_file),
+                },
+            )
+            return False
+
+    try:
+        config = json.loads(config_file.read_text())
+        if "mcpServers" not in config:
+            config["mcpServers"] = {}
+
+        # Always preserve existing env vars and merge with new ones
+        if server_name in config["mcpServers"] and "env" in config["mcpServers"][server_name]:
+            existing_env = config["mcpServers"][server_name]["env"]
+            if env_vars:
+                # New vars take precedence over existing ones
+                env_vars = {**existing_env, **env_vars}
+            else:
+                env_vars = existing_env
+
+        # Build uv run command
+        args = ["run"]
+
+        # Collect all packages in a set to deduplicate
+        packages = {MCP_PACKAGE}
+        if with_packages:
+            packages.update(pkg for pkg in with_packages if pkg)
+
+        # Add all packages with --with
+        for pkg in sorted(packages):
+            args.extend(["--with", pkg])
+
+        if with_editable:
+            args.extend(["--with-editable", str(with_editable)])
+
+        # Convert file path to absolute before adding to command
+        # Split off any :object suffix first
+        if ":" in file_spec:
+            file_path, server_object = file_spec.rsplit(":", 1)
+            file_spec = f"{Path(file_path).resolve()}:{server_object}"
+        else:
+            file_spec = str(Path(file_spec).resolve())
+
+        # Add fastmcp run command
+        args.extend(["mcp", "run", file_spec])
+
+        server_config: dict[str, Any] = {"command": uv_path, "args": args}
+
+        # Add environment variables if specified
+        if env_vars:
+            server_config["env"] = env_vars
+
+        config["mcpServers"][server_name] = server_config
+
+        config_file.write_text(json.dumps(config, indent=2))
+        logger.info(
+            f"Added server '{server_name}' to Claude config",
+            extra={"config_file": str(config_file)},
+        )
+        return True
+    except Exception:
+        logger.exception(
+            "Failed to update Claude config",
+            extra={
+                "config_file": str(config_file),
+            },
+        )
+        return False