send_control_character

Instructions

Implementation Reference

• src/iterm2_mcp/server.py:143-167 (handler)

  The tool handler function 'send_control_character' that implements the logic. It maps a letter (A-Z) to its Ctrl equivalent, handles special keys ESC/ESCAPE (0x1B) and ] (0x1D), and sends the resulting control character to the target iTerm2 session.

  @mcp.tool()
  async def send_control_character(
      letter: str,
      session_id: str | None = None,
  ) -> str:
      """Send a control character to an iTerm2 session.
  
      Supported values: any single letter ``A``-``Z`` (Ctrl-A through Ctrl-Z),
      ``ESC``/``ESCAPE`` for Escape (0x1B), and ``]`` for the telnet escape
      (0x1D).
  
      :param letter: The control key name; see above for accepted forms.
      :param session_id: Target session UUID. Defaults to the active session.
      """
      _SPECIAL_KEYS = {"ESC": 0x1B, "ESCAPE": 0x1B, "]": 0x1D}
      key = letter.strip().upper()
      if key in _SPECIAL_KEYS:
          code = _SPECIAL_KEYS[key]
      elif len(key) == 1 and "A" <= key <= "Z":
          code = ord(key) - ord("A") + 1
      else:
          raise ValueError(f"Unrecognized control key {letter!r}")
      sess = await _session(session_id)
      await sess.async_send_text(chr(code), suppress_broadcast=True)
      return f"Sent Ctrl-{key} to session {sess.session_id}"

• src/iterm2_mcp/server.py:143-143 (registration)

  The @mcp.tool() decorator registers 'send_control_character' as an MCP tool with the FastMCP server instance.

  @mcp.tool()

• src/iterm2_mcp/server.py:144-147 (schema)

  Input schema for the tool: 'letter' (str) - the control key name (A-Z, ESC, ESCAPE, or ]), and optional 'session_id' (str | None). The docstring/type annotations serve as the schema definition for FastMCP.

  async def send_control_character(
      letter: str,
      session_id: str | None = None,
  ) -> str:

• src/iterm2_mcp/server.py:48-69 (helper)

  The '_session' helper function is used by send_control_character to resolve the target session (by explicit session_id or the currently focused session).

  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