Mcp(fix[filters]): Reject unknown filter fields

`list_sessions`, `list_windows` and `list_panes` validated the operator
half of a Django-style filter key and never the field half, so
`filters={"nosuch_field__contains": "x"}` returned `[]`. A key with no
`__` at all was not checked by anything — the loop only entered its
branch when one was present, and bound the field to `_field`, the name
that means "deliberately unused".

libtmux's `QueryList` resolves a key by attribute traversal and treats
a miss as "no match", so a misspelled field silently filtered every row
out and the empty result was indistinguishable from a real one. That is
the worst shape in this class: not an error the agent can react to, but
a confident wrong answer shaped like a right one.

Field names are now checked against the object being filtered, with
near-misses suggested, mirroring the operator error that was already
good. Validation covers only the leading segment, so nested traversal
like `active_window__window_name__contains` keeps working — the check
rejects what the type cannot have rather than whitelisting.

The type is a parameter rather than read off the first item, so an
empty list still validates. That is exactly when a typo most needs
reporting.

Author: tony

CHANGES

@@ -8,6 +8,28 @@ _Notes on upcoming releases will be added here_
 
 ### What's new
 
+#### A typo in a filter field is an error, not an empty list
+
+`list_sessions`, `list_windows` and `list_panes` validated the *operator*
+half of a Django-style filter key and never the *field* half, so
+`filters={"nosuch_field__contains": "x"}` returned `[]`. A key with no
+`__` at all, like `{"totally_bogus": "zzz"}`, was not checked by
+anything. libtmux's `QueryList` resolves a filter key by attribute
+traversal and treats a miss as "no match", so a misspelled field
+silently filtered every row out and the empty result was
+indistinguishable from a genuine one.
+
+Field names are now checked against the object being filtered, with
+near-misses suggested:
+
+```
+Unknown filter field 'session_nme' in 'session_nme__contains'.
+Did you mean: session_name, session_marked, session_id?
+```
+
+Validation covers only the leading segment of a key, so nested
+traversal such as `active_window__window_name__contains` keeps working.
+
 #### A pane that dies mid-wait reports the death, not a parse crash
 
 Killing a pane while `wait_for_text` was waiting on it surfaced

src/libtmux_mcp/_utils.py

@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import dataclasses
+import difflib
 import functools
 import json
 import logging
@@ -841,10 +842,29 @@ def _coerce_dict_arg(
     return value
 
 
+@functools.cache
+def _filterable_fields(obj_type: type) -> frozenset[str]:
+    """Attribute names a filter key may begin with.
+
+    ``QueryList`` resolves a key by ``getattr`` traversal and treats a
+    miss as "no match", so an unknown field silently filters every row
+    out and an empty result is indistinguishable from a typo.
+
+    Deliberately permissive: it rejects names the type cannot have and
+    accepts everything else, because ``__`` traversal into a nested
+    object is legitimate and only the first segment is checkable here.
+    """
+    names = {name for name in dir(obj_type) if not name.startswith("_")}
+    if dataclasses.is_dataclass(obj_type):
+        names |= {field.name for field in dataclasses.fields(obj_type)}
+    return frozenset(names)
+
+
 def _apply_filters(
     items: t.Any,
     filters: dict[str, str] | str | None,
     serializer: t.Callable[..., M],
+    obj_type: type,
 ) -> list[M]:
     """Apply QueryList filters and serialize results.
 
@@ -858,6 +878,11 @@ def _apply_filters(
         If None or empty, all items are returned.
     serializer : callable
         Serializer function to convert each item to a model.
+    obj_type : type
+        libtmux class of the filtered items, used to validate filter
+        field names. Taken as a parameter rather than read off the
+        first item so an empty list still validates -- an empty result
+        is exactly when a typo most needs reporting.
 
     Returns
     -------
@@ -867,23 +892,39 @@ def _apply_filters(
     Raises
     ------
     ExpectedToolError
-        If a filter key uses an invalid lookup operator.
+        If a filter key uses an invalid lookup operator or names a
+        field the object cannot have.
     """
     coerced = _coerce_dict_arg("filters", filters)
     if not coerced:
         return [serializer(item) for item in items]
     filters = coerced
 
     valid_ops = sorted(LOOKUP_NAME_MAP.keys())
+    allowed_fields = _filterable_fields(obj_type)
     for key in filters:
+        field_path = key
         if "__" in key:
-            _field, op = key.rsplit("__", 1)
+            lhs, op = key.rsplit("__", 1)
             if op not in LOOKUP_NAME_MAP:
                 msg = (
                     f"Invalid filter operator '{op}' in '{key}'. "
                     f"Valid operators: {', '.join(valid_ops)}"
                 )
                 raise ExpectedToolError(msg)
+            field_path = lhs
+
+        # Only the leading segment is checkable; the rest may traverse
+        # into a nested object.
+        field = field_path.split("__", 1)[0]
+        if field not in allowed_fields:
+            msg = f"Unknown filter field '{field}' in '{key}'."
+            close = difflib.get_close_matches(field, sorted(allowed_fields), n=3)
+            if close:
+                msg += f" Did you mean: {', '.join(close)}?"
+            else:
+                msg += " Call this tool without filters to see available fields."
+            raise ExpectedToolError(msg)
 
     filtered = items.filter(**filters)
     return [serializer(item) for item in filtered]

src/libtmux_mcp/tools/server_tools.py

@@ -10,6 +10,7 @@
 import typing as t
 
 from fastmcp.exceptions import ToolError
+from libtmux.session import Session
 
 from libtmux_mcp._history import _prepare_spawn_environment
 from libtmux_mcp._utils import (
@@ -63,7 +64,7 @@ def list_sessions(
     """
     server = _get_server(socket_name=socket_name)
     sessions = server.sessions
-    return _apply_filters(sessions, filters, _serialize_session)
+    return _apply_filters(sessions, filters, _serialize_session, Session)
 
 
 @handle_tool_errors

src/libtmux_mcp/tools/session_tools.py

@@ -5,6 +5,7 @@
 import typing as t
 
 from libtmux.constants import WindowDirection
+from libtmux.window import Window
 
 from libtmux_mcp._history import _prepare_spawn_environment
 from libtmux_mcp._utils import (
@@ -72,7 +73,7 @@ def list_windows(
         windows = session.windows
     else:
         windows = server.windows
-    return _apply_filters(windows, filters, _serialize_window)
+    return _apply_filters(windows, filters, _serialize_window, Window)
 
 
 # get_session_info completes the core-tmux-hierarchy symmetry alongside

src/libtmux_mcp/tools/window_tools.py

@@ -5,6 +5,7 @@
 import typing as t
 
 from libtmux.constants import PaneDirection
+from libtmux.pane import Pane
 
 from libtmux_mcp._history import _prepare_spawn_environment
 from libtmux_mcp._utils import (
@@ -98,7 +99,7 @@ def list_panes(
         panes = session.panes
     else:
         panes = server.panes
-    return _apply_filters(panes, filters, _serialize_pane)
+    return _apply_filters(panes, filters, _serialize_pane, Pane)
 
 
 # get_window_info completes the core-tmux-hierarchy symmetry of get_*_info

tests/test_utils.py

@@ -8,6 +8,7 @@
 import pytest
 from fastmcp.exceptions import ToolError
 from libtmux import exc
+from libtmux.session import Session
 
 from libtmux_mcp._utils import (
     ANNOTATIONS_CREATE,
@@ -34,7 +35,6 @@
 if t.TYPE_CHECKING:
     from libtmux.pane import Pane
     from libtmux.server import Server
-    from libtmux.session import Session
     from libtmux.window import Window
 
 
@@ -212,6 +212,36 @@ class ApplyFiltersFixture(t.NamedTuple):
         expect_error=True,
         error_match="Invalid filter operator",
     ),
+    # A typo'd FIELD used to return [] rather than erroring, so an empty
+    # result was indistinguishable from "nothing matched".
+    ApplyFiltersFixture(
+        test_id="unknown_field_with_valid_operator_errors",
+        filters={"nosuch_field__contains": "x"},
+        expected_count=None,
+        expect_error=True,
+        error_match="Unknown filter field 'nosuch_field'",
+    ),
+    ApplyFiltersFixture(
+        test_id="unknown_field_without_operator_errors",
+        filters={"totally_bogus": "zzz"},
+        expected_count=None,
+        expect_error=True,
+        error_match="Unknown filter field 'totally_bogus'",
+    ),
+    ApplyFiltersFixture(
+        test_id="near_miss_field_suggests_alternatives",
+        filters={"session_nme__contains": "x"},
+        expected_count=None,
+        expect_error=True,
+        error_match="Did you mean: session_name",
+    ),
+    ApplyFiltersFixture(
+        test_id="nested_traversal_still_allowed",
+        filters={"active_window__window_name__contains": ""},
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
     ApplyFiltersFixture(
         test_id="contains_operator",
         filters={"session_name__contains": "<partial>"},
@@ -295,9 +325,9 @@ def test_apply_filters(
 
     if expect_error:
         with pytest.raises(ToolError, match=error_match):
-            _apply_filters(sessions, filters, _serialize_session)
+            _apply_filters(sessions, filters, _serialize_session, Session)
     else:
-        result = _apply_filters(sessions, filters, _serialize_session)
+        result = _apply_filters(sessions, filters, _serialize_session, Session)
         assert isinstance(result, list)
         if expected_count is not None:
             assert len(result) == expected_count