Skip to content

Feature: Add evaluate_script_file tool to evaluate JavaScript files from the local filesystem #1775

@achideal

Description

@achideal

Is your feature request related to a problem? Please describe.

When using the evaluate_script tool, the entire JavaScript code must be passed as a string parameter. This becomes problematic when:

  1. Large scripts: Scripts with hundreds of lines need to be passed entirely as a parameter, which is inefficient and can hit token limits in AI agent contexts.
  2. Complex scripts with special characters: Scripts containing template literals, regex patterns, or escaped characters can be mangled when passed as string parameters.
  3. Reusable scripts: When the same script needs to be executed multiple times across different pages, it must be re-sent each time rather than referenced from a file.
  4. Development workflow: Developers often have pre-written JavaScript files they want to inject into pages for testing, debugging, or automation purposes. Currently, they must manually copy-paste the file contents into the evaluate_script tool parameter.

Describe the solution you'd like

Add a new tool called evaluate_script_file that:

  1. Accepts a filePath parameter pointing to a local JavaScript file.
  2. Reads the file content from the local filesystem.
  3. Evaluates the JavaScript function defined in the file inside the currently selected page.
  4. Supports optional args parameter to pass arguments to the function (same as evaluate_script).
  5. Returns the result as JSON (same as evaluate_script).

Example usage:

Given a file /path/to/script.js containing:

(el) => {
  return el.innerText;
}

The tool would be called with:

{
  "filePath": "/path/to/script.js",
  "args": ["<element-uid>"]
}

This is essentially the file-based counterpart of the existing evaluate_script tool, similar to how many CLI tools support both inline and file-based input.

Describe alternatives you've considered

  1. Using evaluate_script with file content read by the AI agent: The agent could read the file first and then pass the content to evaluate_script. However, this wastes tokens by sending the script content through the AI context, and special characters may get corrupted during the string parameter encoding process.

  2. Using a wrapper script: Writing a small wrapper that uses fetch() or dynamic <script> injection. This is fragile and doesn't work for all use cases (e.g., scripts that need to return values).

  3. No alternative considered viable: The most natural and efficient approach is to have the MCP server read the file directly from the filesystem, avoiding any encoding issues and token overhead.

Additional context

I have already implemented this feature and submitted a PR: #1772. The implementation adds a new evaluate_script_file tool alongside the existing evaluate_script tool, reads the JavaScript file using fs.readFileSync with UTF-8 encoding, validates that the file exists and is readable, and supports the same args parameter for passing element UIDs or other arguments.

This feature is particularly useful for AI agent workflows where pre-written scripts need to be injected into web pages for automation, testing, or data extraction purposes.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions