mcp(feat[list_tools]): Add filtering and scope broadening to list tools

why: LLM agents need to search across tmux objects without knowing the
exact hierarchy, and filter results using QueryList's 12 lookup operators.
what:
- Add optional filters param to list_sessions, list_windows, list_panes
- Broaden list_windows scope: omit session params to list all server windows
- Broaden list_panes scope: window > session > server fallback chain
- Add 9 parametrized tests for list_sessions filtering
- Add 7 parametrized tests for list_windows filtering + cross-session scope
- Add 7 parametrized tests for list_panes filtering + session/server scope

Author: tony

src/libtmux/mcp/tools/server_tools.py

@@ -6,6 +6,7 @@
 import typing as t
 
 from libtmux.mcp._utils import (
+    _apply_filters,
     _get_server,
     _invalidate_server,
     _serialize_session,
@@ -17,13 +18,18 @@
 
 
 @handle_tool_errors
-def list_sessions(socket_name: str | None = None) -> str:
+def list_sessions(
+    socket_name: str | None = None,
+    filters: dict[str, str] | None = None,
+) -> str:
     """List all tmux sessions.
 
     Parameters
     ----------
     socket_name : str, optional
         tmux socket name. Defaults to LIBTMUX_SOCKET env var.
+    filters : dict, optional
+        Django-style filters (e.g. ``{"session_name__contains": "dev"}``).
 
     Returns
     -------
@@ -32,7 +38,7 @@ def list_sessions(socket_name: str | None = None) -> str:
     """
     server = _get_server(socket_name=socket_name)
     sessions = server.sessions
-    return json.dumps([_serialize_session(s) for s in sessions])
+    return json.dumps(_apply_filters(sessions, filters, _serialize_session))
 
 
 @handle_tool_errors

src/libtmux/mcp/tools/session_tools.py

@@ -7,6 +7,7 @@
 
 from libtmux.constants import WindowDirection
 from libtmux.mcp._utils import (
+    _apply_filters,
     _get_server,
     _resolve_session,
     _serialize_session,
@@ -23,27 +24,36 @@ def list_windows(
     session_name: str | None = None,
     session_id: str | None = None,
     socket_name: str | None = None,
+    filters: dict[str, str] | None = None,
 ) -> str:
-    """List all windows in a tmux session.
+    """List windows in a tmux session, or all windows across sessions.
 
     Parameters
     ----------
     session_name : str, optional
-        Session name to look up.
+        Session name to look up. If omitted along with session_id,
+        returns windows from all sessions.
     session_id : str, optional
         Session ID (e.g. '$1') to look up.
     socket_name : str, optional
         tmux socket name. Defaults to LIBTMUX_SOCKET env var.
+    filters : dict, optional
+        Django-style filters (e.g. ``{"window_name__contains": "dev"}``).
 
     Returns
     -------
     str
         JSON array of window objects.
     """
     server = _get_server(socket_name=socket_name)
-    session = _resolve_session(server, session_name=session_name, session_id=session_id)
-    windows = session.windows
-    return json.dumps([_serialize_window(w) for w in windows])
+    if session_name is not None or session_id is not None:
+        session = _resolve_session(
+            server, session_name=session_name, session_id=session_id
+        )
+        windows = session.windows
+    else:
+        windows = server.windows
+    return json.dumps(_apply_filters(windows, filters, _serialize_window))
 
 
 @handle_tool_errors

src/libtmux/mcp/tools/window_tools.py

@@ -7,8 +7,10 @@
 
 from libtmux.constants import PaneDirection
 from libtmux.mcp._utils import (
+    _apply_filters,
     _get_server,
     _resolve_pane,
+    _resolve_session,
     _resolve_window,
     _serialize_pane,
     _serialize_window,
@@ -33,36 +35,50 @@ def list_panes(
     window_id: str | None = None,
     window_index: str | None = None,
     socket_name: str | None = None,
+    filters: dict[str, str] | None = None,
 ) -> str:
-    """List all panes in a tmux window.
+    """List panes in a tmux window, session, or across the entire server.
 
     Parameters
     ----------
     session_name : str, optional
-        Session name to resolve the window from.
+        Session name. If given without window params, lists all panes
+        in the session.
     session_id : str, optional
-        Session ID to resolve the window from.
+        Session ID. If given without window params, lists all panes
+        in the session.
     window_id : str, optional
-        Window ID (e.g. '@1').
+        Window ID (e.g. '@1'). Scopes to a single window.
     window_index : str, optional
-        Window index within the session.
+        Window index within the session. Scopes to a single window.
     socket_name : str, optional
         tmux socket name.
+    filters : dict, optional
+        Django-style filters (e.g. ``{"pane_current_command__contains": "vim"}``).
 
     Returns
     -------
     str
         JSON array of serialized pane objects.
     """
     server = _get_server(socket_name=socket_name)
-    window = _resolve_window(
-        server,
-        window_id=window_id,
-        window_index=window_index,
-        session_name=session_name,
-        session_id=session_id,
-    )
-    return json.dumps([_serialize_pane(p) for p in window.panes])
+    if window_id is not None or window_index is not None:
+        window = _resolve_window(
+            server,
+            window_id=window_id,
+            window_index=window_index,
+            session_name=session_name,
+            session_id=session_id,
+        )
+        panes = window.panes
+    elif session_name is not None or session_id is not None:
+        session = _resolve_session(
+            server, session_name=session_name, session_id=session_id
+        )
+        panes = session.panes
+    else:
+        panes = server.panes
+    return json.dumps(_apply_filters(panes, filters, _serialize_pane))
 
 
 @handle_tool_errors

tests/mcp/test_server_tools.py

@@ -69,6 +69,134 @@ def test_get_server_info(mcp_server: Server, mcp_session: Session) -> None:
     assert data["session_count"] >= 1
 
 
+class ListSessionsFilterFixture(t.NamedTuple):
+    """Test fixture for list_sessions with filters."""
+
+    test_id: str
+    filters: dict[str, str] | None
+    expected_count: int | None
+    expect_error: bool
+    error_match: str | None
+
+
+LIST_SESSIONS_FILTER_FIXTURES: list[ListSessionsFilterFixture] = [
+    ListSessionsFilterFixture(
+        test_id="no_filters",
+        filters=None,
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="exact_session_name",
+        filters={"session_name": "<session_name>"},
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="contains_operator",
+        filters={"session_name__contains": "<partial>"},
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="startswith_operator",
+        filters={"session_name__startswith": "<partial>"},
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="regex_operator",
+        filters={"session_name__regex": ".*"},
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="icontains_operator",
+        filters={"session_name__icontains": "<partial_upper>"},
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="no_match",
+        filters={"session_name": "nonexistent_xyz_999"},
+        expected_count=0,
+        expect_error=False,
+        error_match=None,
+    ),
+    ListSessionsFilterFixture(
+        test_id="invalid_operator",
+        filters={"session_name__badop": "test"},
+        expected_count=None,
+        expect_error=True,
+        error_match="Invalid filter operator",
+    ),
+    ListSessionsFilterFixture(
+        test_id="multiple_filters",
+        filters={"session_name__contains": "<partial>", "session_name__regex": ".*"},
+        expected_count=None,
+        expect_error=False,
+        error_match=None,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    ListSessionsFilterFixture._fields,
+    LIST_SESSIONS_FILTER_FIXTURES,
+    ids=[f.test_id for f in LIST_SESSIONS_FILTER_FIXTURES],
+)
+def test_list_sessions_with_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:
+    """list_sessions supports QueryList filtering."""
+    from fastmcp.exceptions import ToolError
+
+    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]
+            elif v == "<partial_upper>":
+                resolved[k] = session_name[:4].upper()
+            else:
+                resolved[k] = v
+        filters = resolved
+
+    if expect_error:
+        with pytest.raises(ToolError, match=error_match):
+            list_sessions(
+                socket_name=mcp_server.socket_name,
+                filters=filters,
+            )
+    else:
+        result = list_sessions(
+            socket_name=mcp_server.socket_name,
+            filters=filters,
+        )
+        data = json.loads(result)
+        assert isinstance(data, list)
+        if expected_count is not None:
+            assert len(data) == expected_count
+        else:
+            assert len(data) >= 1
+
+
 def test_kill_server(mcp_server: Server, mcp_session: Session) -> None:
     """kill_server kills the tmux server."""
     result = kill_server(socket_name=mcp_server.socket_name)