mcp(fix[_utils]): Accept filters as JSON string for MCP client compat

why: Multiple MCP clients (Cursor agent CLI, older Claude Code) cannot
serialize nested dict tool arguments — they either stringify the object
or fail with a JSON parse error before dispatching. This is a widely
reported bug across platforms.

refs:
- https://forum.cursor.com/t/145807 (Dec 2025)
- https://forum.cursor.com/t/132571
- https://forum.cursor.com/t/151180 (Feb 2026)
- makenotion/notion-mcp-server#176 (Jan 2026)
- anthropics/claude-code#5504

what:
- Widen _apply_filters() to accept str, parse via json.loads()
- Widen tool signatures to dict | str | None for JSON Schema compat
- Add 5 parametrized test cases for string coercion and error paths

Author: tony

src/libtmux/mcp/_utils.py

@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import functools
+import json
 import logging
 import os
 import typing as t
@@ -276,7 +277,7 @@ def _resolve_pane(
 
 def _apply_filters(
     items: t.Any,
-    filters: dict[str, str] | None,
+    filters: dict[str, str] | str | None,
     serializer: t.Callable[..., dict[str, t.Any]],
 ) -> list[dict[str, t.Any]]:
     """Apply QueryList filters and serialize results.
@@ -285,8 +286,9 @@ def _apply_filters(
     ----------
     items : QueryList
         The QueryList of tmux objects to filter.
-    filters : dict or None
-        Django-style filter kwargs (e.g. ``{"session_name__contains": "dev"}``).
+    filters : dict or str, optional
+        Django-style filters as a dict (e.g. ``{"session_name__contains": "dev"}``)
+        or as a JSON string. Some MCP clients require the string form.
         If None or empty, all items are returned.
     serializer : callable
         Serializer function to convert each item to a dict.
@@ -306,6 +308,20 @@ def _apply_filters(
 
     from fastmcp.exceptions import ToolError
 
+    # Workaround: Cursor and other MCP clients serialize dict params as
+    # JSON strings instead of objects.  Accept both forms.
+    # See: https://forum.cursor.com/t/145807
+    #      https://github.com/anthropics/claude-code/issues/5504
+    if isinstance(filters, str):
+        try:
+            filters = json.loads(filters)
+        except (json.JSONDecodeError, ValueError) as e:
+            msg = f"Invalid filters JSON: {e}"
+            raise ToolError(msg) from e
+        if not isinstance(filters, dict):
+            msg = f"filters must be a JSON object, got {type(filters).__name__}"
+            raise ToolError(msg) from None
+
     valid_ops = sorted(LOOKUP_NAME_MAP.keys())
     for key in filters:
         if "__" in key:

src/libtmux/mcp/tools/server_tools.py

@@ -20,16 +20,17 @@
 @handle_tool_errors
 def list_sessions(
     socket_name: str | None = None,
-    filters: dict[str, str] | None = None,
+    filters: dict[str, 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"}``).
+    filters : dict or str, optional
+        Django-style filters as a dict (e.g. ``{"session_name__contains": "dev"}``)
+        or as a JSON string. Some MCP clients require the string form.
 
     Returns
     -------

src/libtmux/mcp/tools/session_tools.py

@@ -24,7 +24,7 @@ def list_windows(
     session_name: str | None = None,
     session_id: str | None = None,
     socket_name: str | None = None,
-    filters: dict[str, str] | None = None,
+    filters: dict[str, str] | str | None = None,
 ) -> str:
     """List windows in a tmux session, or all windows across sessions.
 
@@ -37,8 +37,9 @@ def list_windows(
         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"}``).
+    filters : dict or str, optional
+        Django-style filters as a dict (e.g. ``{"window_name__contains": "dev"}``)
+        or as a JSON string. Some MCP clients require the string form.
 
     Returns
     -------

src/libtmux/mcp/tools/window_tools.py

@@ -35,7 +35,7 @@ def list_panes(
     window_id: str | None = None,
     window_index: str | None = None,
     socket_name: str | None = None,
-    filters: dict[str, str] | None = None,
+    filters: dict[str, str] | str | None = None,
 ) -> str:
     """List panes in a tmux window, session, or across the entire server.
 
@@ -53,8 +53,10 @@ def list_panes(
         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"}``).
+    filters : dict or str, optional
+        Django-style filters as a dict
+        (e.g. ``{"pane_current_command__contains": "vim"}``)
+        or as a JSON string. Some MCP clients require the string form.
 
     Returns
     -------

tests/mcp/test_utils.py

@@ -152,7 +152,7 @@ class ApplyFiltersFixture(t.NamedTuple):
     """Test fixture for _apply_filters."""
 
     test_id: str
-    filters: dict[str, str] | None
+    filters: dict[str, str] | str | None
     expected_count: int | None  # None = don't check exact count
     expect_error: bool
     error_match: str | None
@@ -201,6 +201,41 @@ class ApplyFiltersFixture(t.NamedTuple):
         expect_error=False,
         error_match=None,
     ),
+    ApplyFiltersFixture(
+        test_id="string_filter_exact",
+        filters='{"session_name": "<session_name>"}',
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+    ApplyFiltersFixture(
+        test_id="string_filter_contains",
+        filters='{"session_name__contains": "<partial>"}',
+        expected_count=1,
+        expect_error=False,
+        error_match=None,
+    ),
+    ApplyFiltersFixture(
+        test_id="string_filter_invalid_json",
+        filters="{bad json",
+        expected_count=None,
+        expect_error=True,
+        error_match="Invalid filters JSON",
+    ),
+    ApplyFiltersFixture(
+        test_id="string_filter_not_object",
+        filters='"just a string"',
+        expected_count=None,
+        expect_error=True,
+        error_match="filters must be a JSON object",
+    ),
+    ApplyFiltersFixture(
+        test_id="string_filter_array",
+        filters='["not", "a", "dict"]',
+        expected_count=None,
+        expect_error=True,
+        error_match="filters must be a JSON object",
+    ),
 ]
 
 
@@ -213,14 +248,19 @@ def test_apply_filters(
     mcp_server: Server,
     mcp_session: Session,
     test_id: str,
-    filters: dict[str, str] | None,
+    filters: dict[str, 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:
+    if isinstance(filters, str):
+        session_name = mcp_session.session_name
+        assert session_name is not None
+        filters = filters.replace("<session_name>", session_name)
+        filters = filters.replace("<partial>", session_name[:4])
+    elif filters is not None:
         session_name = mcp_session.session_name
         assert session_name is not None
         resolved: dict[str, str] = {}