ha-mcp-dev 7.14.2.dev2129__tar.gz → 7.14.2.dev2131__tar.gz

{ha_mcp_dev-7.14.2.dev2129/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.14.2.dev2131}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.14.2.dev2129
+Version: 7.14.2.dev2131
 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.14.2.dev2129 → ha_mcp_dev-7.14.2.dev2131}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.14.2.dev2129"
+version = "7.14.2.dev2131"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.14.2.dev2129 → ha_mcp_dev-7.14.2.dev2131}/src/ha_mcp/tools/tools_yaml_read.py

@@ -17,6 +17,7 @@ back door.
 
 import asyncio
 import logging
+import re
 from typing import Annotated, Any
 
 from fastmcp.exceptions import ToolError
@@ -43,10 +44,46 @@ logger = logging.getLogger(__name__)
 # fnmatches on the file name); this only decides single-file vs. glob.
 _GLOB_METACHARS = ("*", "?", "[")
 
+# The metacharacters that match their own literal names, and so are pattern
+# syntax rather than a plausible spelling of a file name the caller means
+# exactly. A bracket class is the ambiguous one and is deliberately absent.
+_PATTERN_ONLY_METACHARS = ("*", "?")
 
-def _has_glob(file: str) -> bool:
-    """True if ``file`` carries an fnmatch wildcard and must be expanded."""
-    return any(char in file for char in _GLOB_METACHARS)
+# Wraps each metacharacter in a bracket class so fnmatch reads it literally.
+# Deliberately not glob.escape: it splits a drive off first and returns that
+# part UNESCAPED, and the split is ntpath on a Windows-hosted server - where a
+# name like \\weird[a].yaml is taken for a drive in its entirety and comes back
+# with its bracket intact. The one host-dependent step in a path that is
+# otherwise POSIX and config-relative.
+_METACHAR_RE = re.compile(r"([*?\[])")
+
+
+def _has_glob(name: str) -> bool:
+    """True if ``name`` carries an fnmatch wildcard and must be expanded.
+
+    Takes the file name rather than the whole path: the component resolves
+    directories literally, so a metacharacter in a folder name belongs to that
+    folder's name and is not a pattern.
+    """
+    return any(char in name for char in _GLOB_METACHARS)
+
+
+def _names_a_file(pattern: str) -> bool:
+    """True if the request can be read as naming one file rather than a class.
+
+    ``*`` and ``?`` are pattern syntax: they match their own literal names, so
+    a caller who wrote one wrote a pattern. A bracket class alone is ambiguous,
+    since such a name is legal on the filesystem and cannot match itself.
+
+    One predicate for two decisions that must not diverge - whether a path the
+    literal lookup returned counts as explicitly named, and whether the absence
+    of such a path is worth a warning. Honouring it in the warning alone would
+    leave a file genuinely called ``[ab]*.yaml`` strict, so one failed read of
+    it would discard every match the pattern half had already found: the shape
+    removed for ``*.yaml`` when provenance moved into the resolver, reachable
+    again through the other lookup.
+    """
+    return not any(char in pattern for char in _PATTERN_ONLY_METACHARS)
 
 
 def _call_failed(service: str, context: dict[str, Any]) -> None:
@@ -83,16 +120,18 @@ def _failure_text(payload: dict[str, Any]) -> str:
 
 
 def _parse_error_result(
-    target: str, yaml_path: str, parse_error: str, *, is_glob: bool
+    target: str, yaml_path: str, parse_error: str, *, is_expanded: bool
 ) -> tuple[None, str]:
-    """Decide a file the component could not parse: raise for a single target.
-
-    A single explicit target has no siblings to salvage, so a parse failure
-    raises rather than soft-degrading to a warning that reads as "key absent".
-    Under a glob it stays a per-file warning so one broken file does not sink
-    the whole search.
+    """Decide a file the component could not parse: raise for a named target.
+
+    The explicitly named target raises rather than soft-degrading to a warning
+    that reads as "key absent" - it raises even when expansion turned up
+    siblings alongside it, discarding their results, because a named file that
+    cannot be parsed is the caller's question, not a stray unreadable neighbour.
+    An expanded target stays a per-file warning so one broken file does not
+    sink the whole search.
     """
-    if not is_glob:
+    if not is_expanded:
         raise_tool_error(
             create_error_response(
                 ErrorCode.CONFIG_INVALID,
@@ -104,12 +143,39 @@ def _parse_error_result(
     return None, f"{target} was not searched: {parse_error}."
 
 
+def _read_exception_result(
+    target: str, error: BaseException, *, is_expanded: bool
+) -> tuple[None, str]:
+    """Decide a read that blew up outright.
+
+    An expanded target degrades to a warning so one unreadable file cannot sink
+    the search; the explicitly named target raises, as it does for every other
+    failure class in :func:`_evaluate_read`. The error is re-raised as it came
+    rather than wrapped, so the tool's own handler classifies it by type - the
+    other classes have no live exception to preserve and build a structured
+    :class:`ToolError` instead.
+
+    Anything that is not an ``Exception`` propagates whatever the target's
+    provenance - this is the one failure class here that raises for an expanded
+    target too. Cancellation and shutdown are not one file being unreadable,
+    and absorbing them into a warning next to ``success: true`` would report a
+    search that was called off as one that ran and found nothing. The per-item
+    fan-outs in ``tools_entities`` and ``tools_search`` draw the same line.
+
+    ``str()`` is empty on a bare ``TimeoutError()``, so the class name stands
+    in - a warning reading "was not searched: ." names no reason at all.
+    """
+    if not is_expanded or not isinstance(error, Exception):
+        raise error
+    return None, f"{target} was not searched: {str(error) or type(error).__name__}."
+
+
 def _evaluate_read(
     response: Any,
     target: str,
     yaml_path: str,
     *,
-    is_glob: bool,
+    is_expanded: bool,
     include_content: bool,
     include_parsed: bool,
 ) -> tuple[dict[str, Any] | None, str | None]:
@@ -117,37 +183,37 @@ def _evaluate_read(
 
     Three outcomes, in the order they are decided:
 
-    * **warning** — the file could not be searched at all. Under a glob that
+    * **warning** — the file could not be searched at all. An expanded target
       must not sink the whole search and discard the matches already found:
-      the glob is not restricted to ``*.yaml``, so ``packages/*`` can turn up
+      expansion is not restricted to ``*.yaml``, so ``packages/*`` can turn up
       a README the component refuses to read, and a permission-denied or
       non-UTF-8 ``.yaml`` lands here too. A syntactically broken file is the
       same class — reporting it as "key absent" would claim a file was
-      inspected when it never was. A single explicit target has no siblings
-      to salvage, so it raises instead.
+      inspected when it never was. The explicitly named target raises
+      instead, even when expansion turned up siblings alongside it.
     * **neither** — the file parsed and simply has no such key. The real
       non-match, and the whole point of a glob search.
     * **match** — the key is there.
     """
-    # Only reachable under a glob: with a single target return_exceptions is
-    # False, so gather itself raised.
     if isinstance(response, BaseException):
-        return None, f"{target} was not searched: {response}."
+        return _read_exception_result(target, response, is_expanded=is_expanded)
 
     if not isinstance(response, dict):
-        if is_glob:
+        if is_expanded:
             return None, f"{target} was not searched: unexpected read_file response."
         _call_failed("read_file", {"file": target, "yaml_path": yaml_path})
     unwrapped = unwrap_service_response(response)
 
     if not unwrapped.get("success", True):
-        if not is_glob:
+        if not is_expanded:
             raise_tool_error(unwrapped)
         return None, f"{target} was not searched: {_failure_text(unwrapped)}."
 
     parse_error = unwrapped.get("parse_error")
     if parse_error:
-        return _parse_error_result(target, yaml_path, str(parse_error), is_glob=is_glob)
+        return _parse_error_result(
+            target, yaml_path, str(parse_error), is_expanded=is_expanded
+        )
 
     if unwrapped.get("subtree") is None:
         return None, None
@@ -160,18 +226,10 @@ def _evaluate_read(
     return match, None
 
 
-async def _resolve_target_files(client: Any, file: str) -> list[str]:
-    """Expand ``file`` into the concrete config-relative paths to read.
-
-    A plain path is returned as-is (the read itself reports a missing file). A
-    glob is expanded through the component's ``list_files``, which matches the
-    file name only — so ``packages/*.yaml`` covers one directory level, not a
-    nested tree.
-    """
-    if not _has_glob(file):
-        return [file]
-
-    directory, _, pattern = file.rpartition("/")
+async def _list_files_matching(
+    client: Any, file: str, directory: str, pattern: str
+) -> list[str]:
+    """Return the non-directory paths in ``directory`` matching ``pattern``."""
     unwrapped = _unwrap_or_raise(
         await call_mcp_tools_service(
             client,
@@ -192,6 +250,113 @@ async def _resolve_target_files(client: Any, file: str) -> list[str]:
     )
 
 
+def _absent_literal_warnings(
+    file: str, pattern: str, *, literal_found: bool, target_count: int
+) -> list[str]:
+    """Say so when nothing is literally named the way a bracketed request was.
+
+    Silence is what the caller reads as "your file was searched": the siblings
+    the class matched arrive as ``files_searched`` with nothing marking the
+    named file as never opened.
+
+    Two cases stay silent. A literal that was found needs no warning, and
+    neither does a request that :func:`_names_a_file` rejects - nobody named a
+    file, so nothing is missing. The literal lookup still runs for those, since
+    its results are merged as ordinary expansion matches; only the complaint is
+    dropped.
+    """
+    if literal_found or not _names_a_file(pattern):
+        return []
+    if not target_count:
+        # Phrased for the degenerate case rather than reporting "the 0 file(s)
+        # matching it as a pattern", which reads as a search that happened.
+        return [
+            f"No file is literally named {file}, and nothing matched it as a "
+            f"pattern either."
+        ]
+    return [
+        f"No file is literally named {file}; searched the {target_count} "
+        f"file(s) matching it as a pattern."
+    ]
+
+
+async def _resolve_target_files(
+    client: Any, file: str
+) -> tuple[list[tuple[str, bool]], list[str]]:
+    """Expand ``file`` into ``(path, is_expanded)`` pairs plus any warnings.
+
+    ``is_expanded`` records where the path came from, and it is decided here
+    because only here is it known: a path produced by the pattern lookup is an
+    expansion, while the requested path itself, and what the escaped-literal
+    lookup returns for a request :func:`_names_a_file` accepts, were named
+    explicitly. Recovering that downstream by comparing the path against the
+    requested string would be wrong for ``*`` and ``?``, which match their own
+    literal names - a file genuinely called ``*.yaml`` would then be mistaken
+    for the name the caller typed and its read failure would sink the whole
+    search.
+
+    A plain path is returned as-is (the read itself reports a missing file). A
+    glob is expanded through the component's ``list_files``, which matches the
+    file name only, so ``packages/*.yaml`` covers one directory level rather
+    than a nested tree. Only the name is inspected for metacharacters: the
+    component resolves the directory literally, so ``pack[a]ges/svc.yaml``
+    names one file and is read as one rather than expanded.
+
+    A bracketed name is ambiguous: ``packages/svc[a].yaml`` is both a valid
+    pattern and a valid filename, and a closed bracket class is the one
+    metacharacter form whose pattern cannot match its own name (``fnmatch``
+    reads ``[a]`` as the single character ``a``, while ``*`` and ``?`` do match
+    themselves). Such a name is therefore looked up twice, as the pattern and
+    as the escaped literal, and the results are merged: the pattern alone would
+    report ``files_searched: 0`` for a file that exists, and the literal alone
+    would drop the siblings a deliberate class like ``svc[12].yaml`` is meant
+    to find. Both lookups run because a sibling that satisfies the class would
+    otherwise mask the file the caller named exactly. Only bracketed names pay
+    the second lookup, and it is issued concurrently with the first rather than
+    after it. The component likewise treats package folder names carrying
+    metacharacters as literal names (#1854).
+
+    The guard is any bracket, not a closed class: an unclosed or empty bracket
+    is literal to ``fnmatch`` and so matches its own name, which means both
+    lookups return it and the deduplication below is what keeps it a single
+    target. A listing failure on either lookup raises rather than degrading -
+    the directory is the same one in both calls, so a failure there is a broken
+    request, not one unreadable file among several.
+
+    When the literal lookup comes back empty the caller named a file that does
+    not exist, and the pattern's siblings would otherwise be reported as if the
+    named file had been searched; :func:`_absent_literal_warnings` decides what
+    to say about that.
+    """
+    directory, _, pattern = file.rpartition("/")
+    if not _has_glob(pattern):
+        return [(file, False)], []
+
+    if "[" not in pattern:
+        matched = await _list_files_matching(client, file, directory, pattern)
+        return [(target, True) for target in matched], []
+
+    # The two lookups are independent, so run them together rather than paying
+    # two sequential round-trips; the reads below fan out for the same reason.
+    matched, literal = await asyncio.gather(
+        _list_files_matching(client, file, directory, pattern),
+        _list_files_matching(
+            client, file, directory, _METACHAR_RE.sub(r"[\1]", pattern)
+        ),
+    )
+    # Both lookups always contribute targets; only whether a literal hit counts
+    # as *named* depends on the request. Under a pattern it is merged as an
+    # ordinary expansion match, so nobody named it and a bad read stays a
+    # warning.
+    literal_paths = set(literal)
+    named = literal_paths if _names_a_file(pattern) else set()
+    targets = sorted(set(matched) | literal_paths)
+    warnings = _absent_literal_warnings(
+        file, pattern, literal_found=bool(named), target_count=len(targets)
+    )
+    return [(target, target not in named) for target in targets], warnings
+
+
 class YamlReadTools:
     def __init__(self, client: Any) -> None:
         self._client = client
@@ -273,15 +438,18 @@ class YamlReadTools:
         try:
             await _assert_mcp_tools_available(self._client)
 
-            is_glob = _has_glob(file)
-            targets = await _resolve_target_files(self._client, file)
+            # Strictness is a property of each target, not of the request, so
+            # the resolver reports which targets were named rather than expanded.
+            targets, resolve_warnings = await _resolve_target_files(self._client, file)
 
             extra: dict[str, Any] = {"include_parsed": True} if include_parsed else {}
             # The reads are independent, so fan them out rather than paying N
             # sequential round-trips to HA — a packages glob is routinely 10+
             # files. gather preserves order, so matches stay sorted by file.
-            # Under a glob a single read blowing up must not sink its siblings,
-            # so exceptions come back as values to be warned about below.
+            # An expanded target blowing up must not sink the search, so every
+            # exception comes back as a value; whether it degrades to a warning
+            # or is re-raised is then decided per target, like every other
+            # failure class.
             responses = await asyncio.gather(
                 *(
                     call_mcp_tools_service(
@@ -289,24 +457,26 @@ class YamlReadTools:
                         "read_file",
                         {"path": target, "yaml_path": yaml_path, **extra},
                     )
-                    for target in targets
+                    for target, _ in targets
                 ),
-                return_exceptions=is_glob,
+                return_exceptions=True,
             )
 
             matches: list[dict[str, Any]] = []
-            warnings: list[str] = []
-            for target, response in zip(targets, responses, strict=True):
+            warnings: list[str] = list(resolve_warnings)
+            files_unreadable = 0
+            for (target, is_expanded), response in zip(targets, responses, strict=True):
                 match, warning = _evaluate_read(
                     response,
                     target,
                     yaml_path,
-                    is_glob=is_glob,
+                    is_expanded=is_expanded,
                     include_content=include_content,
                     include_parsed=include_parsed,
                 )
                 if warning:
                     warnings.append(warning)
+                    files_unreadable += 1
                 elif match:
                     matches.append(match)
 
@@ -318,6 +488,10 @@ class YamlReadTools:
                 # Separates "the glob matched no files" from "no file defines
                 # the key" — same empty matches[], different fix.
                 "files_searched": len(targets),
+                # Keeps `count: 0` beside a non-zero files_searched from reading
+                # as "searched them, found nothing". Counted in the loop, not as
+                # len(warnings): those also carry resolver-level entries.
+                "files_unreadable": files_unreadable,
             }
             if warnings:
                 result["warnings"] = warnings

{ha_mcp_dev-7.14.2.dev2129 → ha_mcp_dev-7.14.2.dev2131/src/ha_mcp_dev.egg-info}/PKG-INFO

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