espresso-mcp

Instructions

Implementation Reference

• src/espresso_mcp/server.py:408-473 (handler)

  The replace_text tool handler, registered via @mcp.tool() decorator. It uses a series of ADB shell input keyevents to select all text (trying Ctrl+A, multiple Ctrl, or home+shift+end), clear it with DEL or BACK, then input the new text (replacing spaces with %s for ADB compatibility). Returns success message or raises RuntimeError on failure.

  @mcp.tool()
  def replace_text(text: str) -> str:
      """Replace text on the connected Android device by clearing current text and typing new text"""
      # Try using Ctrl+A to select all text
      ctrl_a = subprocess.run(
          ["adb", "shell", "input", "keyevent", "KEYCODE_CTRL_LEFT", "KEYCODE_A"],
          capture_output=True,
          text=True,
      )
      
      # If Ctrl+A doesn't work, try alternative selection methods
      if ctrl_a.returncode != 0:
          # Method 1: Select all using key combination
          select_all_combo = subprocess.run(
              ["adb", "shell", "input", "keyevent", "29", "29", "29"],  # Multiple Ctrl+A attempts
              capture_output=True,
              text=True,
          )
          
          if select_all_combo.returncode != 0:
              # Method 2: Move to start, then select to end
              move_home = subprocess.run(
                  ["adb", "shell", "input", "keyevent", "KEYCODE_MOVE_HOME"],
                  capture_output=True,
                  text=True,
              )
              if move_home.returncode == 0:
                  # Hold shift and move to end
                  subprocess.run(
                      ["adb", "shell", "input", "keyevent", "KEYCODE_SHIFT_LEFT"],
                      capture_output=True,
                      text=True,
                  )
                  subprocess.run(
                      ["adb", "shell", "input", "keyevent", "KEYCODE_MOVE_END"],
                      capture_output=True,
                      text=True,
                  )
      
      # Clear the selected text by pressing delete/backspace
      delete = subprocess.run(
          ["adb", "shell", "input", "keyevent", "KEYCODE_DEL"],
          capture_output=True,
          text=True,
      )
      if delete.returncode != 0:
          # If delete doesn't work, try backspace
          backspace = subprocess.run(
              ["adb", "shell", "input", "keyevent", "KEYCODE_BACK"],
              capture_output=True,
              text=True,
          )
          if backspace.returncode != 0:
              raise RuntimeError("Error clearing text: unable to delete selected text")
      
      # Type the new text
      adb_text = text.replace(" ", "%s")
      type_result = subprocess.run(
          ["adb", "shell", "input", "text", adb_text],
          capture_output=True,
          text=True,
      )
      if type_result.returncode != 0:
          raise RuntimeError(f"Error typing text '{text}': {type_result.stderr}")
      
      return f"Replaced text with '{text}' successfully."

• src/espresso_mcp/server.py:408-408 (registration)

  Decorator that registers the replace_text function as an MCP tool.

  @mcp.tool()

• src/espresso_mcp/server.py:409-409 (schema)

  Function signature defines input schema (text: str) and output (str), with docstring providing description.

  def replace_text(text: str) -> str: