mcp(feat[tools]): Use Literal types for enum parameters in JSON schema

why: Parameters like `direction` and `scope` were typed as `str | None`,
so the MCP input schema showed `{"type": "string"}` — LLMs had to read
descriptions to discover valid values. Pydantic generates
`{"enum": ["above", "below", ...]}` from `Literal` types, putting valid
values directly in the JSON schema where LLMs can see them.
what:
- Use `t.Literal["above", "below", "left", "right"]` for split direction
- Use `t.Literal["before", "after"]` for window placement direction
- Use `t.Literal["server", "session", "window", "pane"]` for option scope
- Keep manual validation as safety net for direct callers (belt-and-suspenders)

Author: tony

src/libtmux/mcp/tools/option_tools.py

@@ -29,7 +29,7 @@
 
 def _resolve_option_target(
     socket_name: str | None,
-    scope: str | None,
+    scope: t.Literal["server", "session", "window", "pane"] | None,
     target: str | None,
 ) -> tuple[OptionsMixin, OptionScope | None]:
     """Resolve the target object and scope for option operations."""
@@ -62,7 +62,7 @@ def _resolve_option_target(
 @handle_tool_errors
 def show_option(
     option: str,
-    scope: str | None = None,
+    scope: t.Literal["server", "session", "window", "pane"] | None = None,
     target: str | None = None,
     global_: bool = False,
     socket_name: str | None = None,
@@ -74,7 +74,7 @@ def show_option(
     option : str
         The tmux option name to query.
     scope : str, optional
-        Option scope: "server", "session", "window", or "pane".
+        Option scope.
     target : str, optional
         Target identifier. For session scope: session name
         (e.g. 'mysession'). For window scope: window ID (e.g. '@1').
@@ -98,7 +98,7 @@ def show_option(
 def set_option(
     option: str,
     value: str,
-    scope: str | None = None,
+    scope: t.Literal["server", "session", "window", "pane"] | None = None,
     target: str | None = None,
     global_: bool = False,
     socket_name: str | None = None,
@@ -112,7 +112,7 @@ def set_option(
     value : str
         The value to set.
     scope : str, optional
-        Option scope: "server", "session", "window", or "pane".
+        Option scope.
     target : str, optional
         Target identifier. For session scope: session name
         (e.g. 'mysession'). For window scope: window ID (e.g. '@1').

src/libtmux/mcp/tools/session_tools.py

@@ -64,7 +64,7 @@ def create_window(
     window_name: str | None = None,
     start_directory: str | None = None,
     attach: bool = False,
-    direction: str | None = None,
+    direction: t.Literal["before", "after"] | None = None,
     socket_name: str | None = None,
 ) -> str:
     """Create a new window in a tmux session.
@@ -82,7 +82,7 @@ def create_window(
     attach : bool, optional
         Whether to make the new window active.
     direction : str, optional
-        Window placement direction: "before" or "after".
+        Window placement direction.
     socket_name : str, optional
         tmux socket name. Defaults to LIBTMUX_SOCKET env var.
 
@@ -104,7 +104,7 @@ def create_window(
             "before": WindowDirection.Before,
             "after": WindowDirection.After,
         }
-        resolved = direction_map.get(direction.lower())
+        resolved = direction_map.get(direction)
         if resolved is None:
             from fastmcp.exceptions import ToolError
 

src/libtmux/mcp/tools/window_tools.py

@@ -90,7 +90,7 @@ def split_window(
     session_id: str | None = None,
     window_id: str | None = None,
     window_index: str | None = None,
-    direction: str | None = None,
+    direction: t.Literal["above", "below", "left", "right"] | None = None,
     size: str | int | None = None,
     start_directory: str | None = None,
     shell: str | None = None,
@@ -111,7 +111,7 @@ def split_window(
     window_index : str, optional
         Window index within the session.
     direction : str, optional
-        Split direction: 'above', 'below', 'left', or 'right'.
+        Split direction.
     size : str or int, optional
         Size of the new pane. Use a string with '%%' suffix for
         percentage (e.g. '50%%') or an integer for lines/columns.
@@ -131,7 +131,7 @@ def split_window(
 
     pane_dir: PaneDirection | None = None
     if direction is not None:
-        pane_dir = _DIRECTION_MAP.get(direction.lower())
+        pane_dir = _DIRECTION_MAP.get(direction)
         if pane_dir is None:
             from fastmcp.exceptions import ToolError
 

tests/mcp/test_option_tools.py

@@ -33,7 +33,7 @@ def test_show_option_invalid_scope(mcp_server: Server, mcp_session: Session) ->
     with pytest.raises(ToolError, match="Invalid scope"):
         show_option(
             option="base-index",
-            scope="global",
+            scope="global",  # type: ignore[arg-type]
             socket_name=mcp_server.socket_name,
         )
 

tests/mcp/test_session_tools.py

@@ -61,7 +61,7 @@ def test_create_window_invalid_direction(
         create_window(
             session_name=mcp_session.session_name,
             window_name="bad_dir",
-            direction="sideways",
+            direction="sideways",  # type: ignore[arg-type]
             socket_name=mcp_server.socket_name,
         )
 

tests/mcp/test_window_tools.py

@@ -68,7 +68,7 @@ def test_split_window_invalid_direction(
     with pytest.raises(ToolError, match="Invalid direction"):
         split_window(
             window_id=window.window_id,
-            direction="diagonal",
+            direction="diagonal",  # type: ignore[arg-type]
             socket_name=mcp_server.socket_name,
         )