Automattic / Automattic/studio

Studio MCP take_screenshot should accept local site nameOrPath

Open
#3,306 0 comments 0 reactions 1 assignee Claimed by @chubes4 View on GitHub
[Status] Auto-allocated Bug
Dominant language
TypeScript
Stars
517
Forks
95
Avg merge
1d 22h
Merged PRs (30d)
162

Description

## Bug

`take_screenshot` is advertised and prompted as part of Studio's local-site workflow, but it does not accept the local-site addressing shape used by the rest of the local-site MCP tool surface.

Most local-site tools accept `nameOrPath`, resolve it through Studio's site config, then operate on the resolved site. `take_screenshot` only accepts `url`, so an agent operating on an active local site can naturally call it with `nameOrPath` + `path` and get rejected by MCP schema validation before the handler runs.

## Evidence

Runtime tool schema probe against `studioToolDefinitions` showed:

```json
{
"wp_cli": ["nameOrPath", "command"],
"validate_blocks": ["nameOrPath", "filePath", "content"],
"take_screenshot": ["url", "viewport"]
}
```

Focused temporary Vitest probe passed while confirming this contrast:

```bash
npm -w wp-studio exec vitest run ai/tests/screenshot-contract.temp.test.ts
```

Relevant code locations on current trunk/BFB worktrees:

- Local prompt tells agents to screenshot the local site after build: `apps/cli/ai/system-prompt.ts`
- Local-site resolver pattern: `apps/cli/ai/tools.ts` → `resolveSite( nameOrPath )`
- `wp_cli` schema uses `nameOrPath`
- `validate_blocks` schema uses `nameOrPath`
- `take_screenshot` schema requires `url` only

Live benchmark artifact captured the real failure:

```json
{
"name": "take_screenshot",
"input": {
"nameOrPath": "/tmp/studio-bfb-bench-single-1777579294/studio-agent-site-build-artifacts/sites/bfb-38088-1777579299409-zrmah4u33v9",
"path": "/"
}
}
```

MCP rejected it before the handler ran:

```text
MCP error -32602: Input validation error: Invalid arguments for tool take_screenshot:
[
{
"expected": "string",
"code": "invalid_type",
"path": ["url"],
"message": "Invalid input: expected string, received undefined"
}
]
```

The same run later retried with an absolute URL:

```json
{
"name": "take_screenshot",
"input": {
"url": "http://localhost:9092/"
}
}
```

That indicates the failure is not a browser/screenshot runtime failure. It is the argument contract mismatch.

## Why this is a Studio bug

The local-site MCP tool surface trains the agent to identify sites by `nameOrPath`:

- `site_info`
- `site_start`
- `site_stop`
- `site_delete`
- `preview_create`
- `preview_list`
- `preview_update`
- `wp_cli`
- `validate_blocks`
- `need_for_speed`
- `rank_me_up`
- `site_push`
- `site_pull`
- `site_import`
- `site_export`

`take_screenshot` is the exception even though the local prompt tells the agent to use it as part of the same local-site build loop.

## Expected behavior

`take_screenshot` should accept either:

- `url` for the existing absolute-URL behavior, or
- `nameOrPath` plus optional `path` for local Studio sites.

When `url` is absent and `nameOrPath` is present, Studio should:

1. Resolve the site with the existing `resolveSite( nameOrPath )` helper.
2. Build the base URL with `getSiteUrl( site )`.
3. Normalize and append `path` when provided, defaulting to `/`.
4. Capture the screenshot of that resolved URL.

## Suggested test coverage

Add focused tests in `apps/cli/ai/tests/tools.test.ts`:

- URL-only screenshot path remains supported.
- `nameOrPath` resolves a local site URL.
- `nameOrPath` + `path` resolves a site-relative URL.
- Missing both `url` and `nameOrPath` returns a clear validation/tool error.

## Scope

This should be a small Studio MCP tool contract fix. It does not require BFB, benchmark harness changes, or screenshot runtime changes.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.