browser_take_screenshot: custom filenames bypass --output-dir, save to workspace root instead

[LeeorNahum]

Description

When --output-dir is configured, browser_take_screenshot only respects it for auto-generated filenames. Custom filenames bypass --output-dir entirely and save to the workspace root.

Scenario	Where file saves	Expected
No filename (auto-generated page-{timestamp}.png)	--output-dir ✅	Correct
Custom filename (e.g. test.png)	Workspace root ❌	Should go to --output-dir

Steps to Reproduce

1. Start the MCP server with --output-dir /tmp/playwright-mcp
2. Navigate to any page
3. Call browser_take_screenshot without a filename → file saves to /tmp/playwright-mcp/page-{timestamp}.png ✅
4. Call browser_take_screenshot with filename: "test.png" → file saves to {workspace}/test.png ❌

Root Cause

In response.ts, the resolveClientFile method uses workspaceFile() when a suggestedFilename is provided, but outputFile() when no filename is given:

async resolveClientFile(template: FilenameTemplate, title: string): Promise<ResolvedFile> {
    let fileName: string;
    if (template.suggestedFilename)
      fileName = await this._context.workspaceFile(template.suggestedFilename, this._clientWorkspace);  // ← workspace root
    else
      fileName = await this._context.outputFile(template, { origin: 'llm' });  // ← --output-dir

Both paths should use outputFile(). The context.outputFile() method already handles suggestedFilename correctly — it uses it as the basename and resolves against outputDir. The checkFile() security check still validates the path is within allowed directories.

Proposed Fix

One-line change in packages/playwright/src/mcp/browser/response.ts:

   if (template.suggestedFilename)
-    fileName = await this._context.workspaceFile(template.suggestedFilename, this._clientWorkspace);
+    fileName = await this._context.outputFile(template, { origin: 'llm' });

I have a PR ready with this fix targeting microsoft/playwright.

Related Issues

• browser_take_screenshot ignores --output-dir when filename contains path separators #1253 — reported the same symptom (closed, root cause not addressed)
• LLM confusion about file saving paths in browser_pdf_save and browser_take_screenshot tools #1002 — suggested clarifying filename as "name only, no directories"

[yury-s]

The --output-dir parameter predates workspace roots and ideally you shouldn't need it at all. The LLM comfortably operates in terms of the paths relative to root and having second base for relative paths just introduces extra churn (the file is first saved to /data/blah and then needs to be moved to /data/blah). We currently use output dir for saving automatic (temporary?) artifacts, e.g. you take a snapshot and it goes to an automatically created file with only path to the file being returned in the response. We should probably update the docs for --output-dir or remove it altogether. What is the reason you are setting it to a custom value? would default output dir work for you?

[LeeorNahum]

Thanks for the follow up.

Default output dir does not work for my use case. I set --output-dir to a temp location on purpose so transient MCP artifacts do not land in repository roots.

In agent workflows, screenshot, PDF, trace, and log files are usually temporary outputs. Saving them in the workspace root creates clutter, accidental git tracking, and extra .gitignore maintenance.

The core issue is inconsistent behavior:

• auto generated filenames respect --output-dir
• custom filenames can resolve to workspace root

That inconsistency is the problem, not relative paths by themselves.

The fix is small and consistent:

• if --output-dir is set, both auto generated and custom filenames should resolve there

This is implemented in PR #39229:
microsoft/playwright#39229