focus_session
Bring a specific iTerm2 session to the foreground by activating its window and selecting its tab or pane. Provide the session UUID to focus.
Instructions
Bring a session to the foreground.
:param session_id: The session UUID to activate. Its window is raised and its tab/pane is selected.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:111-120 (handler)The 'focus_session' tool handler. Decorated with @mcp.tool(), it resolves a session by ID and calls async_activate to bring it to the foreground.
@mcp.tool() async def focus_session(session_id: str) -> str: """Bring a session to the foreground. :param session_id: The session UUID to activate. Its window is raised and its tab/pane is selected. """ sess = await _session(session_id) await sess.async_activate(select_tab=True, order_window_front=True) return f"Activated session {session_id}" - src/iterm2_mcp/server.py:48-69 (helper)The _session() helper that resolves a session_id to an iterm2.Session, called by focus_session. Falls back to the currently focused session if session_id is None.
async def _session(session_id: str | None) -> iterm2.Session: """Resolve a session by ID, falling back to the currently active session. :param session_id: A specific session UUID to target, or ``None`` to use the currently focused window/tab/pane. """ app = await _app() if session_id: sess = app.get_session_by_id(session_id) if sess is None: raise ValueError(f"No session found with ID {session_id!r}") return sess win = app.current_terminal_window if win is None: raise RuntimeError("No active iTerm2 window.") tab = win.current_tab if tab is None: raise RuntimeError("No active tab in the current window.") sess = tab.current_session if sess is None: raise RuntimeError("No active session in the current tab.") return sess - src/iterm2_mcp/server.py:21-22 (registration)The FastMCP instance used to register all tools via the @mcp.tool() decorator.
mcp = FastMCP("iterm2-mcp") - src/iterm2_mcp/server.py:111-112 (schema)The session_id parameter is a plain str (no Pydantic model) – FastMCP derives the schema from the type annotation automatically.
@mcp.tool() async def focus_session(session_id: str) -> str: