app_get_focus
Retrieve details about the currently active window, tab, and session in iTerm2 to monitor or control terminal interactions.
Instructions
Get information about the currently focused window, tab, and session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/it2mcp/server.py:801-821 (handler)Main handler function for app_get_focus tool. Decorated with @mcp.tool(), this async function retrieves information about the currently focused iTerm2 window, tab, and session. It uses an inner _impl function that accesses app.current_terminal_window and traverses the hierarchy to collect window_id, tab_id, session_id, and session_name, returning them as JSON.
@mcp.tool() async def app_get_focus() -> str: """Get information about the currently focused window, tab, and session.""" async def _impl(connection: iterm2.Connection, app: iterm2.App) -> str: result: dict[str, Any] = {} window = app.current_terminal_window if window: result["window_id"] = window.window_id tab = window.current_tab if tab: result["tab_id"] = tab.tab_id session = tab.current_session if session: result["session_id"] = session.session_id name = await session.async_get_variable("session.name") if name: result["session_name"] = name return json.dumps(result, indent=2) return await _run(_impl) - src/it2mcp/server.py:38-42 (helper)Helper function _run that creates a connection to iTerm2 and executes the tool implementation. It creates an iterm2.Connection, retrieves the app instance, and calls the provided function with connection and app parameters.
async def _run(func: Callable[..., Awaitable[T]], **kwargs: Any) -> T: """Create a connection to iTerm2, run *func*, and return its result.""" connection = await iterm2.Connection.async_create() app = await iterm2.async_get_app(connection) return await func(connection=connection, app=app, **kwargs) - src/it2mcp/security.py:33-45 (schema)Security tier configuration defining app_get_focus as a Tier.READ tool. This places the tool in the 'read' permission tier, indicating it performs read-only operations that don't modify state.
TOOL_TIERS: dict[str, Tier] = { # read "session_list": Tier.READ, "session_read": Tier.READ, "session_get_variable": Tier.READ, "tab_list": Tier.READ, "window_list": Tier.READ, "app_get_focus": Tier.READ, "profile_list": Tier.READ, "profile_show": Tier.READ, "app_version": Tier.READ, "app_theme": Tier.READ, "window_arrange_list": Tier.READ, - src/it2mcp/server.py:28-31 (registration)FastMCP instance creation that serves as the tool registry. The @mcp.tool() decorator used on app_get_focus registers it with this MCP server instance named 'it2mcp'.
mcp = FastMCP( "it2mcp", instructions="Control iTerm2 from MCP — manage sessions, windows, tabs, profiles, and more.", )