mcp(fix[_utils]): Add tmux_bin to cache key and is_alive eviction

why: Cache key only included (socket_name, socket_path), so changing
LIBTMUX_TMUX_BIN between calls returned a stale Server. Dead servers
were never evicted from the cache.
what:
- Change cache key to 3-tuple (socket_name, socket_path, tmux_bin)
- Add is_alive() check on cache hit to evict dead servers
- Add _invalidate_server() for explicit cache eviction
- Call _invalidate_server() in kill_server tool after server.kill()
- Update test fixtures for 3-tuple cache keys
- Add tests for is_alive eviction and _invalidate_server

Author: tony

src/libtmux/mcp/_utils.py

@@ -21,7 +21,7 @@
 
 logger = logging.getLogger(__name__)
 
-_server_cache: dict[tuple[str | None, str | None], Server] = {}
+_server_cache: dict[tuple[str | None, str | None, str | None], Server] = {}
 
 
 def _get_server(
@@ -49,7 +49,12 @@ def _get_server(
 
     tmux_bin = os.environ.get("LIBTMUX_TMUX_BIN")
 
-    cache_key = (socket_name, socket_path)
+    cache_key = (socket_name, socket_path, tmux_bin)
+    if cache_key in _server_cache:
+        cached = _server_cache[cache_key]
+        if not cached.is_alive():
+            del _server_cache[cache_key]
+
     if cache_key not in _server_cache:
         kwargs: dict[str, t.Any] = {}
         if socket_name is not None:
@@ -63,6 +68,26 @@ def _get_server(
     return _server_cache[cache_key]
 
 
+def _invalidate_server(
+    socket_name: str | None = None,
+    socket_path: str | None = None,
+) -> None:
+    """Evict a server from the cache.
+
+    Parameters
+    ----------
+    socket_name : str, optional
+        tmux socket name used in the cache key.
+    socket_path : str, optional
+        tmux socket path used in the cache key.
+    """
+    keys_to_remove = [
+        key for key in _server_cache if key[0] == socket_name and key[1] == socket_path
+    ]
+    for key in keys_to_remove:
+        del _server_cache[key]
+
+
 def _resolve_session(
     server: Server,
     session_name: str | None = None,

src/libtmux/mcp/tools/server_tools.py

@@ -7,6 +7,7 @@
 
 from libtmux.mcp._utils import (
     _get_server,
+    _invalidate_server,
     _serialize_session,
     handle_tool_errors,
 )
@@ -102,6 +103,7 @@ def kill_server(socket_name: str | None = None) -> str:
     """
     server = _get_server(socket_name=socket_name)
     server.kill()
+    _invalidate_server(socket_name=socket_name)
     return "Server killed successfully"
 
 

tests/mcp/conftest.py

@@ -30,10 +30,10 @@ def mcp_server(server: Server) -> Server:
     This fixture sets up the server cache so MCP tools can find the
     test server without environment variables.
     """
-    cache_key = (server.socket_name, None)
+    cache_key = (server.socket_name, None, 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
+    # Also register as default for tools that don't specify a socket
+    _server_cache[(None, None, None)] = server
     return server
 
 

tests/mcp/test_utils.py

@@ -9,6 +9,7 @@
 from libtmux import exc
 from libtmux.mcp._utils import (
     _get_server,
+    _invalidate_server,
     _resolve_pane,
     _resolve_session,
     _resolve_window,
@@ -36,8 +37,12 @@ def test_get_server_caches(monkeypatch: pytest.MonkeyPatch) -> None:
     """_get_server returns the same instance for the same socket."""
     _server_cache.clear()
     s1 = _get_server(socket_name="test_cache")
+    # Simulate a live server so the cache is not evicted
+    monkeypatch.setattr(s1, "is_alive", lambda: True)
     s2 = _get_server(socket_name="test_cache")
     assert s1 is s2
+    # Verify 3-tuple cache key includes tmux_bin
+    assert (s1.socket_name, None, None) in _server_cache
 
 
 def test_get_server_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -120,3 +125,22 @@ def test_serialize_pane(mcp_pane: Pane) -> None:
     assert "pane_id" in data
     assert "window_id" in data
     assert "session_id" in data
+
+
+def test_get_server_evicts_dead(monkeypatch: pytest.MonkeyPatch) -> None:
+    """_get_server evicts cached server when is_alive returns False."""
+    _server_cache.clear()
+    s1 = _get_server(socket_name="test_evict")
+    # Patch is_alive to return False to simulate a dead server
+    monkeypatch.setattr(s1, "is_alive", lambda: False)
+    s2 = _get_server(socket_name="test_evict")
+    assert s1 is not s2
+
+
+def test_invalidate_server() -> None:
+    """_invalidate_server removes matching entries from cache."""
+    _server_cache.clear()
+    _get_server(socket_name="test_inv")
+    assert len(_server_cache) == 1
+    _invalidate_server(socket_name="test_inv")
+    assert len(_server_cache) == 0