easy-spec-mcp
# easy-spec-mcp
MCP server for Easy Spec - Playwright projects. It lets an MCP-connected assistant (Claude Code, Claude Desktop, etc.) read and edit flows, scenarios, page objects, and variables, and drive live browser automation -- all by relaying every operation to the companion browser extension's side panel.
This server never reads project files or drives a browser itself. It holds no filesystem adapter and spawns no browser process; every tool call is forwarded over a local WebSocket bridge to an already-connected, human-approved side panel, which performs the action and reports back.
## Requirements
- Node.js 18+
- The Easy Spec - Playwright browser extension installed, with its side panel open and connected to your project folder
- The MCP agent must be approved in the side panel before any `live_*` tool will work
## Install / run
No install needed -- run it with `npx`:
```
npx easy-spec-mcp
```
### Add to an MCP client
```json
{
"mcpServers": {
"easy-spec": {
"command": "npx",
"args": ["easy-spec-mcp"],
"env": {
"EASYSPEC_PROJECT": "/absolute/path/to/your/project"
}
}
}
}
```
`EASYSPEC_PROJECT` is optional -- every tool also accepts a `project` argument. If omitted, tools fall back to `EASYSPEC_PROJECT`, and the `live_*` tools can auto-target the single connected side panel with neither.
## Tools
- **Inspection** -- `list_flows`, `list_scenarios`, `list_page_objects`, `get_variables`, `get_flow`, `get_scenario`, `get_page_object`
- **Flow authoring** -- `create_flow`, `delete_flow`, `set_flow_meta`, `add_step`, `add_multiple_steps`, `update_step`, `remove_step`, `copy_steps`, `set_flow_dataset`, `remove_flow_dataset`, `set_state_var`, `remove_state_var`, `set_output_field`, `remove_output_field`
- **Page objects** -- `create_page_object`, `delete_page_object`, `set_locator`, `remove_locator`
- **Scenarios** -- `create_scenario`, `delete_scenario`, `add_flow_to_scenario`, `remove_flow_from_scenario`, `set_scenario_dataset`, `remove_scenario_dataset`
- **Variables** -- `set_variable`, `unset_variable`
- **Live browser control** (requires a connected, approved side panel) -- `live_status`, `live_replay_flow`, `live_replay_scenario`, `live_run_step`, `live_run_multiple_steps`, `live_run_step_range`, `live_pick_element`, `live_snapshot`, `live_screenshot`, `live_detach`
- **Run tracking** -- `live_start_run`, `live_list_runs`, `live_get_run`, `live_cancel_run`, `live_start_scenario_run`, `live_list_scenario_runs`, `live_get_scenario_run`, `live_cancel_scenario_run`
- **Tab management** -- `live_list_tabs`, `live_switch_tab`, `live_new_tab`
Call `live_status` first to see which projects have a connected side panel and what to pass as `project`/`session`.
## License
MIT
TDQS
Scored across 77 tools
Most tools are clearly separated by entity type (flow, scenario, page object, util, suite) and action (list, get, create, delete, set, live_*). A few closely related live-execution tools could require careful reading, but descriptions generally make each one's purpose distinct.
The naming largely follows a consistent snake_case verb_noun pattern such as list_flows, create_page_object, set_util_body, and live_get_run. Minor deviations like add_to_suite and connect_panel are still readable and do not seriously break the overall convention.
With 77 tools, the surface is extremely large and far outside the typical well-scoped range. Even for a complex automation domain, this many distinct endpoints creates a heavy cognitive and discovery burden for an agent.
The toolkit covers a broad lifecycle: create/list/get/update/delete for flows, scenarios, page objects, and utils, plus live execution, run inspection, and suite management. Some possible lifecycle gaps exist, such as no explicit suite-entry removal tool, but the domain is otherwise richly covered.