fix(puppeteer): enable async code execution in puppeteer_evaluate tool

[matipojo]

Description

The fix enables the puppeteer_evaluate tool in the Puppeteer server to properly handle and execute asynchronous code. Previously, async functions would return empty results, but now they correctly wait for and return the resolved values.

Example before fix:

// Returns empty results {}
(async function exampleForWatingforFetchResults(query) {
    const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
    await sleep(2_000);
    console.log('searching for:', query);
    return { searchResults: ['result #1'] };
})('foo');

Before fix output:

{
  "content": [
    {
      "type": "text",
      "text": "Execution result:\n{}\n\nConsole output:\n"
    }
  ],
  "isError": false
}

After fix output:

{
  "content": [
    {
      "type": "text",
      "text": "Execution result:\n{\n  \"searchResults\": [\n    \"result #1\"\n  ]\n}\n\nConsole output:\n[log] searching for: foo"
    }
  ],
  "isError": false
}

Server Details

• Server: puppeteer
• Changes to: tools (puppeteer_evaluate tool)

Motivation and Context

This fix is crucial for properly executing asynchronous JavaScript code in browser automation tasks. Common use cases that were previously broken include:

• Web scraping with delay handling
• Waiting for network requests to complete
• Complex browser automation sequences requiring async/await
• Custom scripts that interact with browser APIs asynchronously

How Has This Been Tested?

By running both versions in Claude Desktop and MCP Inspector.

Breaking Changes

No breaking changes. This fix enhances existing functionality without modifying the tool's interface.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Protocol Documentation
• My server follows MCP security best practices
• I have updated the server's README accordingly
• I have tested this with an LLM client
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have documented all environment variables and configuration options

Additional context

The implementation approach involves three key steps:

1. Console Preparation:

   • Before code execution, the browser's console functions are manipulated to capture all logs
   • This ensures proper collection of console output during async operations

2. Code Execution:

   • Instead of using JavaScript's eval, the code is executed using Puppeteer's native evaluate function
   • This change is crucial as Puppeteer's evaluate is specifically designed to handle async code execution in the browser context

3. Cleanup and Collection:

   • After execution, all console logs are collected
   • The manipulated console functions are reset to their original state
   • Both the execution result and console output are properly returned

[jspahrsummers]

Thanks, the await on page.evaluate makes sense. Can you explain why you added window.mcpHelper?

[matipojo]

Thanks, the await on page.evaluate makes sense. Can you explain why you added window.mcpHelper?

Since, in this solution, we can't use a local var to store the original console and the logs, so we have to store it on the global window.

Storing on the global window can make conflicts with other scripts that may run on the page, specially for a generic var name like logs, so I preferred to store them on a scoped variable on the global window.