atlas-browser-mcp

Instructions

Implementation Reference

• src/atlas_browser_mcp/browser.py:476-493 (handler)

  Main scroll handler that validates input, determines scroll amount, calls humanized scroll, and returns page observation

  def _scroll(self, direction: str = "down", **_) -> BrowserResult:
      """Scroll the page"""
      if self._page is None:
          return BrowserResult(success=False, error="No page open")
      
      if direction not in ["up", "down"]:
          return BrowserResult(success=False, error="direction must be 'up' or 'down'")
      
      try:
          amount = random.randint(250, 400) if self._humanize else 300
          self._human_scroll(direction, amount)
          return self._observe()
          
      except Exception as e:
          return BrowserResult(
              success=False,
              error=f"Scroll failed: {str(e)}"
          )

• src/atlas_browser_mcp/browser.py:601-634 (helper)

  Humanized scroll helper that simulates natural scrolling with inertia using segmented wheel movements and occasional corrections

  def _human_scroll(self, direction: str, amount: int = 300):
      """Humanized scrolling with inertia"""
      delta = amount if direction == "down" else -amount
      
      if not self._humanize:
          self._page.mouse.wheel(0, delta)
          return
      
      segments = random.randint(5, 10)
      total_scrolled = 0
      
      for i in range(segments):
          progress = i / segments
          if progress < 0.2 or progress > 0.8:
              segment_ratio = 0.05
          else:
              segment_ratio = 0.15
          
          segment_delta = int(delta * segment_ratio)
          self._page.mouse.wheel(0, segment_delta)
          total_scrolled += segment_delta
          time.sleep(random.uniform(0.02, 0.05))
      
      remaining = delta - total_scrolled
      if abs(remaining) > 10:
          self._page.mouse.wheel(0, remaining)
      
      if random.random() < 0.15:
          time.sleep(random.uniform(0.1, 0.3))
          correction = int(delta * random.uniform(-0.1, -0.05))
          self._page.mouse.wheel(0, correction)
      
      if self._humanize:
          time.sleep(random.uniform(0.3, 0.8))

• src/atlas_browser_mcp/server.py:116-130 (schema)

  Tool schema registration defining the scroll tool with name, description, and inputSchema (direction parameter with enum values)

  Tool(
      name="scroll",
      description="Scroll the page up or down",
      inputSchema={
          "type": "object",
          "properties": {
              "direction": {
                  "type": "string",
                  "enum": ["up", "down"],
                  "description": "Scroll direction (default: down)",
                  "default": "down"
              }
          }
      }
  )

• src/atlas_browser_mcp/server.py:175-180 (registration)

  Tool call handler that routes 'scroll' tool invocations to browser.execute with action='scroll' and direction parameter

  elif name == "scroll":
      result = await asyncio.to_thread(
          browser.execute,
          action="scroll",
          direction=arguments.get("direction", "down")
      )

• src/atlas_browser_mcp/browser.py:76-84 (registration)

  Action mapping that connects the 'scroll' action string to the _scroll method handler in the execute dispatcher

  actions = {
      "navigate": self._navigate,
      "observe": self._observe,
      "click": self._click,
      "multi_click": self._multi_click,
      "type": self._type,
      "scroll": self._scroll,
      "close": self._close
  }