claude-team-mcp 0.6.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

claude_team_mcp/server.py

@@ -1,26 +1,24 @@
 """
 Claude Team MCP Server
 
-FastMCP-based server for managing multiple Claude Code sessions via iTerm2.
+FastMCP-based server for managing multiple Claude Code sessions via terminal backends.
 Allows a "manager" Claude Code session to spawn and coordinate multiple
 "worker" Claude Code sessions.
 """
 
+import functools
 import logging
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from iterm2.app import App as ItermApp
-    from iterm2.connection import Connection as ItermConnection
 
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.session import ServerSession
 
-from .iterm_utils import read_screen_text
+from claude_team.poller import WorkerPoller
+
 from .registry import SessionRegistry
+from .terminal_backends import ItermBackend, TerminalBackend, TmuxBackend, select_backend_id
 from .tools import register_all_tools
 from .utils import error_response, HINTS
 
@@ -44,6 +42,7 @@ logger.info("=== Claude Team MCP Server Starting ===")
 # =============================================================================
 
 _global_registry: SessionRegistry | None = None
+_global_poller: WorkerPoller | None = None
 
 
 def get_global_registry() -> SessionRegistry:
@@ -55,6 +54,15 @@ def get_global_registry() -> SessionRegistry:
     return _global_registry
 
 
+def get_global_poller(registry: SessionRegistry) -> WorkerPoller:
+    """Get or create the global singleton poller."""
+    global _global_poller
+    if _global_poller is None:
+        _global_poller = WorkerPoller(registry)
+        logger.info("Created global singleton poller")
+    return _global_poller
+
+
 # =============================================================================
 # Application Context
 # =============================================================================
@@ -65,12 +73,11 @@ class AppContext:
     """
     Application context shared across all tool invocations.
 
-    Maintains the iTerm2 connection and registry of managed sessions.
+    Maintains the terminal backend and registry of managed sessions.
     This is the persistent state that makes the MCP server useful.
     """
 
-    iterm_connection: "ItermConnection"
-    iterm_app: "ItermApp"
+    terminal_backend: TerminalBackend
     registry: SessionRegistry
 
 
@@ -79,16 +86,16 @@ class AppContext:
 # =============================================================================
 
 
-async def refresh_iterm_connection() -> tuple["ItermConnection", "ItermApp"]:
+async def refresh_iterm_connection() -> ItermBackend:
     """
-    Create a fresh iTerm2 connection.
+    Create a fresh iTerm2 connection and backend.
 
     The iTerm2 Python API uses websockets with ping_interval=None, meaning
     connections can go stale without any keepalive mechanism. This function
     creates a new connection when needed.
 
     Returns:
-        Tuple of (connection, app)
+        ItermBackend with a fresh connection and app
 
     Raises:
         RuntimeError: If connection fails
@@ -103,98 +110,121 @@ async def refresh_iterm_connection() -> tuple["ItermConnection", "ItermApp"]:
         if app is None:
             raise RuntimeError("Could not get iTerm2 app")
         logger.debug("Fresh iTerm2 connection established")
-        return connection, app
+        return ItermBackend(connection, app)
     except Exception as e:
         logger.error(f"Failed to refresh iTerm2 connection: {e}")
         raise RuntimeError("Could not connect to iTerm2") from e
 
 
-async def ensure_connection(app_ctx: "AppContext") -> tuple["ItermConnection", "ItermApp"]:
+async def ensure_connection(app_ctx: "AppContext") -> TerminalBackend:
     """
-    Ensure we have a working iTerm2 connection, refreshing if stale.
+    Ensure we have a working terminal backend, refreshing if stale.
 
     The iTerm2 websocket connection can go stale due to lack of keepalive
     (ping_interval=None in the iterm2 library). This function tests the
     connection and refreshes it if needed.
 
+    For non-iTerm backends (e.g., tmux), this simply returns the backend.
+
     Args:
-        app_ctx: The application context containing connection and app
+        app_ctx: The application context containing the backend
 
     Returns:
-        Tuple of (connection, app) - either existing or refreshed
+        TerminalBackend - either existing or refreshed
     """
+    backend = app_ctx.terminal_backend
+    if not isinstance(backend, ItermBackend):
+        return backend
+
     from iterm2.app import async_get_app
 
-    connection = app_ctx.iterm_connection
-    app = app_ctx.iterm_app
+    connection = backend.connection
+    app = backend.app
 
     # Test if connection is still alive by trying a simple operation
     try:
         # async_get_app is a lightweight call that tests the connection
         refreshed_app = await async_get_app(connection)
         if refreshed_app is not None:
-            return connection, refreshed_app
+            if refreshed_app is not app:
+                backend = ItermBackend(connection, refreshed_app)
+                app_ctx.terminal_backend = backend
+            return backend
         # App is None, need to refresh
         raise RuntimeError("App is None, refreshing connection")
     except Exception as e:
         logger.warning(f"iTerm2 connection appears stale ({e}), refreshing...")
         # Connection is dead, create a new one
-        connection, app = await refresh_iterm_connection()
-        # Update the context with fresh connection
-        app_ctx.iterm_connection = connection
-        app_ctx.iterm_app = app
-        return connection, app
+        backend = await refresh_iterm_connection()
+        app_ctx.terminal_backend = backend
+        return backend
 
 
 @asynccontextmanager
-async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+async def app_lifespan(
+    server: FastMCP,
+    enable_poller: bool = False,
+) -> AsyncIterator[AppContext]:
     """
-    Manage iTerm2 connection lifecycle.
+    Manage terminal backend connection lifecycle.
 
-    Connects to iTerm2 on startup and maintains the connection
+    Connects to the terminal backend on startup and maintains the connection
     for the duration of the server's lifetime.
 
     Note: The iTerm2 Python API uses websockets with ping_interval=None,
     meaning connections can go stale. Individual tool functions should use
-    ensure_connection() before making iTerm2 API calls that use the
+    ensure_connection() before making terminal backend calls that use the
     connection directly.
     """
     logger.info("Claude Team MCP Server starting...")
 
-    # Import iterm2 here to fail fast if not available
-    try:
-        from iterm2.app import async_get_app
-        from iterm2.connection import Connection
-    except ImportError as e:
-        logger.error(
-            "iterm2 package not found. Install with: uv add iterm2\n"
-            "Also enable: iTerm2 → Preferences → General → Magic → Enable Python API"
-        )
-        raise RuntimeError("iterm2 package required") from e
-
-    # Connect to iTerm2
-    logger.info("Connecting to iTerm2...")
-    try:
-        connection = await Connection.async_create()
-        app = await async_get_app(connection)
-        if app is None:
-            raise RuntimeError("Could not get iTerm2 app")
-        logger.info("Connected to iTerm2 successfully")
-    except Exception as e:
-        logger.error(f"Failed to connect to iTerm2: {e}")
-        logger.error("Make sure iTerm2 is running and Python API is enabled")
-        raise RuntimeError("Could not connect to iTerm2") from e
+    backend_id = select_backend_id()
+    logger.info("Selecting terminal backend: %s", backend_id)
+
+    if backend_id == "tmux":
+        backend: TerminalBackend = TmuxBackend()
+    elif backend_id == "iterm":
+        # Import iterm2 here to fail fast if not available
+        try:
+            from iterm2.app import async_get_app
+            from iterm2.connection import Connection
+        except ImportError as e:
+            logger.error(
+                "iterm2 package not found. Install with: uv add iterm2\n"
+                "Also enable: iTerm2 → Preferences → General → Magic → Enable Python API"
+            )
+            raise RuntimeError("iterm2 package required") from e
+
+        # Connect to iTerm2
+        logger.info("Connecting to iTerm2...")
+        try:
+            connection = await Connection.async_create()
+            app = await async_get_app(connection)
+            if app is None:
+                raise RuntimeError("Could not get iTerm2 app")
+            logger.info("Connected to iTerm2 successfully")
+        except Exception as e:
+            logger.error(f"Failed to connect to iTerm2: {e}")
+            logger.error("Make sure iTerm2 is running and Python API is enabled")
+            raise RuntimeError("Could not connect to iTerm2") from e
+        backend = ItermBackend(connection, app)
+    else:
+        raise RuntimeError(f"Unknown terminal backend: {backend_id}")
 
-    # Create application context with singleton registry (persists across sessions)
+    # Create application context with singleton registry (persists across sessions).
     ctx = AppContext(
-        iterm_connection=connection,
-        iterm_app=app,
+        terminal_backend=backend,
         registry=get_global_registry(),
     )
+    poller: WorkerPoller | None = None
+    if enable_poller:
+        poller = get_global_poller(ctx.registry)
+        poller.start()
 
     try:
         yield ctx
     finally:
+        # Keep the global poller running across per-session lifespans.
         # Cleanup: close any remaining sessions gracefully
         logger.info("Claude Team MCP Server shutting down...")
         if ctx.registry.count() > 0:
@@ -207,11 +237,15 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
 # =============================================================================
 
 
-def create_mcp_server(host: str = "127.0.0.1", port: int = 8766) -> FastMCP:
+def create_mcp_server(
+    host: str = "127.0.0.1",
+    port: int = 8766,
+    enable_poller: bool = False,
+) -> FastMCP:
     """Create and configure the FastMCP server instance."""
     server = FastMCP(
         "Claude Team Manager",
-        lifespan=app_lifespan,
+        lifespan=functools.partial(app_lifespan, enable_poller=enable_poller),
         host=host,
         port=port,
     )
@@ -301,7 +335,7 @@ async def resource_session_screen(
     """
     Get the current terminal screen content for a session.
 
-    Returns the visible text in the iTerm2 pane for the specified session.
+    Returns the visible text in the terminal pane for the specified session.
     Useful for checking what Claude is currently displaying or doing.
 
     Args:
@@ -318,7 +352,7 @@ async def resource_session_screen(
         )
 
     try:
-        screen_text = await read_screen_text(session.iterm_session)
+        screen_text = await app_ctx.terminal_backend.read_screen_text(session.terminal_session)
         # Get non-empty lines
         lines = [line for line in screen_text.split("\n") if line.strip()]
 
@@ -354,7 +388,7 @@ def run_server(transport: str = "stdio", port: int = 8766):
     if transport == "streamable-http":
         logger.info(f"Starting Claude Team MCP Server (HTTP on port {port})...")
         # Create server with configured port for HTTP mode
-        server = create_mcp_server(host="127.0.0.1", port=port)
+        server = create_mcp_server(host="127.0.0.1", port=port, enable_poller=True)
         server.run(transport="streamable-http")
     else:
         logger.info("Starting Claude Team MCP Server (stdio)...")