Automattic / Automattic/studio
Studio MCP take_screenshot should accept local site nameOrPath
- 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
Assessment
This issue has not been assessed yet.