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

117 lines
6.7 KiB
Markdown

# 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](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](scenario.md)) |
| `import_yaml` | Import any mix of environments, credentials, snippets and scenarios from YAML (see "Import" in [scenario.md](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`.