it2mcp

Instructions

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.",
  )