mcp(feat[_utils]): Add _apply_filters() helper for QueryList filtering

why: MCP list tools need to expose libtmux's QueryList filtering via
an optional dict parameter, requiring a bridge between MCP dict params
and QueryList.filter(**kwargs).
what:
- Add _apply_filters() that validates operator keys against LOOKUP_NAME_MAP
- Raise ToolError with valid operators list on invalid lookup operator
- Short-circuit to direct serialization when filters is None/empty
- Add 6 parametrized tests: none, empty, exact, no_match, invalid_op, contains

Author: tony

src/libtmux/mcp/_utils.py

@@ -12,6 +12,7 @@
 import typing as t
 
 from libtmux import exc
+from libtmux._internal.query_list import LOOKUP_NAME_MAP
 from libtmux.server import Server
 
 if t.TYPE_CHECKING:
@@ -273,6 +274,53 @@ def _resolve_pane(
     return panes[0]
 
 
+def _apply_filters(
+    items: t.Any,
+    filters: dict[str, str] | None,
+    serializer: t.Callable[..., dict[str, t.Any]],
+) -> list[dict[str, t.Any]]:
+    """Apply QueryList filters and serialize results.
+
+    Parameters
+    ----------
+    items : QueryList
+        The QueryList of tmux objects to filter.
+    filters : dict or None
+        Django-style filter kwargs (e.g. ``{"session_name__contains": "dev"}``).
+        If None or empty, all items are returned.
+    serializer : callable
+        Serializer function to convert each item to a dict.
+
+    Returns
+    -------
+    list[dict]
+        Serialized list of matching items.
+
+    Raises
+    ------
+    ToolError
+        If a filter key uses an invalid lookup operator.
+    """
+    if not filters:
+        return [serializer(item) for item in items]
+
+    from fastmcp.exceptions import ToolError
+
+    valid_ops = sorted(LOOKUP_NAME_MAP.keys())
+    for key in filters:
+        if "__" in key:
+            _field, 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 ToolError(msg)
+
+    filtered = items.filter(**filters)
+    return [serializer(item) for item in filtered]
+
+
 def _serialize_session(session: Session) -> dict[str, t.Any]:
     """Serialize a Session to a JSON-compatible dict.
 

tests/mcp/test_utils.py

@@ -5,9 +5,11 @@
 import typing as t
 
 import pytest
+from fastmcp.exceptions import ToolError
 
 from libtmux import exc
 from libtmux.mcp._utils import (
+    _apply_filters,
     _get_server,
     _invalidate_server,
     _resolve_pane,
@@ -144,3 +146,102 @@ def test_invalidate_server() -> None:
     assert len(_server_cache) == 1
     _invalidate_server(socket_name="test_inv")
     assert len(_server_cache) == 0
+
+
+class ApplyFiltersFixture(t.NamedTuple):
+    """Test fixture for _apply_filters."""
+
+    test_id: str
+    filters: dict[str, str] | None
+    expected_count: int | None  # None = don't check exact count
+    expect_error: bool
+    error_match: str | None
+
+
+APPLY_FILTERS_FIXTURES: list[ApplyFiltersFixture] = [
+    ApplyFiltersFixture(
+        test_id="none_returns_all",
+        filters=None,
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
+    ApplyFiltersFixture(
+        test_id="empty_dict_returns_all",
+        filters={},
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
+    ApplyFiltersFixture(
+        test_id="exact_match",
+        filters={"session_name": "<session_name>"},
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+    ApplyFiltersFixture(
+        test_id="no_match_returns_empty",
+        filters={"session_name": "nonexistent_xyz_999"},
+        expected_count=0,
+        expect_error=False,
+        error_match=None,
+    ),
+    ApplyFiltersFixture(
+        test_id="invalid_operator",
+        filters={"session_name__badop": "test"},
+        expected_count=None,
+        expect_error=True,
+        error_match="Invalid filter operator",
+    ),
+    ApplyFiltersFixture(
+        test_id="contains_operator",
+        filters={"session_name__contains": "<partial>"},
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    ApplyFiltersFixture._fields,
+    APPLY_FILTERS_FIXTURES,
+    ids=[f.test_id for f in APPLY_FILTERS_FIXTURES],
+)
+def test_apply_filters(
+    mcp_server: Server,
+    mcp_session: Session,
+    test_id: str,
+    filters: dict[str, str] | None,
+    expected_count: int | None,
+    expect_error: bool,
+    error_match: str | None,
+) -> None:
+    """_apply_filters bridges dict params to QueryList.filter()."""
+    # Substitute placeholders with real session name
+    if filters is not None:
+        session_name = mcp_session.session_name
+        assert session_name is not None
+        resolved: dict[str, str] = {}
+        for k, v in filters.items():
+            if v == "<session_name>":
+                resolved[k] = session_name
+            elif v == "<partial>":
+                resolved[k] = session_name[:4]
+            else:
+                resolved[k] = v
+        filters = resolved
+
+    sessions = mcp_server.sessions
+
+    if expect_error:
+        with pytest.raises(ToolError, match=error_match):
+            _apply_filters(sessions, filters, _serialize_session)
+    else:
+        result = _apply_filters(sessions, filters, _serialize_session)
+        assert isinstance(result, list)
+        if expected_count is not None:
+            assert len(result) == expected_count
+        else:
+            assert len(result) >= 1