ha-mcp-dev 7.4.1.dev411__tar.gz → 7.4.1.dev413__tar.gz

{ha_mcp_dev-7.4.1.dev411/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev413}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev411
+Version: 7.4.1.dev413
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.4.1.dev411 → ha_mcp_dev-7.4.1.dev413}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev411"
+version = "7.4.1.dev413"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.4.1.dev411 → ha_mcp_dev-7.4.1.dev413}/src/ha_mcp/tools/tools_addons.py

@@ -28,23 +28,169 @@ from ..errors import (
     create_timeout_error,
     create_validation_error,
 )
+from ..utils.python_sandbox import PythonSandboxError, safe_execute_expression
 from .helpers import (
     exception_to_structured_error,
     get_connected_ws_client,
     log_tool_usage,
     raise_tool_error,
 )
+from .util_helpers import ANSI_ESCAPE_RE
 
 logger = logging.getLogger(__name__)
 
 # Maximum response size to return from add-on API calls (50 KB)
 _MAX_RESPONSE_SIZE = 50 * 1024
 
-# Maximum number of WebSocket messages to collect
+# Hard safety cap on WebSocket messages collected per call. `message_limit`
+# can lower this but never raise it.
 _MAX_WS_MESSAGES = 1000
 
-# ANSI escape code pattern for stripping terminal colors from addon output
-_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+# Substrings that flag a WebSocket message as "signal" for the summarize pass.
+# Keep conservative: false negatives get elided, false positives just mean
+# no elision. Case-insensitive match on the JSON-stringified message.
+_SIGNAL_PATTERNS = re.compile(
+    r"(?:^|[^A-Za-z])(INFO|WARN(?:ING)?|ERROR|FATAL|FAIL(?:ED|URE)?|EXCEPTION|"
+    r"TRACEBACK|Configuration is valid|Successfully|unsuccessful|exit|"
+    r"returncode|Compiling|Linking)",
+    re.IGNORECASE,
+)
+
+# Consecutive non-signal messages needed to trigger elision. Below this,
+# the run passes through untouched.
+_SUMMARIZE_RUN_THRESHOLD = 10
+
+# Messages preserved verbatim at each end of an elided run for context.
+_SUMMARIZE_CONTEXT_KEEP = 2
+
+
+def _slice_ws_messages(
+    messages: list[Any],
+    offset: int,
+    limit: int | None,
+) -> tuple[list[Any], dict[str, Any]]:
+    """Apply offset/limit to a collected WebSocket message list.
+
+    Returns ``(sliced_messages, pagination_metadata)``. Pagination metadata
+    is always returned so the response shape is stable regardless of whether
+    offset/limit were applied.
+    """
+    total_collected = len(messages)
+    if offset < 0:
+        offset = 0
+    if offset > total_collected:
+        sliced: list[Any] = []
+    elif limit is None:
+        sliced = messages[offset:]
+    else:
+        if limit < 0:
+            limit = 0
+        sliced = messages[offset : offset + limit]
+
+    pagination: dict[str, Any] = {
+        "total_collected": total_collected,
+        "offset": offset,
+        "returned": len(sliced),
+    }
+    if limit is not None:
+        pagination["limit"] = limit
+    return sliced, pagination
+
+
+def _is_signal_message(msg: Any) -> bool:
+    """Return True if ``msg`` looks like a log line or terminal event worth keeping.
+
+    The heuristic errs toward keeping messages — false positives just mean
+    a run doesn't get elided.
+    """
+    if isinstance(msg, (dict, list)):
+        serialized = json.dumps(msg, default=str)
+    else:
+        serialized = str(msg)
+    return bool(_SIGNAL_PATTERNS.search(serialized[:2000]))
+
+
+def _summarize_ws_messages(
+    messages: list[Any],
+    *,
+    run_threshold: int = _SUMMARIZE_RUN_THRESHOLD,
+    context_keep: int = _SUMMARIZE_CONTEXT_KEEP,
+) -> tuple[list[Any], dict[str, Any]]:
+    """Collapse runs of non-signal WebSocket messages into elision markers.
+
+    Each run of ≥ ``run_threshold`` consecutive non-signal entries becomes:
+    ``context_keep`` originals, one elision dict
+    ``{"elided": N, "note": "..."}``, then ``context_keep`` originals.
+    Signal messages always pass through unchanged.
+    """
+    result: list[Any] = []
+    run_start: int | None = None
+    elided_total = 0
+
+    def flush(run_end: int) -> None:
+        nonlocal elided_total
+        assert run_start is not None
+        run_len = run_end - run_start
+        if run_len >= run_threshold:
+            result.extend(messages[run_start : run_start + context_keep])
+            elided_count = run_len - 2 * context_keep
+            result.append(
+                {
+                    "elided": elided_count,
+                    "note": (
+                        f"{elided_count} non-signal messages elided; "
+                        "pass summarize=False for full output"
+                    ),
+                }
+            )
+            result.extend(messages[run_end - context_keep : run_end])
+            elided_total += elided_count
+        else:
+            result.extend(messages[run_start:run_end])
+
+    for i, msg in enumerate(messages):
+        if _is_signal_message(msg):
+            if run_start is not None:
+                flush(i)
+                run_start = None
+            result.append(msg)
+        else:
+            if run_start is None:
+                run_start = i
+
+    if run_start is not None:
+        flush(len(messages))
+
+    return result, {
+        "original_count": len(messages),
+        "summarized_count": len(result),
+        "elided_count": elided_total,
+    }
+
+
+def _apply_response_transform(response: Any, expr: str) -> Any:
+    """Run a sandboxed ``python_transform`` expression against ``response``.
+
+    Exposes the value to the expression as ``response``. Supports both
+    in-place mutation and reassignment (``response = [...]``). Raises
+    ToolError with VALIDATION_FAILED on sandbox errors so the agent gets
+    a structured code it can react to.
+    """
+    try:
+        return safe_execute_expression(expr, {"response": response}, "response")
+    except PythonSandboxError as e:
+        raise_tool_error(
+            create_error_response(
+                ErrorCode.VALIDATION_FAILED,
+                f"python_transform failed: {e!s}",
+                context={"expression_preview": expr[:200]},
+                suggestions=[
+                    "Operate on the `response` variable (in-place or reassign)",
+                    "Allowed: dict/list access, assignment, loops, "
+                    "comprehensions, whitelisted str/list/dict methods",
+                ],
+            )
+        )
 
 
 def _merge_options(base: dict, override: dict) -> dict:
@@ -325,6 +471,10 @@ async def _call_addon_ws(
     debug: bool = False,
     port: int | None = None,
     wait_for_close: bool = True,
+    message_limit: int | None = None,
+    message_offset: int = 0,
+    summarize: bool = True,
+    python_transform: str | None = None,
 ) -> dict[str, Any]:
     """Connect to an add-on's WebSocket API and collect messages.
 
@@ -338,6 +488,20 @@ async def _call_addon_ws(
         port: Override port (same as HTTP tool)
         wait_for_close: If True, collect messages until server closes or timeout.
             If False, return after first batch of messages (up to 2s of silence).
+        message_limit: Cap on messages collected from the wire. Bounded by the
+            hard ceiling ``_MAX_WS_MESSAGES``. None means "collect up to the
+            ceiling" (legacy behavior).
+        message_offset: Drop this many messages from the start of the collected
+            list before returning. Useful for paginating past a known-noisy
+            header when re-running the same call.
+        summarize: When True (default), collapse runs of non-signal messages
+            (typically YAML config dumps) into short elision markers. Set to
+            False to return the raw stream.
+        python_transform: Optional sandboxed Python expression that post-
+            processes the response. The variable ``response`` is bound to
+            the list of parsed messages (``list[dict | str]``); the value
+            of ``response`` after execution replaces ``messages`` in the
+            output. See ``ha_manage_addon`` docstring for details.
 
     Returns:
         Dictionary with collected messages, metadata, and status.
@@ -427,6 +591,16 @@ async def _call_addon_ws(
     close_reason = "unknown"
     start_time = time.monotonic()
 
+    # Effective collection cap: callers may lower _MAX_WS_MESSAGES via
+    # message_limit but cannot raise it. A caller's message_limit interacts
+    # with message_offset — we collect enough to satisfy `offset + limit`
+    # so requesting a later window actually returns the window.
+    if message_limit is None:
+        collection_cap = _MAX_WS_MESSAGES
+    else:
+        requested = max(0, message_offset) + max(0, message_limit)
+        collection_cap = min(_MAX_WS_MESSAGES, requested)
+
     try:
         async with websockets.connect(
             ws_url,
@@ -451,8 +625,15 @@ async def _call_addon_ws(
                     close_reason = "timeout"
                     break
 
-                if len(collected) >= _MAX_WS_MESSAGES:
-                    close_reason = "message_limit"
+                if len(collected) >= collection_cap:
+                    # Distinguish caller-set cap from the global safety ceiling
+                    # so an agent reading the response can tell "I capped this"
+                    # from "ha-mcp's hard ceiling kicked in".
+                    close_reason = (
+                        "message_limit"
+                        if message_limit is not None
+                        else "safety_ceiling"
+                    )
                     break
 
                 if total_size >= _MAX_RESPONSE_SIZE:
@@ -478,7 +659,7 @@ async def _call_addon_ws(
                     continue
 
                 # Strip ANSI escape codes
-                clean = _ANSI_ESCAPE_RE.sub("", message)
+                clean = ANSI_ESCAPE_RE.sub("", message)
                 collected.append(clean)
                 total_size += len(clean)
 
@@ -527,7 +708,9 @@ async def _call_addon_ws(
     elapsed = round(time.monotonic() - start_time, 2)
 
     # 8. Build result
-    # Try to parse each message as JSON; keep as string if not JSON
+    # Try to parse each message as JSON; keep as string if not JSON.
+    # Result shape is list[dict | str] — the heterogeneity is part of the
+    # python_transform contract (see ha_manage_addon docstring).
     parsed_messages: list[Any] = []
     for msg in collected:
         try:
@@ -535,22 +718,61 @@ async def _call_addon_ws(
         except (json.JSONDecodeError, ValueError):
             parsed_messages.append(msg)
 
+    # 8a. Apply offset/limit slicing before summarize/transform so users
+    # paginate the raw collected list, not the post-summarize output.
+    sliced_messages, pagination = _slice_ws_messages(
+        parsed_messages,
+        offset=message_offset,
+        limit=message_limit,
+    )
+
+    # 8b. Summarize (default on) — collapse bulk non-signal runs.
+    summary_meta: dict[str, Any] | None = None
+    processed_messages: list[Any] = sliced_messages
+    if summarize:
+        processed_messages, summary_meta = _summarize_ws_messages(sliced_messages)
+
+    # 8c. python_transform (optional) — user-controlled post-processing.
+    transformed = False
+    pre_transform_count = len(processed_messages)
+    if python_transform is not None:
+        processed_messages = _apply_response_transform(
+            processed_messages,
+            python_transform,
+        )
+        transformed = True
+
     result: dict[str, Any] = {
         "success": True,
-        "messages": parsed_messages,
-        "message_count": len(parsed_messages),
+        "messages": processed_messages,
+        "message_count": (
+            len(processed_messages) if isinstance(processed_messages, list) else None
+        ),
         "closed_by": close_reason,
         "duration_seconds": elapsed,
         "addon_name": addon_name,
         "slug": slug,
     }
 
+    # Pagination metadata is always present when offset/limit were used so
+    # callers have a stable shape to reason about.
+    if message_offset > 0 or message_limit is not None:
+        result["pagination"] = pagination
+
+    if summary_meta is not None and summary_meta["elided_count"] > 0:
+        result["summary"] = summary_meta
+
+    if transformed:
+        result["transformed"] = True
+        result["pre_transform_message_count"] = pre_transform_count
+
     if debug:
         result["_debug"] = {
             "ws_url": ws_url,
             "request_headers": dict(headers),
             "initial_message": body,
             "total_bytes_collected": total_size,
+            "collection_cap": collection_cap,
         }
 
     # Cap the serialized result size (raw bytes undercount due to JSON + MCP overhead)
@@ -559,17 +781,20 @@ async def _call_addon_ws(
         result = {
             "success": True,
             "error": "RESPONSE_TOO_LARGE",
-            "message": f"WebSocket collected {len(parsed_messages)} messages "
-            f"({len(result_serialized)} bytes serialized) exceeding "
-            f"{_MAX_RESPONSE_SIZE // 1024}KB limit.",
-            "message_count": len(parsed_messages),
+            "message": f"WebSocket response ({len(result_serialized)} bytes "
+            f"serialized) exceeds {_MAX_RESPONSE_SIZE // 1024}KB limit.",
+            "message_count": (
+                len(processed_messages)
+                if isinstance(processed_messages, list)
+                else None
+            ),
             "closed_by": close_reason,
             "duration_seconds": elapsed,
             "addon_name": addon_name,
             "slug": slug,
             "truncated": True,
-            "hint": "Use wait_for_close=false for shorter collection, "
-            "or use the HTTP endpoint with offset/limit for paginated access.",
+            "hint": "Lower message_limit, raise message_offset, keep summarize=True, "
+            "or narrow the response with python_transform.",
         }
 
     return result
@@ -586,6 +811,7 @@ async def _call_addon_api(
     port: int | None = None,
     offset: int = 0,
     limit: int | None = None,
+    python_transform: str | None = None,
 ) -> dict[str, Any]:
     """Call an add-on's web API through Home Assistant's Ingress proxy.
 
@@ -599,6 +825,10 @@ async def _call_addon_api(
         port: Override port to connect to (e.g., direct access port instead of ingress port)
         offset: Skip this many items in array responses (default 0)
         limit: Return at most this many items from array responses
+        python_transform: Optional sandboxed Python expression applied to the
+            parsed response body. The variable ``response`` is bound to
+            ``dict | list | str`` depending on content-type. Transform runs
+            after offset/limit slicing.
 
     Returns:
         Dictionary with response data, status code, and content type.
@@ -756,6 +986,13 @@ async def _call_addon_api(
             "returned": len(response_data),
         }
 
+    # 8a. python_transform (optional) — runs after slicing, before size cap,
+    # so an agent can narrow a large response down under the limit.
+    transformed = False
+    if python_transform is not None:
+        response_data = _apply_response_transform(response_data, python_transform)
+        transformed = True
+
     # 9. Truncate large responses
     truncated = False
     if isinstance(response_data, str) and len(response_data) > _MAX_RESPONSE_SIZE:
@@ -814,6 +1051,9 @@ async def _call_addon_api(
     if pagination_meta:
         result["pagination"] = pagination_meta
 
+    if transformed:
+        result["transformed"] = True
+
     if truncated:
         result["truncated"] = True
         result["note"] = (
@@ -1046,6 +1286,44 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
                 default=True,
             ),
         ] = True,
+        message_limit: Annotated[
+            int | None,
+            Field(
+                description="Proxy mode only. WebSocket: cap on messages collected from the wire, "
+                "bounded by an internal safety ceiling. None = collect up to the ceiling. "
+                "Lower to save tokens on noisy streams (e.g., message_limit=50 for a quick health check).",
+                default=None,
+            ),
+        ] = None,
+        message_offset: Annotated[
+            int,
+            Field(
+                description="Proxy mode only. WebSocket: drop this many messages from the start of the "
+                "collected list before returning. Useful for paginating past known-noisy headers. Default: 0.",
+                default=0,
+            ),
+        ] = 0,
+        summarize: Annotated[
+            bool,
+            Field(
+                description="Proxy mode only. WebSocket: when True (default), collapse runs of "
+                "non-signal messages (typically YAML config dumps) into short elision markers. "
+                "Set to False to return the raw stream.",
+                default=True,
+            ),
+        ] = True,
+        python_transform: Annotated[
+            str | None,
+            Field(
+                description="Proxy mode only. Sandboxed Python expression that post-processes the response. "
+                "Variable `response` is exposed — a list[dict | str] for WebSocket (parsed JSON or raw text), "
+                "or dict/list/str for HTTP (parsed body). Supports in-place mutation "
+                "(response.append(...)) or reassignment (response = [...]). "
+                "Example: response = [m for m in response if 'ERROR' in str(m)]. "
+                "Post-processing only — does not provide optimistic-locking write semantics.",
+                default=None,
+            ),
+        ] = None,
         options: Annotated[
             dict[str, Any] | None,
             Field(
@@ -1095,6 +1373,23 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         Sends requests directly to the add-on container's own web API via HTTP or WebSocket.
         Use ha_get_addon(slug="...") to discover available ports and endpoints.
 
+        **Response shaping (proxy mode):**
+        - WebSocket streams can be noisy (ESPHome /validate often emits hundreds of
+          config-dump lines). By default, `summarize=True` collapses long runs of
+          non-signal messages into short elision markers; INFO/WARNING/ERROR/exit
+          lines always pass through. Pagination via `message_offset` / `message_limit`
+          works on the raw collected list before summarize runs.
+        - `python_transform` applies a sandboxed Python expression as a final
+          post-processing step in both HTTP and WebSocket modes. The variable
+          `response` is bound to:
+            * WebSocket: `list[dict | str]` — parsed JSON messages are dicts,
+              undecodable frames stay as ANSI-stripped strings. Elision markers
+              appear as `{"elided": N, "note": "..."}` dicts when summarize ran.
+            * HTTP: `dict | list | str` — whichever the content-type produced.
+          Transforms may mutate in place (response.append(...), del response[k])
+          or reassign (response = [...]). This is post-processing only — it does
+          NOT provide optimistic-locking or write-back semantics.
+
         **WARNING:** Setting boot="auto"/"manual" will fail for add-ons whose Supervisor
         metadata locks the boot mode. The Supervisor returns an error in this case.
 
@@ -1110,6 +1405,9 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
         - Call HTTP API: ha_manage_addon(slug="...", path="/api/events")
         - Direct port: ha_manage_addon(slug="...", path="/flows", port=1880)
         - WebSocket: ha_manage_addon(slug="...", path="/validate", port=6052, websocket=True, body={"type": "spawn", "configuration": "device.yaml"})
+        - Quick WS health check (50 msgs, raw): ha_manage_addon(slug="...", path="/logs", websocket=True, message_limit=50, summarize=False)
+        - Filter WS errors only: ha_manage_addon(slug="...", path="/validate", websocket=True, python_transform="response = [m for m in response if 'ERROR' in str(m) or 'WARN' in str(m)]")
+        - HTTP subset: ha_manage_addon(slug="...", path="/flows", python_transform="response = [f['id'] for f in response]")
         """
         # Build config payload from provided config parameters
         config_data: dict[str, Any] = {}
@@ -1169,6 +1467,18 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
                 proxy_overrides.append(("websocket", "websocket=True"))
             if not wait_for_close:
                 proxy_overrides.append(("wait_for_close", "wait_for_close=False"))
+            if message_limit is not None:
+                proxy_overrides.append(
+                    ("message_limit", f"message_limit={message_limit}")
+                )
+            if message_offset != 0:
+                proxy_overrides.append(
+                    ("message_offset", f"message_offset={message_offset}")
+                )
+            if not summarize:
+                proxy_overrides.append(("summarize", "summarize=False"))
+            if python_transform is not None:
+                proxy_overrides.append(("python_transform", "python_transform"))
             if proxy_overrides:
                 raise_tool_error(
                     create_validation_error(
@@ -1278,6 +1588,10 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
                 debug=debug,
                 port=port,
                 wait_for_close=wait_for_close,
+                message_limit=message_limit,
+                message_offset=message_offset,
+                summarize=summarize,
+                python_transform=python_transform,
             )
             if not result.get("success"):
                 raise_tool_error(result)
@@ -1293,6 +1607,17 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
                 )
             )
 
+        # HTTP mode does not use WebSocket-specific params. Reject explicit
+        # use so misroutes surface immediately rather than silently ignoring.
+        if message_limit is not None or message_offset != 0 or not summarize:
+            raise_tool_error(
+                create_validation_error(
+                    "message_limit / message_offset / summarize apply only to "
+                    "WebSocket mode. Set websocket=True or remove them.",
+                    parameter="message_limit",
+                )
+            )
+
         result = await _call_addon_api(
             client=client,
             slug=slug,
@@ -1303,6 +1628,7 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs: Any) -
             port=port,
             offset=offset,
             limit=limit,
+            python_transform=python_transform,
         )
         if not result.get("success"):
             raise_tool_error(result)