Files
liqa/docs/mcp.md
ars9 81164f8494
CI / changes (pull_request) Successful in 14s
CI / server (pull_request) Successful in 2m25s
CI / client (pull_request) Successful in 1m35s
CI / image (pull_request) Skipped
feat: export e2e tests for a chosen scenario version
- GET /scenarios/:id/export-e2e and the export_e2e_test MCP tool take
  an optional version, defaulting to the latest
- build the test project from that version's steps, name and timeout
- put the version in the zip name (<scenario>-vN-e2e-test.zip), the
  generated package name and the README heading
- the Export e2e test button exports the version being viewed
- document the e2e export in scenario.md and mcp.md
2026-10-08 18:37:33 +03:00

6.7 KiB

MCP tools

The MCP endpoint is exposed at /mcp (Streamable HTTP transport), e.g. http://localhost:13000/mcp with the compose setup. Each request is served by a fresh MCP server, so there is no MCP session state between calls.

The server registers the following tools. All entity IDs are UUIDs; list tools are paginated (page, limit, and where noted orderBy / orderDir). Errors are returned as MCP tool errors (isError: true) with the message as text.

Sessions

Tool Description
list_sessions List saved browser sessions (orderBy/orderDir)
delete_session Delete a session by id

Environments

Tool Description
list_environments List environments (orderBy/orderDir)
get_environment Get one environment by id
create_environment Create an environment: name, optional description, data
update_environment Update name, description and/or data of environment id
delete_environment Delete an environment by id

data is a free-form map of string keys to string values, read in step code with context.getEnv(key).

Credentials

Tool Description
list_credentials List credentials (orderBy/orderDir). Returns the full data, secrets included
get_credential Get one credential by id (full data)
create_credential Create a credential: name, optional data (JSON-encoded string)
update_credential Update name and/or data; omitted fields are left unchanged
delete_credential Delete a credential; also removes it from scenarios it's assigned to

Browser (ad-hoc)

Tool Description
open_url Open url, optionally in saved session sessionName; returns title and content (readerMode for readable text, selector to limit to one element)
exec_code Run Playwright JS that receives a single context argument (see scenario.md), optionally after opening url and/or in session sessionName. environmentId loads an environment for context.getEnv(); credentials ({ alias: credentialId }) loads credentials for context.getCredential(alias)

Scenarios

Tool Description
list_scenarios List scenarios (orderBy/orderDir)
get_scenario Get a scenario (latest version) with its steps
create_scenario Create a scenario: name, optional description, environmentId (default environment), timeoutSeconds
update_scenario Update scenario fields; bumps the version when content changes
delete_scenario Delete a scenario with its steps, versions and runs
create_scenario_step Append a step: execCode, optional title and timeoutSeconds. The schema also requires order and type, but both are ignored: new steps always go last (use update_scenario_step with order to move one)
get_scenario_step Get one step
update_scenario_step Update step fields (including order to move it)
delete_scenario_step Delete a step
list_scenario_versions List a scenario's versions, newest first
get_scenario_version Get one scenario version with its steps
list_scenario_credentials List credentials assigned to a scenario (alias → credential)
add_scenario_credential Assign credential credentialId to a scenario under alias
remove_scenario_credential Remove an assignment by scenarioCredentialId (the assignment id, not the credential id)
export_scenario Export one scenario version (optional version, defaults to the latest)
import_scenario Import one scenario version; version is required (see "Versioning" in scenario.md)
import_yaml Import any mix of environments, credentials, snippets and scenarios from YAML (see "Import" in scenario.md)
export_e2e_test Export one scenario version as a standalone Playwright test project (zip, base64; optional version, defaults to the latest)

Changes to scenario content (fields and steps) create a new scenario version; credential assignments and files are not versioned.

Runs

Tool Description
run_scenario Start a run of scenario id in environmentId; optional version (defaults to the latest), saveSession, traceMode (on, retain-on-failure, off; defaults to PLAYWRIGHT_TRACE_MODE)
list_scenario_runs List runs of a scenario, optionally filtered by status
list_all_runs List runs across all scenarios, optionally filtered by status
get_scenario_run Get a run with its step runs (outputs) and logs
wait_for_scenario_run Wait until a run is pass or fail (up to 5 minutes), then return it

Snippets

Tool Description
list_snippets List snippets (orderBy/orderDir)
get_snippet Get one snippet (latest version)
create_snippet Create a snippet: alias, title, code, optional description
update_snippet Update snippet fields; bumps its version when content changes
delete_snippet Delete a snippet and all its versions
list_snippet_versions List a snippet's versions, newest first
get_snippet_version Get one snippet version

Step code runs a snippet with context.runSnippet("alias", ...args) (latest version) or context.runSnippet("alias@3", ...args) (version 3).

Scenario files

Tool Description
upload_scenario_file Upload a file to a scenario: name, base64 contentBase64, optional mimeType and expiresAt (ISO 8601)
list_scenario_files List a scenario's files (limit, offset)
get_scenario_file_content Get a file's content as base64, with metadata

Run files

Tool Description
list_run_files List files created during a run (limit, offset): downloads, failure screenshots/HTML, trace.zip
get_run_file_content Get a run file's content as base64, with metadata
delete_run_file Delete a file from a run; the stored file is removed once no scenario or run references it (also DELETE /api/v1/scenarios/:id/runs/:runId/files/:fileId and the delete button on the run detail page)

Binary content handling

File tools carry binary content as base64 strings in a contentBase64 field, with encoding: "base64" in the response. Decode it to get the original bytes.

Content for upload_scenario_file must be base64-encoded. Run files are only created by runs themselves (context.downloadFile(), failure page dumps, traces) and can't be uploaded.

Notes

  • The step type field (login, exec, sign) in create_scenario_step, update_scenario_step and import_scenario is a legacy field kept for compatibility; it's ignored, and every step runs its execCode.