mcp(refactor[tools,resources]): Return Pydantic models instead of JSON strings

why: Returning typed Pydantic models instead of `json.dumps()` strings
gives MCP clients auto-generated `outputSchema` for result validation,
lets tests assert on model attributes directly (`result.session_name`)
instead of `json.loads(result)["session_name"]`, and centralizes field
documentation in model `Field(description=...)` definitions.
what:
- Update `_serialize_*` functions to return Pydantic models
- Update `_apply_filters` with generic TypeVar for typed returns
- Change tool return types: `str` → `SessionInfo`, `WindowInfo`,
  `PaneInfo`, `ServerInfo`, `OptionResult`, `OptionSetResult`,
  `EnvironmentSetResult`
- Keep `str` returns for message-only tools (kill_*, send_keys,
  clear_pane) and text output (capture_pane, show_environment)
- Update resources to use `.model_dump()` before `json.dumps()`
- Update all tests to assert on model attributes directly

Author: tony

src/libtmux/mcp/_utils.py

@@ -18,6 +18,7 @@
 from libtmux.server import Server
 
 if t.TYPE_CHECKING:
+    from libtmux.mcp.models import PaneInfo, SessionInfo, WindowInfo
     from libtmux.pane import Pane
     from libtmux.session import Session
     from libtmux.window import Window
@@ -286,11 +287,14 @@ def _resolve_pane(
     return panes[0]
 
 
+M = t.TypeVar("M")
+
+
 def _apply_filters(
     items: t.Any,
     filters: dict[str, str] | str | None,
-    serializer: t.Callable[..., dict[str, t.Any]],
-) -> list[dict[str, t.Any]]:
+    serializer: t.Callable[..., M],
+) -> list[M]:
     """Apply QueryList filters and serialize results.
 
     Parameters
@@ -302,11 +306,11 @@ def _apply_filters(
         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.
+        Serializer function to convert each item to a model.
 
     Returns
     -------
-    list[dict]
+    list
         Serialized list of matching items.
 
     Raises
@@ -349,8 +353,8 @@ def _apply_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.
+def _serialize_session(session: Session) -> SessionInfo:
+    """Serialize a Session to a Pydantic model.
 
     Parameters
     ----------
@@ -359,20 +363,23 @@ def _serialize_session(session: Session) -> dict[str, t.Any]:
 
     Returns
     -------
-    dict
-        Session data including id, name, window count, dimensions.
+    SessionInfo
+        Session data including id, name, window count.
     """
-    return {
-        "session_id": session.session_id,
-        "session_name": session.session_name,
-        "window_count": len(session.windows),
-        "session_attached": getattr(session, "session_attached", None),
-        "session_created": getattr(session, "session_created", None),
-    }
+    from libtmux.mcp.models import SessionInfo
+
+    assert session.session_id is not None
+    return SessionInfo(
+        session_id=session.session_id,
+        session_name=session.session_name,
+        window_count=len(session.windows),
+        session_attached=getattr(session, "session_attached", None),
+        session_created=getattr(session, "session_created", None),
+    )
 
 
-def _serialize_window(window: Window) -> dict[str, t.Any]:
-    """Serialize a Window to a JSON-compatible dict.
+def _serialize_window(window: Window) -> WindowInfo:
+    """Serialize a Window to a Pydantic model.
 
     Parameters
     ----------
@@ -381,25 +388,28 @@ def _serialize_window(window: Window) -> dict[str, t.Any]:
 
     Returns
     -------
-    dict
+    WindowInfo
         Window data including id, name, index, pane count, layout.
     """
-    return {
-        "window_id": window.window_id,
-        "window_name": window.window_name,
-        "window_index": window.window_index,
-        "session_id": window.session_id,
-        "session_name": getattr(window, "session_name", None),
-        "pane_count": len(window.panes),
-        "window_layout": getattr(window, "window_layout", None),
-        "window_active": getattr(window, "window_active", None),
-        "window_width": getattr(window, "window_width", None),
-        "window_height": getattr(window, "window_height", None),
-    }
-
-
-def _serialize_pane(pane: Pane) -> dict[str, t.Any]:
-    """Serialize a Pane to a JSON-compatible dict.
+    from libtmux.mcp.models import WindowInfo
+
+    assert window.window_id is not None
+    return WindowInfo(
+        window_id=window.window_id,
+        window_name=window.window_name,
+        window_index=window.window_index,
+        session_id=window.session_id,
+        session_name=getattr(window, "session_name", None),
+        pane_count=len(window.panes),
+        window_layout=getattr(window, "window_layout", None),
+        window_active=getattr(window, "window_active", None),
+        window_width=getattr(window, "window_width", None),
+        window_height=getattr(window, "window_height", None),
+    )
+
+
+def _serialize_pane(pane: Pane) -> PaneInfo:
+    """Serialize a Pane to a Pydantic model.
 
     Parameters
     ----------
@@ -408,22 +418,25 @@ def _serialize_pane(pane: Pane) -> dict[str, t.Any]:
 
     Returns
     -------
-    dict
+    PaneInfo
         Pane data including id, dimensions, current command, title.
     """
-    return {
-        "pane_id": pane.pane_id,
-        "pane_index": getattr(pane, "pane_index", None),
-        "pane_width": getattr(pane, "pane_width", None),
-        "pane_height": getattr(pane, "pane_height", None),
-        "pane_current_command": getattr(pane, "pane_current_command", None),
-        "pane_current_path": getattr(pane, "pane_current_path", None),
-        "pane_pid": getattr(pane, "pane_pid", None),
-        "pane_title": getattr(pane, "pane_title", None),
-        "pane_active": getattr(pane, "pane_active", None),
-        "window_id": pane.window_id,
-        "session_id": pane.session_id,
-    }
+    from libtmux.mcp.models import PaneInfo
+
+    assert pane.pane_id is not None
+    return PaneInfo(
+        pane_id=pane.pane_id,
+        pane_index=getattr(pane, "pane_index", None),
+        pane_width=getattr(pane, "pane_width", None),
+        pane_height=getattr(pane, "pane_height", None),
+        pane_current_command=getattr(pane, "pane_current_command", None),
+        pane_current_path=getattr(pane, "pane_current_path", None),
+        pane_pid=getattr(pane, "pane_pid", None),
+        pane_title=getattr(pane, "pane_title", None),
+        pane_active=getattr(pane, "pane_active", None),
+        window_id=pane.window_id,
+        session_id=pane.session_id,
+    )
 
 
 P = t.ParamSpec("P")

src/libtmux/mcp/resources/hierarchy.py

@@ -31,7 +31,7 @@ def get_sessions() -> str:
             JSON array of session objects.
         """
         server = _get_server()
-        sessions = [_serialize_session(s) for s in server.sessions]
+        sessions = [_serialize_session(s).model_dump() for s in server.sessions]
         return json.dumps(sessions, indent=2)
 
     @mcp.resource("tmux://sessions/{session_name}", title="Session Detail")
@@ -54,8 +54,8 @@ def get_session(session_name: str) -> str:
             msg = f"Session not found: {session_name}"
             raise ResourceError(msg)
 
-        result = _serialize_session(session)
-        result["windows"] = [_serialize_window(w) for w in session.windows]
+        result = _serialize_session(session).model_dump()
+        result["windows"] = [_serialize_window(w).model_dump() for w in session.windows]
         return json.dumps(result, indent=2)
 
     @mcp.resource("tmux://sessions/{session_name}/windows", title="Session Windows")
@@ -78,7 +78,7 @@ def get_session_windows(session_name: str) -> str:
             msg = f"Session not found: {session_name}"
             raise ResourceError(msg)
 
-        windows = [_serialize_window(w) for w in session.windows]
+        windows = [_serialize_window(w).model_dump() for w in session.windows]
         return json.dumps(windows, indent=2)
 
     @mcp.resource(
@@ -111,8 +111,8 @@ def get_window(session_name: str, window_index: str) -> str:
             msg = f"Window not found: index {window_index}"
             raise ResourceError(msg)
 
-        result = _serialize_window(window)
-        result["panes"] = [_serialize_pane(p) for p in window.panes]
+        result = _serialize_window(window).model_dump()
+        result["panes"] = [_serialize_pane(p).model_dump() for p in window.panes]
         return json.dumps(result, indent=2)
 
     @mcp.resource("tmux://panes/{pane_id}", title="Pane Detail")
@@ -135,7 +135,7 @@ def get_pane(pane_id: str) -> str:
             msg = f"Pane not found: {pane_id}"
             raise ResourceError(msg)
 
-        return json.dumps(_serialize_pane(pane), indent=2)
+        return json.dumps(_serialize_pane(pane).model_dump(), indent=2)
 
     @mcp.resource("tmux://panes/{pane_id}/content", title="Pane Content")
     def get_pane_content(pane_id: str) -> str:

src/libtmux/mcp/tools/env_tools.py

@@ -10,6 +10,7 @@
     _resolve_session,
     handle_tool_errors,
 )
+from libtmux.mcp.models import EnvironmentSetResult
 
 if t.TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -59,7 +60,7 @@ def set_environment(
     session_name: str | None = None,
     session_id: str | None = None,
     socket_name: str | None = None,
-) -> str:
+) -> EnvironmentSetResult:
     """Set a tmux environment variable.
 
     Parameters
@@ -77,8 +78,8 @@ def set_environment(
 
     Returns
     -------
-    str
-        JSON confirming the variable was set.
+    EnvironmentSetResult
+        Confirmation with variable name, value, and status.
     """
     server = _get_server(socket_name=socket_name)
 
@@ -92,7 +93,7 @@ def set_environment(
     else:
         server.set_environment(name, value)
 
-    return json.dumps({"name": name, "value": value, "status": "set"})
+    return EnvironmentSetResult(name=name, value=value, status="set")
 
 
 def register(mcp: FastMCP) -> None:

src/libtmux/mcp/tools/option_tools.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import json
 import typing as t
 
 from libtmux.constants import OptionScope
@@ -13,6 +12,7 @@
     _resolve_window,
     handle_tool_errors,
 )
+from libtmux.mcp.models import OptionResult, OptionSetResult
 
 if t.TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -66,7 +66,7 @@ def show_option(
     target: str | None = None,
     global_: bool = False,
     socket_name: str | None = None,
-) -> str:
+) -> OptionResult:
     """Show a tmux option value.
 
     Parameters
@@ -86,12 +86,12 @@ def show_option(
 
     Returns
     -------
-    str
-        JSON with the option name and its value.
+    OptionResult
+        Option name and its value.
     """
     obj, opt_scope = _resolve_option_target(socket_name, scope, target)
     value = obj.show_option(option, global_=global_, scope=opt_scope)
-    return json.dumps({"option": option, "value": value})
+    return OptionResult(option=option, value=value)
 
 
 @handle_tool_errors
@@ -102,7 +102,7 @@ def set_option(
     target: str | None = None,
     global_: bool = False,
     socket_name: str | None = None,
-) -> str:
+) -> OptionSetResult:
     """Set a tmux option value.
 
     Parameters
@@ -124,12 +124,12 @@ def set_option(
 
     Returns
     -------
-    str
-        JSON confirming the option was set.
+    OptionSetResult
+        Confirmation with option name, value, and status.
     """
     obj, opt_scope = _resolve_option_target(socket_name, scope, target)
     obj.set_option(option, value, global_=global_, scope=opt_scope)
-    return json.dumps({"option": option, "value": value, "status": "set"})
+    return OptionSetResult(option=option, value=value, status="set")
 
 
 def register(mcp: FastMCP) -> None: