hud-python 0.4.47__py3-none-any.whl → 0.4.49__py3-none-any.whl

hud/server/server.py

@@ -133,7 +133,9 @@ class MCPServer(FastMCP):
        FastMCP ``FunctionTool`` interface.
     """
 
-    def __init__(self, *, name: str | None = None, **fastmcp_kwargs: Any) -> None:
+    def __init__(
+        self, name: str | None = None, instructions: str | None = None, **fastmcp_kwargs: Any
+    ) -> None:
         # Store shutdown function placeholder before super().__init__
         self._shutdown_fn: Callable | None = None
 
@@ -179,7 +181,7 @@ class MCPServer(FastMCP):
 
             fastmcp_kwargs["lifespan"] = _lifespan
 
-        super().__init__(name=name, **fastmcp_kwargs)
+        super().__init__(name=name, instructions=instructions, **fastmcp_kwargs)
         self._initializer_fn: Callable | None = None
         self._did_init = False
         self._replaced_server = False
@@ -382,90 +384,255 @@ class MCPServer(FastMCP):
 
         return _wrapper
 
+    def include_router(
+        self,
+        router: FastMCP,
+        prefix: str | None = None,
+        hidden: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Include a router's tools/resources with optional hidden dispatcher pattern.
+
+        Uses import_server for fast static composition (unlike mount which is slower).
+
+        Args:
+            router: FastMCP router to include
+            prefix: Optional prefix for tools/resources (ignored if hidden=True)
+            hidden: If True, wrap in HiddenRouter (single dispatcher tool that calls sub-tools)
+            **kwargs: Additional arguments passed to import_server()
+
+        Examples:
+            # Direct include - tools appear at top level
+            mcp.include_router(tools_router)
+
+            # Prefixed include - tools get prefix
+            mcp.include_router(admin_router, prefix="admin")
+
+            # Hidden include - single dispatcher tool
+            mcp.include_router(setup_router, hidden=True)
+        """
+        if not hidden:
+            # Synchronous composition - directly copy tools/resources
+            self._sync_import_router(router, hidden=False, prefix=prefix, **kwargs)
+            return
+
+        # Hidden pattern: wrap in HiddenRouter before importing
+        from .router import HiddenRouter
+
+        # Import the hidden router (synchronous)
+        self._sync_import_router(HiddenRouter(router), hidden=True, prefix=prefix, **kwargs)
+
+    def _sync_import_router(
+        self,
+        router: FastMCP,
+        hidden: bool = False,
+        prefix: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Synchronously import tools/resources from a router.
+
+        This is a synchronous alternative to import_server for use at module import time.
+        """
+        import re
+
+        # Import tools directly - use internal dict to preserve keys
+        tools = (
+            router._tool_manager._tools.items() if not hidden else router._sync_list_tools().items()  # type: ignore
+        )
+        for key, tool in tools:
+            # Validate tool name
+            if not re.match(r"^[a-zA-Z0-9_-]{1,128}$", key):
+                raise ValueError(
+                    f"Tool name '{key}' must match ^[a-zA-Z0-9_-]{{1,128}}$ "
+                    "(letters, numbers, underscore, hyphen only, 1-128 chars)"
+                )
+
+            new_key = f"{prefix}_{key}" if prefix else key
+            self._tool_manager._tools[new_key] = tool
+
+        # Import resources directly
+        for key, resource in router._resource_manager._resources.items():
+            new_key = f"{prefix}_{key}" if prefix else key
+            self._resource_manager._resources[new_key] = resource
+
+        # Import prompts directly
+        for key, prompt in router._prompt_manager._prompts.items():
+            new_key = f"{prefix}_{key}" if prefix else key
+            self._prompt_manager._prompts[new_key] = prompt
+        # await self.import_server(hidden_router, prefix=None, **kwargs)
+
     def _register_hud_helpers(self) -> None:
-        """Register HUD helper HTTP routes.
+        """Register development helper endpoints.
 
         This adds:
-        - GET /hud - Overview of available endpoints
-        - GET /hud/tools - List all registered tools with their schemas
-        - GET /hud/resources - List all registered resources
-        - GET /hud/prompts - List all registered prompts
+        - GET /docs - Interactive documentation and tool testing
+        - POST /api/tools/{name} - REST wrappers for MCP tools
+        - GET /openapi.json - OpenAPI spec for REST endpoints
         """
 
-        @self.custom_route("/hud/tools", methods=["GET"])
-        async def list_tools(request: Request) -> Response:
-            """List all registered tools with their names, descriptions, and schemas."""
-            tools = []
-            # _tools is a mapping of tool_name -> FunctionTool/Tool instance
+        # Register REST wrapper for each tool
+        def create_tool_endpoint(key: str) -> Any:
+            """Create a REST endpoint for an MCP tool."""
+
+            async def tool_endpoint(request: Request) -> Response:
+                """Call MCP tool via REST endpoint."""
+                try:
+                    data = await request.json()
+                except Exception:
+                    data = {}
+
+                try:
+                    result = await self._tool_manager.call_tool(key, data)
+
+                    # Recursively serialize MCP objects
+                    def serialize_obj(obj: Any) -> Any:
+                        """Recursively serialize MCP objects to JSON-compatible format."""
+                        if obj is None or isinstance(obj, (str, int, float, bool)):
+                            return obj
+                        if isinstance(obj, (list, tuple)):
+                            return [serialize_obj(item) for item in obj]
+                        if isinstance(obj, dict):
+                            return {k: serialize_obj(v) for k, v in obj.items()}
+                        if hasattr(obj, "model_dump"):
+                            # Pydantic v2
+                            return serialize_obj(obj.model_dump())
+                        if hasattr(obj, "dict"):
+                            # Pydantic v1
+                            return serialize_obj(obj.dict())
+                        if hasattr(obj, "__dict__"):
+                            # Dataclass or regular class
+                            return serialize_obj(obj.__dict__)
+                        # Fallback: convert to string
+                        return str(obj)
+
+                    serialized = serialize_obj(result)
+                    return JSONResponse({"success": True, "result": serialized})
+                except Exception as e:
+                    return JSONResponse({"success": False, "error": str(e)}, status_code=400)
+
+            return tool_endpoint
+
+        for tool_key in self._tool_manager._tools.keys():  # noqa: SIM118
+            endpoint = create_tool_endpoint(tool_key)
+            self.custom_route(f"/api/tools/{tool_key}", methods=["POST"])(endpoint)
+
+        @self.custom_route("/openapi.json", methods=["GET"])
+        async def openapi_spec(request: Request) -> Response:
+            """Generate OpenAPI spec from MCP tools."""
+            spec = {
+                "openapi": "3.1.0",
+                "info": {
+                    "title": f"{self.name or 'MCP Server'} - Testing API",
+                    "version": "1.0.0",
+                    "description": (
+                        "REST API wrappers for testing MCP tools. "
+                        "These endpoints are for development/testing only. "
+                        "Agents should connect via MCP protocol (JSON-RPC over stdio/HTTP)."
+                    ),
+                },
+                "paths": {},
+            }
+
+            # Convert each MCP tool to an OpenAPI path
             for tool_key, tool in self._tool_manager._tools.items():
-                tool_data = {"name": tool_key}
                 try:
-                    # Prefer converting to MCP model for consistent fields
                     mcp_tool = tool.to_mcp_tool()
-                    tool_data["description"] = getattr(mcp_tool, "description", "")
-                    if hasattr(mcp_tool, "inputSchema") and mcp_tool.inputSchema:
-                        tool_data["input_schema"] = mcp_tool.inputSchema  # type: ignore[assignment]
-                    if hasattr(mcp_tool, "outputSchema") and mcp_tool.outputSchema:
-                        tool_data["output_schema"] = mcp_tool.outputSchema  # type: ignore[assignment]
-                except Exception:
-                    # Fallback to direct attributes on FunctionTool
-                    tool_data["description"] = getattr(tool, "description", "")
-                    params = getattr(tool, "parameters", None)
-                    if params:
-                        tool_data["input_schema"] = params
-                tools.append(tool_data)
-
-            return JSONResponse({"server": self.name, "tools": tools, "count": len(tools)})
-
-        @self.custom_route("/hud/resources", methods=["GET"])
-        async def list_resources(request: Request) -> Response:
-            """List all registered resources."""
-            resources = []
-            for resource_key, resource in self._resource_manager._resources.items():
-                resource_data = {
-                    "uri": resource_key,
-                    "name": resource.name,
-                    "description": resource.description,
-                    "mimeType": resource.mime_type,
-                }
-                resources.append(resource_data)
-
-            return JSONResponse(
-                {"server": self.name, "resources": resources, "count": len(resources)}
-            )
+                    input_schema = mcp_tool.inputSchema or {"type": "object"}
+
+                    spec["paths"][f"/api/tools/{tool_key}"] = {
+                        "post": {
+                            "summary": tool_key,
+                            "description": mcp_tool.description or "",
+                            "operationId": f"call_{tool_key}",
+                            "requestBody": {
+                                "required": True,
+                                "content": {"application/json": {"schema": input_schema}},
+                            },
+                            "responses": {
+                                "200": {
+                                    "description": "Success",
+                                    "content": {
+                                        "application/json": {
+                                            "schema": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "success": {"type": "boolean"},
+                                                    "result": {"type": "object"},
+                                                },
+                                            }
+                                        }
+                                    },
+                                }
+                            },
+                        }
+                    }
+                except Exception as e:
+                    logger.warning("Failed to generate spec for %s: %s", tool_key, e)
+
+            return JSONResponse(spec)
+
+        @self.custom_route("/docs", methods=["GET"])
+        async def docs_page(request: Request) -> Response:
+            """Interactive documentation page."""
+            import base64
+            import json
 
-        @self.custom_route("/hud/prompts", methods=["GET"])
-        async def list_prompts(request: Request) -> Response:
-            """List all registered prompts."""
-            prompts = []
-            for prompt_key, prompt in self._prompt_manager._prompts.items():
-                prompt_data = {
-                    "name": prompt_key,
-                    "description": prompt.description,
-                }
-                # Check if it has arguments
-                if hasattr(prompt, "arguments") and prompt.arguments:
-                    prompt_data["arguments"] = [
-                        {"name": arg.name, "description": arg.description, "required": arg.required}
-                        for arg in prompt.arguments
-                    ]
-                prompts.append(prompt_data)
-
-            return JSONResponse({"server": self.name, "prompts": prompts, "count": len(prompts)})
-
-        @self.custom_route("/hud", methods=["GET"])
-        async def hud_info(request: Request) -> Response:
-            """Show available HUD helper endpoints."""
             base_url = str(request.base_url).rstrip("/")
-            return JSONResponse(
-                {
-                    "name": "HUD MCP Development Helpers",
-                    "server": self.name,
-                    "endpoints": {
-                        "tools": f"{base_url}/hud/tools",
-                        "resources": f"{base_url}/hud/resources",
-                        "prompts": f"{base_url}/hud/prompts",
-                    },
-                    "description": "These endpoints help you inspect your MCP server during development.",  # noqa: E501
-                }
-            )
+            tool_count = len(self._tool_manager._tools)
+            resource_count = len(self._resource_manager._resources)
+
+            # Generate Cursor deeplink
+            server_config = {"url": f"{base_url}/mcp"}
+            config_json = json.dumps(server_config, indent=2)
+            config_base64 = base64.b64encode(config_json.encode()).decode()
+            cursor_deeplink = f"cursor://anysphere.cursor-deeplink/mcp/install?name={self.name or 'mcp-server'}&config={config_base64}"  # noqa: E501
+
+            html = f"""
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{self.name or "MCP Server"} - Documentation</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+    <style>
+        body {{ margin: 0; padding: 0; font-family: monospace; }}
+        .header {{ padding: 1.5rem; border-bottom: 1px solid #e0e0e0; background: #fafafa; }}
+        .header h1 {{ margin: 0 0 0.5rem 0; font-size: 1.5rem; color: #000; }}
+        .header .info {{ margin: 0.25rem 0; color: #666; font-size: 0.9rem; }}
+        .header .warning {{ margin: 0.75rem 0 0 0; padding: 0.5rem; background: #fff3cd; border-left: 3px solid #ffc107; color: #856404; font-size: 0.85rem; }}
+        .header a {{ color: #000; text-decoration: underline; }}
+        .header a:hover {{ color: #666; }}
+        .topbar {{ display: none; }}
+    </style>
+</head>
+<body>
+    <div class="header">
+        <h1>{self.name or "MCP Server"} - Development Tools</h1>
+        <div class="info">MCP Endpoint (use this with agents): <a href="{base_url}/mcp">{base_url}/mcp</a></div>
+        <div class="info">Tools: {tool_count} | Resources: {resource_count}</div>
+        <div class="info">Add to Cursor: <a href="{cursor_deeplink}">Click here to install</a></div>
+        <div class="warning">
+            ⚠️ The REST API below is for testing only. Agents connect via MCP protocol at <code>{base_url}/mcp</code>
+        </div>
+    </div>
+    
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+        window.onload = function() {{
+            SwaggerUIBundle({{
+                url: '/openapi.json',
+                dom_id: '#swagger-ui',
+                deepLinking: true,
+                presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+                layout: "StandaloneLayout",
+                tryItOutEnabled: true
+            }})
+        }}
+    </script>
+</body>
+</html>
+"""  # noqa: E501
+            return Response(content=html, media_type="text/html")

hud/telemetry/trace.py

@@ -139,7 +139,7 @@ def trace(
     else:
         # Use a placeholder for custom backends
         logger.warning(
-            "HUD API key is not set, using a placeholder for the task run ID. If this looks wrong, check your API key." # noqa: E501
+            "HUD API key is not set, using a placeholder for the task run ID. If this looks wrong, check your API key."  # noqa: E501
         )
         task_run_id = str(uuid.uuid4())
 

hud/tools/base.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
+import logging
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, cast, Awaitable
+from typing import TYPE_CHECKING, Any, cast
 
 from fastmcp import FastMCP
 
 from hud.tools.types import ContentBlock, EvaluationResult
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Awaitable, Callable
 
     from fastmcp.tools import FunctionTool
     from fastmcp.tools.tool import Tool, ToolResult
@@ -16,9 +17,9 @@ if TYPE_CHECKING:
 # Basic result types for tools
 BaseResult = list[ContentBlock] | EvaluationResult
 
-import logging
 logger = logging.getLogger(__name__)
 
+
 class BaseTool(ABC):
     """
     Base helper class for all MCP tools to constrain their output.
@@ -106,9 +107,9 @@ class BaseTool(ABC):
             )
         return self._mcp_tool
 
-    def add_callback(self, event_type: str, callback: Callable[..., Awaitable[Any]]):
+    def add_callback(self, event_type: str, callback: Callable[..., Awaitable[Any]]) -> None:
         """Register a callback function for specific event
-        
+
         Args:
             event_type: (Required) Specific event name to trigger callback
                         e.g. "after_click", "before_navigate"
@@ -118,7 +119,7 @@ class BaseTool(ABC):
             self._callbacks[event_type] = []
         self._callbacks[event_type].append(callback)
 
-    def remove_callback(self, event_type: str, callback: Callable[..., Awaitable[Any]]):
+    def remove_callback(self, event_type: str, callback: Callable[..., Awaitable[Any]]) -> None:
         """Remove a registered callback
         Args:
             event_type: (Required) Specific event name to trigger callback
@@ -127,22 +128,27 @@ class BaseTool(ABC):
         """
         if (event_type in self._callbacks) and (callback in self._callbacks[event_type]):
             self._callbacks[event_type].remove(callback)
-    
-    async def _trigger_callbacks(self, event_type: str, **kwargs):
+
+    async def _trigger_callbacks(self, event_type: str, **kwargs: Any) -> None:
         """Trigger all registered callback functions of an event type"""
         callback_list = self._callbacks.get(event_type, [])
         for callback in callback_list:
             try:
                 await callback(**kwargs)
             except Exception as e:
-                logger.warning(f"Callback failed for {event_type}: {e}")
+                logger.warning("Callback failed for %s: %s", event_type, e)
+
 
 # Prefix for internal tool names
 _INTERNAL_PREFIX = "int_"
 
 
 class BaseHub(FastMCP):
-    """A composition-friendly FastMCP server that holds an internal tool dispatcher."""
+    """A composition-friendly FastMCP server that holds an internal tool dispatcher.
+
+    Note: BaseHub can be used standalone or to wrap existing routers. For the newer
+    FastAPI-like pattern, consider using HiddenRouter from hud.server instead.
+    """
 
     env: Any
 
@@ -165,6 +171,10 @@ class BaseHub(FastMCP):
             Optional long-lived environment object. Stored on the server
             instance (``layer.env``) and therefore available to every request
             via ``ctx.fastmcp.env``.
+        title:
+            Optional title for the dispatcher tool.
+        description:
+            Optional description for the dispatcher tool.
         meta:
             Metadata to include in MCP tool listing.
         """

hud/tools/computer/__init__.py

@@ -5,11 +5,13 @@ from __future__ import annotations
 from .anthropic import AnthropicComputerTool
 from .hud import HudComputerTool
 from .openai import OpenAIComputerTool
+from .qwen import QwenComputerTool
 from .settings import computer_settings
 
 __all__ = [
     "AnthropicComputerTool",
     "HudComputerTool",
     "OpenAIComputerTool",
+    "QwenComputerTool",
     "computer_settings",
 ]