mcp(feat[tools]): Add 25 MCP tools for tmux control

why: Provide comprehensive tool coverage for AI agents to manage tmux.
what:
- server_tools: list_sessions, create_session, kill_server, get_server_info
- session_tools: list_windows, create_window, rename_session, kill_session
- window_tools: list_panes, split_window, rename_window, kill_window,
  select_layout, resize_window
- pane_tools: send_keys, capture_pane, resize_pane, kill_pane,
  set_pane_title, get_pane_info, clear_pane
- option_tools: show_option, set_option
- env_tools: show_environment, set_environment

Author: tony

src/libtmux/mcp/tools/__init__.py

@@ -0,0 +1,27 @@
+"""MCP tool registration for libtmux."""
+
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register all tool modules with the FastMCP instance."""
+    from libtmux.mcp.tools import (
+        env_tools,
+        option_tools,
+        pane_tools,
+        server_tools,
+        session_tools,
+        window_tools,
+    )
+
+    server_tools.register(mcp)
+    session_tools.register(mcp)
+    window_tools.register(mcp)
+    pane_tools.register(mcp)
+    option_tools.register(mcp)
+    env_tools.register(mcp)

src/libtmux/mcp/tools/env_tools.py

@@ -0,0 +1,101 @@
+"""MCP tools for tmux environment variable management."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+from libtmux.mcp._utils import (
+    _get_server,
+    _resolve_session,
+    handle_tool_errors,
+)
+
+if t.TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+@handle_tool_errors
+def show_environment(
+    session_name: str | None = None,
+    session_id: str | None = None,
+    socket_name: str | None = None,
+) -> str:
+    """Show tmux environment variables.
+
+    Parameters
+    ----------
+    session_name : str, optional
+        Session name to query environment for.
+    session_id : str, optional
+        Session ID to query environment for.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    str
+        JSON dict of environment variables.
+    """
+    server = _get_server(socket_name=socket_name)
+
+    if session_name is not None or session_id is not None:
+        session = _resolve_session(
+            server,
+            session_name=session_name,
+            session_id=session_id,
+        )
+        env_dict = session.show_environment()
+    else:
+        env_dict = server.show_environment()
+
+    return json.dumps(env_dict)
+
+
+@handle_tool_errors
+def set_environment(
+    name: str,
+    value: str,
+    session_name: str | None = None,
+    session_id: str | None = None,
+    socket_name: str | None = None,
+) -> str:
+    """Set a tmux environment variable.
+
+    Parameters
+    ----------
+    name : str
+        Environment variable name.
+    value : str
+        Environment variable value.
+    session_name : str, optional
+        Session name to set environment for.
+    session_id : str, optional
+        Session ID to set environment for.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    str
+        JSON confirming the variable was set.
+    """
+    server = _get_server(socket_name=socket_name)
+
+    if session_name is not None or session_id is not None:
+        session = _resolve_session(
+            server,
+            session_name=session_name,
+            session_id=session_id,
+        )
+        session.set_environment(name, value)
+    else:
+        server.set_environment(name, value)
+
+    return json.dumps({"name": name, "value": value, "status": "set"})
+
+
+def register(mcp: FastMCP) -> None:
+    """Register environment tools with the MCP instance."""
+    mcp.tool(annotations={"readOnlyHint": True})(show_environment)
+    mcp.tool(annotations={"destructiveHint": False})(set_environment)

src/libtmux/mcp/tools/option_tools.py

@@ -0,0 +1,121 @@
+"""MCP tools for tmux option management."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+from libtmux.constants import OptionScope
+from libtmux.mcp._utils import (
+    _get_server,
+    _resolve_pane,
+    _resolve_session,
+    _resolve_window,
+    handle_tool_errors,
+)
+
+if t.TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+    from libtmux.options import OptionsMixin
+
+_SCOPE_MAP: dict[str, OptionScope] = {
+    "server": OptionScope.Server,
+    "session": OptionScope.Session,
+    "window": OptionScope.Window,
+    "pane": OptionScope.Pane,
+}
+
+
+def _resolve_option_target(
+    socket_name: str | None,
+    scope: str | None,
+    target: str | None,
+) -> tuple[OptionsMixin, OptionScope | None]:
+    """Resolve the target object and scope for option operations."""
+    server = _get_server(socket_name=socket_name)
+    opt_scope = _SCOPE_MAP.get(scope) if scope is not None else None
+
+    if target is not None and opt_scope is not None:
+        if opt_scope == OptionScope.Session:
+            return _resolve_session(server, session_name=target), opt_scope
+        if opt_scope == OptionScope.Window:
+            return _resolve_window(server, window_id=target), opt_scope
+        if opt_scope == OptionScope.Pane:
+            return _resolve_pane(server, pane_id=target), opt_scope
+    return server, opt_scope
+
+
+@handle_tool_errors
+def show_option(
+    option: str,
+    scope: str | None = None,
+    target: str | None = None,
+    global_: bool = False,
+    socket_name: str | None = None,
+) -> str:
+    """Show a tmux option value.
+
+    Parameters
+    ----------
+    option : str
+        The tmux option name to query.
+    scope : str, optional
+        Option scope: "server", "session", "window", or "pane".
+    target : str, optional
+        Target session, window, or pane identifier.
+    global_ : bool
+        Whether to query the global option.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    str
+        JSON with the 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})
+
+
+@handle_tool_errors
+def set_option(
+    option: str,
+    value: str,
+    scope: str | None = None,
+    target: str | None = None,
+    global_: bool = False,
+    socket_name: str | None = None,
+) -> str:
+    """Set a tmux option value.
+
+    Parameters
+    ----------
+    option : str
+        The tmux option name to set.
+    value : str
+        The value to set.
+    scope : str, optional
+        Option scope: "server", "session", "window", or "pane".
+    target : str, optional
+        Target session, window, or pane identifier.
+    global_ : bool
+        Whether to set the global option.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    str
+        JSON confirming the option was set.
+    """
+    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"})
+
+
+def register(mcp: FastMCP) -> None:
+    """Register option tools with the MCP instance."""
+    mcp.tool(annotations={"readOnlyHint": True})(show_option)
+    mcp.tool(annotations={"destructiveHint": False})(set_option)