Playwright MCP

Instructions

Implementation Reference

• src/mcp/index.ts:190-229 (registration)

  Registration of the 'execute-code' MCP tool using server.tool, including schema and handler function that delegates to secureEvalAsync

  server.tool(
    'execute-code',
    'Execute custom Playwright JS code against the current page',
    {
      code: z.string().describe(`The Playwright code to execute. Must be an async function declaration that takes a page parameter.
  
  Example:
  async function run(page) {
    console.log(await page.title());
    return await page.title();
  }
  
  Returns an object with:
  - result: The return value from your function
  - logs: Array of console logs from execution
  - errors: Array of any errors encountered
  
  Example response:
  {"result": "Google", "logs": ["[log] Google"], "errors": []}`)
    },
    async ({ code }) => {
      posthogServer.capture({
        distinctId: getUserId(),
        event: 'execute_code',
        properties: {
          codeLength: code.length,
        },
      });
  
      const result = await secureEvalAsync(page, code);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2) // Pretty print the JSON
          }
        ]
      };
    }
  )

• src/mcp/index.ts:210-228 (handler)

  MCP tool handler for 'execute-code': logs event, executes code via secureEvalAsync, and returns JSON-stringified result as text content

  async ({ code }) => {
    posthogServer.capture({
      distinctId: getUserId(),
      event: 'execute_code',
      properties: {
        codeLength: code.length,
      },
    });
  
    const result = await secureEvalAsync(page, code);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2) // Pretty print the JSON
        }
      ]
    };
  }

• src/mcp/index.ts:193-208 (schema)

  Input schema for 'execute-code' tool: requires 'code' string with detailed description and example

    {
      code: z.string().describe(`The Playwright code to execute. Must be an async function declaration that takes a page parameter.
  
  Example:
  async function run(page) {
    console.log(await page.title());
    return await page.title();
  }
  
  Returns an object with:
  - result: The return value from your function
  - logs: Array of console logs from execution
  - errors: Array of any errors encountered
  
  Example response:
  {"result": "Google", "logs": ["[log] Google"], "errors": []}`)

• src/mcp/eval.ts:6-97 (helper)

  Core implementation of secure code execution using Node.js vm module: wraps user code, sandboxes with page object and captured console, executes and returns result/logs/errors

  export const secureEvalAsync = async (page: Page, code: string, context = {}) => {
    // Set default options
    const timeout = 20000;
    const filename = 'eval.js';
  
    let logs: string[] = [];
    let errors: string[] = [];
  
    // Code should already be a function declaration
    // Just need to execute it with page argument
    const wrappedCode = `
      ${code}
      run(page);
    `;
  
    // Create restricted sandbox with provided context
    const sandbox = {
      // Core async essentials
      Promise,
      setTimeout,
      clearTimeout,
      setImmediate,
      clearImmediate,
  
      // Pass page object to sandbox
      page,
  
      // Capture all console methods
      console: {
        log: (...args: any[]) => {
          const msg = args.map(arg => String(arg)).join(' ');
          logs.push(`[log] ${msg}`);
        },
        error: (...args: any[]) => {
          const msg = args.map(arg => String(arg)).join(' ');
          errors.push(`[error] ${msg}`);
        },
        warn: (...args: any[]) => {
          const msg = args.map(arg => String(arg)).join(' ');
          logs.push(`[warn] ${msg}`);
        },
        info: (...args: any[]) => {
          const msg = args.map(arg => String(arg)).join(' ');
          logs.push(`[info] ${msg}`);
        },
        debug: (...args: any[]) => {
          const msg = args.map(arg => String(arg)).join(' ');
          logs.push(`[debug] ${msg}`);
        },
        trace: (...args: any[]) => {
          const msg = args.map(arg => String(arg)).join(' ');
          logs.push(`[trace] ${msg}`);
        }
      },
  
      // User-provided context
      ...context,
  
      // Explicitly block access to sensitive globals
      process: undefined,
      global: undefined,
      require: undefined,
      __dirname: undefined,
      __filename: undefined,
      Buffer: undefined
    };
  
    try {
      // Create context and script
      const vmContext = vm.createContext(sandbox);
      const script = new vm.Script(wrappedCode, { filename });
  
      // Execute and await result
      const result = script.runInContext(vmContext);
      const awaitedResult = await result;
  
      return {
        result: awaitedResult,
        logs,
        errors
      };
  
    } catch (error: any) {
      return {
        error: true,
        message: error.message,
        stack: error.stack,
        logs,
        errors
      };
    }
  }