mcp(test): Add 49 tests for MCP tools, resources, and utilities

why: Ensure MCP server functionality works correctly with live tmux.
what:
- Add conftest.py with mcp_server, mcp_session, mcp_window, mcp_pane
  fixtures and server cache cleanup
- Add test_utils.py for resolver and serializer functions
- Add test files for all 6 tool modules
- Add test_resources.py with mock MCP for resource functions

Author: tony

tests/mcp/__init__.py

@@ -0,0 +1 @@
+"""Tests for libtmux MCP server."""

tests/mcp/conftest.py

@@ -0,0 +1,57 @@
+"""Test fixtures for libtmux MCP server tests."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libtmux.mcp._utils import _server_cache
+
+if t.TYPE_CHECKING:
+    from libtmux.pane import Pane
+    from libtmux.server import Server
+    from libtmux.session import Session
+    from libtmux.window import Window
+
+
+@pytest.fixture(autouse=True)
+def _clear_server_cache() -> t.Generator[None, None, None]:
+    """Clear the MCP server cache between tests."""
+    _server_cache.clear()
+    yield
+    _server_cache.clear()
+
+
+@pytest.fixture
+def mcp_server(server: Server) -> Server:
+    """Provide a libtmux Server pre-registered in the MCP cache.
+
+    This fixture sets up the server cache so MCP tools can find the
+    test server without environment variables.
+    """
+    cache_key = (server.socket_name, None)
+    _server_cache[cache_key] = server
+    # Also register as default (None, None) for tools that don't specify a socket
+    _server_cache[(None, None)] = server
+    return server
+
+
+@pytest.fixture
+def mcp_session(mcp_server: Server, session: Session) -> Session:
+    """Provide a session accessible via MCP tools."""
+    return session
+
+
+@pytest.fixture
+def mcp_window(mcp_session: Session) -> Window:
+    """Provide a window accessible via MCP tools."""
+    return mcp_session.active_window
+
+
+@pytest.fixture
+def mcp_pane(mcp_window: Window) -> Pane:
+    """Provide a pane accessible via MCP tools."""
+    active_pane = mcp_window.active_pane
+    assert active_pane is not None
+    return active_pane

tests/mcp/test_env_tools.py

@@ -0,0 +1,53 @@
+"""Tests for libtmux MCP environment tools."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+from libtmux.mcp.tools.env_tools import set_environment, show_environment
+
+if t.TYPE_CHECKING:
+    from libtmux.server import Server
+    from libtmux.session import Session
+
+
+def test_show_environment(mcp_server: Server, mcp_session: Session) -> None:
+    """show_environment returns environment variables."""
+    result = show_environment(socket_name=mcp_server.socket_name)
+    data = json.loads(result)
+    assert isinstance(data, dict)
+
+
+def test_set_environment(mcp_server: Server, mcp_session: Session) -> None:
+    """set_environment sets an environment variable."""
+    result = set_environment(
+        name="MCP_TEST_VAR",
+        value="test_value",
+        socket_name=mcp_server.socket_name,
+    )
+    data = json.loads(result)
+    assert data["status"] == "set"
+    assert data["name"] == "MCP_TEST_VAR"
+
+
+def test_set_and_show_environment(mcp_server: Server, mcp_session: Session) -> None:
+    """set_environment value is readable via show_environment."""
+    set_environment(
+        name="MCP_ROUND_TRIP",
+        value="hello",
+        socket_name=mcp_server.socket_name,
+    )
+    result = show_environment(socket_name=mcp_server.socket_name)
+    data = json.loads(result)
+    assert data.get("MCP_ROUND_TRIP") == "hello"
+
+
+def test_show_environment_session(mcp_server: Server, mcp_session: Session) -> None:
+    """show_environment can target a specific session."""
+    result = show_environment(
+        session_name=mcp_session.session_name,
+        socket_name=mcp_server.socket_name,
+    )
+    data = json.loads(result)
+    assert isinstance(data, dict)

tests/mcp/test_option_tools.py

@@ -0,0 +1,39 @@
+"""Tests for libtmux MCP option tools."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+from libtmux.mcp.tools.option_tools import set_option, show_option
+
+if t.TYPE_CHECKING:
+    from libtmux.server import Server
+    from libtmux.session import Session
+
+
+def test_show_option(mcp_server: Server, mcp_session: Session) -> None:
+    """show_option returns an option value."""
+    result = show_option(
+        option="base-index",
+        scope="session",
+        global_=True,
+        socket_name=mcp_server.socket_name,
+    )
+    data = json.loads(result)
+    assert data["option"] == "base-index"
+    assert "value" in data
+
+
+def test_set_option(mcp_server: Server, mcp_session: Session) -> None:
+    """set_option sets a tmux option."""
+    result = set_option(
+        option="display-time",
+        value="3000",
+        scope="server",
+        global_=True,
+        socket_name=mcp_server.socket_name,
+    )
+    data = json.loads(result)
+    assert data["status"] == "set"
+    assert data["option"] == "display-time"

tests/mcp/test_pane_tools.py

@@ -0,0 +1,83 @@
+"""Tests for libtmux MCP pane tools."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+from libtmux.mcp.tools.pane_tools import (
+    capture_pane,
+    clear_pane,
+    get_pane_info,
+    kill_pane,
+    send_keys,
+    set_pane_title,
+)
+
+if t.TYPE_CHECKING:
+    from libtmux.pane import Pane
+    from libtmux.server import Server
+    from libtmux.session import Session
+
+
+def test_send_keys(mcp_server: Server, mcp_pane: Pane) -> None:
+    """send_keys sends keys to a pane."""
+    result = send_keys(
+        keys="echo hello_mcp",
+        pane_id=mcp_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert "sent" in result.lower()
+
+
+def test_capture_pane(mcp_server: Server, mcp_pane: Pane) -> None:
+    """capture_pane returns pane content."""
+    result = capture_pane(
+        pane_id=mcp_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert isinstance(result, str)
+
+
+def test_get_pane_info(mcp_server: Server, mcp_pane: Pane) -> None:
+    """get_pane_info returns detailed pane info."""
+    result = get_pane_info(
+        pane_id=mcp_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    data = json.loads(result)
+    assert data["pane_id"] == mcp_pane.pane_id
+    assert "pane_width" in data
+    assert "pane_height" in data
+
+
+def test_set_pane_title(mcp_server: Server, mcp_pane: Pane) -> None:
+    """set_pane_title sets the pane title."""
+    result = set_pane_title(
+        title="my_test_title",
+        pane_id=mcp_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    data = json.loads(result)
+    assert data["pane_id"] == mcp_pane.pane_id
+
+
+def test_clear_pane(mcp_server: Server, mcp_pane: Pane) -> None:
+    """clear_pane clears pane content."""
+    result = clear_pane(
+        pane_id=mcp_pane.pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert "cleared" in result.lower()
+
+
+def test_kill_pane(mcp_server: Server, mcp_session: Session) -> None:
+    """kill_pane kills a pane."""
+    window = mcp_session.active_window
+    new_pane = window.split()
+    pane_id = new_pane.pane_id
+    result = kill_pane(
+        pane_id=pane_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert "killed" in result.lower()

tests/mcp/test_resources.py

@@ -0,0 +1,101 @@
+"""Tests for libtmux MCP resources."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+import pytest
+
+from libtmux.mcp.resources.hierarchy import register
+
+if t.TYPE_CHECKING:
+    from libtmux.pane import Pane
+    from libtmux.server import Server
+    from libtmux.session import Session
+    from libtmux.window import Window
+
+
+@pytest.fixture
+def resource_functions(mcp_server: Server) -> dict[str, t.Any]:
+    """Register resources and return the function references.
+
+    Since resources are registered via decorators, we capture them
+    by creating a mock FastMCP and collecting registered functions.
+    """
+    functions: dict[str, t.Any] = {}
+
+    class MockMCP:
+        def resource(self, uri: str) -> t.Any:
+            def decorator(fn: t.Any) -> t.Any:
+                functions[uri] = fn
+                return fn
+
+            return decorator
+
+    register(MockMCP())  # type: ignore[arg-type]
+    return functions
+
+
+def test_sessions_resource(
+    resource_functions: dict[str, t.Any], mcp_session: Session
+) -> None:
+    """tmux://sessions returns session list."""
+    fn = resource_functions["tmux://sessions"]
+    result = fn()
+    data = json.loads(result)
+    assert isinstance(data, list)
+    assert len(data) >= 1
+
+
+def test_session_detail_resource(
+    resource_functions: dict[str, t.Any], mcp_session: Session
+) -> None:
+    """tmux://sessions/{name} returns session with windows."""
+    fn = resource_functions["tmux://sessions/{session_name}"]
+    result = fn(mcp_session.session_name)
+    data = json.loads(result)
+    assert "session_id" in data
+    assert "windows" in data
+
+
+def test_session_windows_resource(
+    resource_functions: dict[str, t.Any], mcp_session: Session
+) -> None:
+    """tmux://sessions/{name}/windows returns window list."""
+    fn = resource_functions["tmux://sessions/{session_name}/windows"]
+    result = fn(mcp_session.session_name)
+    data = json.loads(result)
+    assert isinstance(data, list)
+
+
+def test_window_detail_resource(
+    resource_functions: dict[str, t.Any],
+    mcp_session: Session,
+    mcp_window: Window,
+) -> None:
+    """tmux://sessions/{name}/windows/{index} returns window with panes."""
+    fn = resource_functions["tmux://sessions/{session_name}/windows/{window_index}"]
+    result = fn(mcp_session.session_name, mcp_window.window_index)
+    data = json.loads(result)
+    assert "window_id" in data
+    assert "panes" in data
+
+
+def test_pane_detail_resource(
+    resource_functions: dict[str, t.Any], mcp_pane: Pane
+) -> None:
+    """tmux://panes/{pane_id} returns pane details."""
+    fn = resource_functions["tmux://panes/{pane_id}"]
+    result = fn(mcp_pane.pane_id)
+    data = json.loads(result)
+    assert data["pane_id"] == mcp_pane.pane_id
+
+
+def test_pane_content_resource(
+    resource_functions: dict[str, t.Any], mcp_pane: Pane
+) -> None:
+    """tmux://panes/{pane_id}/content returns captured text."""
+    fn = resource_functions["tmux://panes/{pane_id}/content"]
+    result = fn(mcp_pane.pane_id)
+    assert isinstance(result, str)