PlayMCP Browser Automation Server

Instructions

Implementation Reference

• src/controllers/playwright.ts:166-208 (handler)

  Core implementation of the scroll tool logic: captures scroll position before and after using window.scrollBy via page.evaluate

  async scroll(x: number, y: number, smooth: boolean = false): Promise<{before: {x: number, y: number}, after: {x: number, y: number}}> {
    try {
      if (!this.isInitialized() || !this.state.page) {
        throw new Error('Browser not initialized');
      }
      
      this.log('Scrolling', { x, y, smooth });
      
      // Get scroll position before scrolling
      const beforeScroll = await this.state.page.evaluate(() => ({
        x: window.scrollX,
        y: window.scrollY
      }));
      
      // Perform scroll with optional smooth behavior
      await this.state.page.evaluate((args: {x: number, y: number, smooth: boolean}) => {
        window.scrollBy({
          left: args.x,
          top: args.y,
          behavior: args.smooth ? 'smooth' : 'auto'
        });
      }, { x, y, smooth });
      
      // Wait for scroll to complete
      await this.state.page.waitForTimeout(smooth ? 500 : 100);
      
      // Get scroll position after scrolling
      const afterScroll = await this.state.page.evaluate(() => ({
        x: window.scrollX,
        y: window.scrollY
      }));
      
      this.log('Scroll complete', { before: beforeScroll, after: afterScroll });
      
      return {
        before: beforeScroll,
        after: afterScroll
      };
    } catch (error: any) {
      console.error('Scroll error:', error);
      throw new BrowserError('Failed to scroll', 'Check if scroll values are valid');
    }
  }

• src/server.ts:638-664 (handler)

  MCP server request handler case for 'scroll' tool: input validation, delegates to controller, formats detailed response with scroll delta

  case 'scroll': {
    if (typeof args.x !== 'number' || typeof args.y !== 'number') {
      return {
        content: [{ type: "text", text: "X and Y scroll amounts are required" }],
        isError: true
      };
    }
    const scrollResult = await playwrightController.scroll(
      args.x, 
      args.y, 
      args.smooth as boolean || false
    );
    return {
      content: [{ 
        type: "text", 
        text: JSON.stringify({
          message: "Page scrolled successfully",
          before: scrollResult.before,
          after: scrollResult.after,
          scrolled: {
            x: scrollResult.after.x - scrollResult.before.x,
            y: scrollResult.after.y - scrollResult.before.y
          }
        }, null, 2)
      }]
    };
  }

• src/server.ts:210-231 (schema)

  Definition and input schema for the 'scroll' tool, specifying parameters x, y (required), smooth (optional)

  const SCROLL_TOOL: Tool = {
    name: "scroll",
    description: "Scroll the page by specified amounts with enhanced feedback",
    inputSchema: {
      type: "object",
      properties: {
        x: { 
          type: "number",
          description: "Horizontal scroll amount in pixels (positive = right, negative = left)"
        },
        y: { 
          type: "number", 
          description: "Vertical scroll amount in pixels (positive = down, negative = up)"
        },
        smooth: {
          type: "boolean",
          description: "Whether to use smooth scrolling animation (default: false)"
        }
      },
      required: ["x", "y"]
    }
  };

• src/server.ts:514-553 (registration)

  Registration of scroll tool in the tools object passed to MCP Server capabilities

  const tools = {
    openBrowser: OPEN_BROWSER_TOOL,
    navigate: NAVIGATE_TOOL,
    type: TYPE_TOOL,
    click: CLICK_TOOL,
    moveMouse: MOVE_MOUSE_TOOL,
    scroll: SCROLL_TOOL,
    screenshot: SCREENSHOT_TOOL,
    getPageSource: GET_PAGE_SOURCE_TOOL,
    getPageText: GET_PAGE_TEXT_TOOL,
    getPageTitle: GET_PAGE_TITLE_TOOL,
    getPageUrl: GET_PAGE_URL_TOOL,
    getScripts: GET_SCRIPTS_TOOL,
    getStylesheets: GET_STYLESHEETS_TOOL,
    getMetaTags: GET_META_TAGS_TOOL,
    getLinks: GET_LINKS_TOOL,
    getImages: GET_IMAGES_TOOL,
    getForms: GET_FORMS_TOOL,
    getElementContent: GET_ELEMENT_CONTENT_TOOL,
    getElementHierarchy: GET_ELEMENT_HIERARCHY_TOOL,
    executeJavaScript: EXECUTE_JAVASCRIPT_TOOL,
    goForward: GO_FORWARD_TOOL,
    hover: HOVER_TOOL,
    dragAndDrop: DRAG_AND_DROP_TOOL,
    selectOption: SELECT_OPTION_TOOL,
    pressKey: PRESS_KEY_TOOL,
    waitForText: WAIT_FOR_TEXT_TOOL,
    waitForSelector: WAIT_FOR_SELECTOR_TOOL,
    resize: RESIZE_TOOL,
    handleDialog: HANDLE_DIALOG_TOOL,
    getConsoleMessages: GET_CONSOLE_MESSAGES_TOOL,
    getNetworkRequests: GET_NETWORK_REQUESTS_TOOL,
    uploadFiles: UPLOAD_FILES_TOOL,
    evaluateWithReturn: EVALUATE_WITH_RETURN_TOOL,
    takeScreenshot: TAKE_SCREENSHOT_TOOL,
    mouseMove: MOUSE_MOVE_TOOL,
    mouseClick: MOUSE_CLICK_TOOL,
    mouseDrag: MOUSE_DRAG_TOOL,
    closeBrowser: CLOSE_BROWSER_TOOL
  };

• src/server.ts:555-565 (registration)

  MCP Server initialization with tools capabilities including the scroll tool

  const server = new Server(
    {
      name: "playmcp-browser",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools,
      },
    }
  );