# MCP tools

Use these MCP tools to discover products, read captured interface context, download assets and submit product requests. Tool names use snake_case.

Common parameters:

| Param | Meaning |
|---|---|
| `product` | Product key (for example `finance-ozon-ru`) |
| `platform` | Type ID from `list_platforms.options.platforms[].id` |
| `environment` | ID from the selected platform type’s `environments[]` |
| `version` | Capture version id |
| `page` | Route / page name inside a crawl |
| `view` | Exact stored profile key from `list_pages.views`: `desktop`, `mobile`, numbered profiles or a device label |
| `stage` | Special stage name (cookie banner, login, …) |
| `scenario` / `replay` | Recorded scenario or replay id |
| `step` | Zero- or one-based step index as stored in the manifest |
| `elementId` | Element index in the page capture element list |

Platform type and environment are separate. Both dictionaries come from
`GET /api/v1/platform/capture-options`, not from a fixed MCP list. The response
contains `platforms[]` (`id`, `label`, `environments[]`) plus `defaultPlatform`
and `defaultEnvironment`. MCP exposes this response under `list_platforms.options`.
Always select returned IDs. The following table describes current examples,
not an exhaustive client-side contract:

| Platform type | Supported environments |
|---|---|
| `desktop` | `web`, `macos`, `windows`, `linux` |
| `mobile` | `web`, `ios`, `android` |

`list_platforms.platforms[]` returns captured pairs with version counts and latest
version; `list_platforms.options.platforms[]` contains the supported options.
A supported type/environment is not necessarily captured.
`list_versions` returns each version's `platforms[]` pairs and supports filters for
`platform` and `environment`. All capture tools except `list_products` accept optional
`environment`. Pass it explicitly when a version has multiple environments; an
ambiguous request fails rather than selecting another capture. Native environments
are usable only when their capture data is available.

`list_pages.views[]` returns `{view, platform, environment}` for each stored profile;
use `view` verbatim in page and component tools. The legacy `desktop`/`mobile`
booleans describe those exact keys only. Named profiles on new captures have their
type recorded in the manifest. An older custom label without type metadata returns
`platform: null`; it remains readable by key without guessing its type from width.
The `platform` filter on `list_pages` filters pages and their returned profiles.

Migration from the old MCP contract: replace `platform="web"` with a type ID
returned by the available options and the captured environment ID. For current browser
captures, an example is `platform="desktop", environment="web"`.
`platform="web"` is rejected. `list_versions` now returns `platforms[]` pairs
instead of a single platform channel. Refresh the client tool schema after upgrading.

Example for a web desktop capture:

```json
{"product":"finance-ozon-ru","platform":"desktop","environment":"web","version":"VERSION"}
```

Use that selection with `get_platform_summary`; choose a returned page and view
with `list_pages`, then pass `environment` to the page tools.

Use structured IR as the source for content, layout, styles, and behavior. Images are for optional surface-level visual checks only. Full capture JSON is not exposed over MCP. Section bundles default to preview text; request full text for a specific section only when needed.

Suggested flow: `list_products` → `list_platforms` → `list_versions` →
`get_platform_summary`, then page or raw-file tools as needed.

## Fast reconstruction

For a known capture, call `get_reconstruction_bundle(product, version, page, view,
yStart=0, yEnd=0, environment="web")` once per requested vertical fragment (at most two viewport
heights). The default response is a small manifest with JSON `path`/`uri` and
HTML `starterPath`/`starterUri`. Consume JSON with code outside the model
conversation; copy media without image analysis. The starter provides a measured
fixed-viewport rendering of the tree. Copy it as `index.html`, with the JSON and
all `assets[].path` files in the same directory, preserving artifact filenames.

Expand each style group as `{...defaults[group], ...styles[node.style][group]}`
for `computed`, `layout`, and `effects`. Preserve node ids, parents, text, line
breaks, text runs and geometry. `captureTruncated` and `selectionComplete` expose
source limitations. Check `starterLimitations`; dynamic behavior, rotated
transforms and responsive layout require verification. You can also use `inline=true` for bounded inspection, but avoid putting complete IR in
the model context during a transfer.

JSON/HTML downloads use authenticated `/mcp-transfers/{fileName}` routes.
Download the returned files using your MCP access token and keep their filenames when using the starter.

## Catalog

| Tool | Purpose | Key params |
|---|---|---|
| `list_products` | List captured products in the archive. | — |
| `list_platforms` | Available options plus captured type/environment pairs for a product. | `product`, `environment?` |
| `list_versions` | List versions (newest first) with captured platform/environment pairs. | `product`, `platform?`, `environment?` |
| `get_platform_summary` | Summarize one version on a platform (counts and available artifacts). | `product`, `platform`, `version`, `environment?` |

## Product metadata

| Tool | Purpose | Key params |
|---|---|---|
| `get_technology_stack` | Detected stack and rendering mode (`stack.json`). | `product`, `platform`, `version`, `environment?` |
| `get_languages` | Detected languages (`languages.json`, with fallback). Capture records locales; the default crawl uses the seed locale, while `captureAllLocales=true` also captures translated routes. | `product`, `platform`, `version`, `environment?` |
| `list_product_assets` | Filtered product-wide media assets (`assets.json`): linked images and inline SVG. | `product`, `platform`, `version`, `query?`, `offset?`, `limit?`, `environment?` |
| `get_fonts` | Paginated font families and weights. Set `includeUrls` for origin webfont URLs from the site; `includeFaces` for unicode ranges. Original webfont files are stored with the capture; `resources[].path` can be read with `get_capture_asset`. | `product`, `platform`, `version`, `query?`, `offset?`, `limit?`, `includeFaces?`, `includeUrls?`, `environment?` |
| `get_font` | Resolve one family or origin URL from `get_fonts`. Returns family, origin URLs, and archived resource paths. | `product`, `platform`, `version`, `path`, `environment?` |
| `get_themes` | Color themes, active theme, and CSS tokens (`themes.json`, with page-state fallback). | `product`, `platform`, `version`, `environment?` |
| `get_route_tree` | Hierarchical route tree from `routes.json` (every discovered router/sitemap/link path, including excluded routes and other languages), falling back to captured page URLs. | `product`, `platform`, `version`, `environment?` |

## Pages

| Tool | Purpose | Key params |
|---|---|---|
| `list_pages` | Search and paginate captured routes; exact stored profiles in `views[]` and legacy desktop/mobile availability. | `product`, `version`, `platform?`, `query?`, `offset?`, `limit?`, `environment?` |
| `get_page_summary` | URL, title, viewport, heading outline, sampled layout structure (`id`/`parent`/`layout`, `structureTotal`), font family names, themes, and links. | `product`, `version`, `page`, `view`, `environment?` |
| `find_elements` | Find elements by text, content, label, href, action, CSS path, or tag. | `product`, `version`, `page`, `view`, `query`, `limit?`, `environment?` |
| `get_elements` | Bounded slice of elements: tree, layout, effects, copy, href/action, media, rects, computed. | `product`, `version`, `page`, `view`, `offset?`, `limit?`, `environment?` |
| `list_assets` | Image, background, and inline SVG assets on one page (linked URLs and `data:image/svg+xml`; not fonts). | `product`, `version`, `page`, `view`, `environment?` |
| `get_page_transitions` | Discovered links resolved to captured route names. | `product`, `version`, `page`, `view`, `offset?`, `limit?`, `environment?` |
| `get_page_motion` | Entrance (`motion.type=entrance`, view fade/rise + stagger), procedural canvas/shader fields, and real CSS animation. Idle `animation: none 0s…` is omitted. | `product`, `version`, `page`, `view`, `limit?`, `environment?` |
| `get_page_image` | Viewport WebP for a named page and view. | `product`, `version`, `page`, `view`, `environment?` |
| `get_page_stack` | Per-view `stack.json` beside a page capture, when present. | `product`, `version`, `page`, `view`, `environment?` |

## Section bundles

| Tool | Purpose | Key params |
|---|---|---|
| `get_page_outline` | Page regions and nested outline; select regions marked `bundleTarget`. | `product`, `version`, `page`, `view`, `environment?` |
| `get_section_bundle` | Content, styles and media for one selected section. | `product`, `version`, `page`, `view`, `sectionId?`, `regionIndex?`, `yStart?`, `yEnd?`, `limit?`, `textMode?`, `environment?` |
| `get_page_bundles` | Batch bundles for selected section IDs. | `product`, `version`, `page`, `view`, `sectionIds?`, `regionIndexes?`, `limit?`, `textMode?`, `environment?` |
| `get_reconstruction_bundle` | Exact bounded IR plus JSON/HTML artifact paths for programmatic transfer. | `product`, `version`, `page`, `view`, `yStart?`, `yEnd?`, `inline?`, `environment?` |

## Layered reconstruction

Start with `get_page_regions`, select a y range, then use `get_page_components` to obtain a stable `componentId`. `get_component_tree` returns only the hierarchy. Request the text, styles, typography, animation, and asset layers independently for that component. Each layer returns `total`, `offset`, `hasMore`, and at most 50 items. Component styles default to 10 groups; most other layers default to 20 items. Omit `yStart` and `yEnd` for the first viewport-height of a component, or provide both to inspect another part of a tall component. Data URLs are omitted from asset lists and fetched one at a time by ID.

| Tool | Purpose | Key params |
|---|---|---|
| `get_page_regions` | Small map of viewport-height regions and heading previews. | `product`, `version`, `page`, `view`, `environment?` |
| `get_page_components` | Visual component candidates in a y range with stable IDs and bounds. | `product`, `version`, `page`, `view`, `yStart?`, `yEnd?`, `offset?`, `limit?`, `environment?` |
| `get_component_tree` | Parent/child skeleton for one component, without content or paint. | `product`, `version`, `page`, `view`, `componentId`, `depth?`, `offset?`, `limit?`, `environment?` |
| `get_component_text` | Own text, painted lines, and text bounds. | `product`, `version`, `page`, `view`, `componentId`, `yStart?`, `yEnd?`, `offset?`, `limit?`, `environment?` |
| `get_component_styles` | Grouped layout and paint values with counts and sample IDs. `expanded=true` returns individual elements. | `product`, `version`, `page`, `view`, `componentId`, `yStart?`, `yEnd?`, `offset?`, `limit?`, `expanded?`, `environment?` |
| `get_component_typography` | Grouped font styles, counts, and sample IDs. | `product`, `version`, `page`, `view`, `componentId`, `yStart?`, `yEnd?`, `offset?`, `limit?`, `environment?` |
| `get_component_animations` | Motion and active CSS animation. | `product`, `version`, `page`, `view`, `componentId`, `yStart?`, `yEnd?`, `offset?`, `limit?`, `environment?` |
| `get_component_assets` | Asset IDs, URLs or inline-source lengths, and placement. | `product`, `version`, `page`, `view`, `componentId`, `yStart?`, `yEnd?`, `offset?`, `limit?`, `environment?` |
| `get_element_asset` | Asset path/URI, hash, MIME and size. Request optional inline bytes with `includeContent=true`, within the configured limit. | `product`, `version`, `page`, `view`, `elementId`, `includeContent?`, `environment?` |

<span id="quota-admission" />

## Usage limits

Tools that read processed page context consume one **API / MCP context read** when a call is accepted, including cached results. An accepted call still counts if the tool later fails.

Calls cannot proceed if your usage limit is reached, your subscription is inactive or usage is temporarily unavailable. Check your subscription and remaining usage in Platform account settings.

Discovery, `get_page_artifacts`, image tools, `get_capture_asset` and asset downloads do not consume context reads. `get_element_asset` reads page context and therefore consumes a context read. Context-token export usage is currently unavailable.

## Components

| Tool | Purpose | Key params |
|---|---|---|
| `list_component_candidates` | Heuristic visual component candidates (element indexes). | `product`, `version`, `page`, `view`, `limit?`, `environment?` |
| `get_component` | One candidate plus descendants (`id`/`parent` tree, else rectangle). | `product`, `version`, `page`, `view`, `elementId`, `limit?`, `environment?` |
| `get_component_image` | WebP cropped to a candidate’s visible rectangle. | `product`, `version`, `page`, `view`, `elementId`, `environment?` |

## Application inventory

| Tool | Purpose | Key params |
|---|---|---|
| `get_application_manifest` | Full route inventory, stages, scenarios, and replays. | `product`, `version`, `environment?` |

## Stages

| Tool | Purpose | Key params |
|---|---|---|
| `list_stages` | Special stages (cookie banner, login, …) and available views. | `product`, `version`, `environment?` |
| `get_stage_image` | Stage viewport WebP. | `product`, `version`, `stage`, `view`, `environment?` |

## Scenarios

| Tool | Purpose | Key params |
|---|---|---|
| `list_scenarios` | Recorded interactive scenarios for a version. | `product`, `version`, `environment?` |
| `get_scenario_manifest` | Scenario manifest (steps, views, actions, transitions). | `product`, `version`, `scenario`, `environment?` |
| `get_scenario_step` | One step: click target, pre/post state, CSS motion. | `product`, `version`, `scenario`, `step`, `environment?` |
| `get_scenario_step_image` | WebP after one scenario step. | `product`, `version`, `scenario`, `step`, `environment?` |
| `get_scenario_initial_image` | Initial desktop/mobile WebP of a scenario. | `product`, `version`, `scenario`, `view`, `environment?` |

## Version metadata and click captures

| Tool | Purpose | Key params |
|---|---|---|
| `get_version_metadata` | `version.json` metadata and artifact pointers. | `product`, `platform`, `version`, `environment?` |
| `get_click_image` | `before.webp` or `after.webp` from a click capture. | `product`, `platform`, `version`, `kind` (`before`\| `product`, `platform`, `version`, `kind`, `environment?` |

## Raw stored files

| Tool | Purpose | Key params |
|---|---|---|
| `list_archived_assets` | Paginated stored images, fonts, video, audio and 3D resources. | `product`, `platform`, `version`, `query?`, `contentType?`, `offset?`, `limit?`, `environment?` |
| `get_capture_asset` | Materialize an archived original or stored screenshot/recording; returns path/URI, hash, MIME and size without transcript bytes. Full page JSON is excluded. | `product`, `platform`, `version`, `path`, `environment?` |
| `get_page_artifacts` | Page media paths: viewport, full-page, section screenshots, scroll and interaction videos; capture-limit metadata. | `product`, `version`, `page`, `view`, `environment?` |
| `list_version_files` | List stored paths; filter by prefix or substring. | `product`, `platform`, `version`, `prefix?`, `query?`, `offset?`, `limit?`, `environment?` |
| `get_capture_image` | Read one allowlisted `.webp` by relative path. | `product`, `platform`, `version`, `path`, `environment?` |

## Replays

| Tool | Purpose | Key params |
|---|---|---|
| `list_replays` | Scenario replay runs under `capture/replays`. | `product`, `version`, `environment?` |
| `get_replay_manifest` | Replay manifest including step results. | `product`, `version`, `replay`, `environment?` |
| `get_replay_step` | One replay step `result.json`. | `product`, `version`, `replay`, `step`, `environment?` |
| `get_replay_step_image` | Replay step `after.webp`, when present. | `product`, `version`, `replay`, `step`, `environment?` |

## Element IR

`get_elements` / `find_elements` return the same element objects. This is Reconstruct's content and layout format. MCP fills missing fields on older captures.

| Field | Meaning |
|---|---|
| `id` / `parent` | Tree index in the captured list. `parent` is the nearest captured ancestor. |
| `text` | Own text of this node (no descendants). |
| `content` | Short visible copy of a container (headings built from letter spans, mixed labels). |
| `lines` | Visual wrap as painted: each entry is one line of this node (and inline descendants). Reconstruct with those breaks; do not reflow. Omitted when the node is a single line. |
| `href` | Navigation target (`https`, `mailto`, `tel`). Separate from media `source`. |
| `action` | `{ type, href, hasPopup, expanded, items }`. `type`: `navigate` / `dialog` / `menu` / `command` / `toggle`. Closed menus may only appear as `items`. |
| `layout` | `{ mode, direction, wrap, justify, align, gap, columns, padding, margin, overflow, z }`. `mode`: `stack` / `grid` / `flow` / `absolute` / `sticky` / `fixed`. |
| `effects` | `{ opacity, blur, backdropBlur, radius, transform }`. Pill radii above 9999px are stored as 999. |
| `source` | Complete paint for `img`, root `svg`, canvas, or a CSS background photo. Paint this field at `rect`; SVG child marks are not separate nodes. Inline root SVGs are also listed in `list_assets` / `list_product_assets` as `data:image/svg+xml` entries. |
| `computed` | Measured paint values, including `filter` / `backdropFilter` on new captures. |
| `className` | Hint only. |
| `pseudo` | `::before` / `::after` `content` when present. |

Capture keeps the first 2500 visible elements (`truncated` when the cap hits). Fonts are recorded in `fonts.json`, and original webfont resources are stored in the capture archive. Use `resources[].path` with `get_capture_asset` to obtain a local file or download URI. Query `get_fonts` with `includeUrls=true` for those origin URLs, and `includeFaces=true` for unicode ranges and weights. Prefer the archived font bytes. If an original is unavailable, fetch the origin URL or use an open-licensed substitute and disclose the substitution. `get_fonts` falls back to page-level font lists when the version file is empty. Themes live on the page state and in `themes.json`; `get_themes` infers light/dark/system from `html` class, `data-theme`, menu labels, and CSS custom properties when the version file is missing.

## Access and inline assets

Sign in to access published captures. Only published versions are available.

Use your MCP access token to download files from `/mcp-assets/*` and `/mcp-transfers/*`. Remote clients resolve relative download URIs against the MCP server origin and send the same Bearer token. Use the returned download URIs rather than server-side `path` or `starterPath` values, then save assets locally before referencing them in HTML or CSS.

Download links belong to the account that requested them. If a link no longer works, request a fresh reference for the published capture.

`get_element_asset(includeContent=true)` returns inline content for small assets. Larger assets are returned as downloadable references. Background and mask data images are also returned as asset references.

## Product requests

Sign in through OAuth or use a personal token with the MCP scope. You can submit requests for your account, read your own requests, and browse the same public requests shown on the Platform.

| Tool | Parameters | Result |
|---|---|---|
| `get_request_options` | none | Supported `platforms[]` for requests, from `capture-options.requestPlatforms` |
| `create_product_request` | required `requestType`, `platform`, `environment`; optional `product=""`, `url=""`, `subject=""`, `payloadJson=""` | Created pending request, `requestId`, review and safety status |
| `get_product_request` | required `requestId`; `scope="mine"` or `"public"` | Your request's review and safety details, or another user's public request fields |
| `list_product_requests` | `scope="mine"` or `"public"`, `pageSize=50`, `pageToken=""` | Requests for the selected scope, newest first, plus `nextPageToken`; maximum page size 200 |
| `wait_product_request` | required `requestId`, `knownStatus`; `waitSeconds=20` | `{request, changed, terminal, timedOut}`; waits at most 30 seconds |

For `requestType="add"`, provide a public HTTPS `url` and leave `product` empty.
The optional subject is derived from the URL when omitted. For `requestType="update"`,
provide an existing published product key; Reconstruct derives its name and source
URL. Use IDs returned by `get_request_options`: currently only Web requests are
supported, even though native captures can exist.

Requests require an eligible subscription and a safe product URL. An active duplicate request may be rejected. Submitting creates a request for review; it does not start a capture immediately. Only submit a request when the user asks for it. Request tools do not consume context reads.

Use `scope="mine"` (the default) to read your requests with their review and safety details. Use `scope="public"` to browse other users' requests; the public response omits owner identity, private request details, safety notes and review reasons. Public `payloadJson` includes only the platform and environment options. Capture jobs are not exposed in either scope.

For pagination, pass the returned `nextPageToken` as `pageToken` with the same `scope`. An empty `nextPageToken` means there are no more pages. A token from the other scope is rejected. `wait_product_request` remains limited to your own requests.

`status` is `pending`, `approved` or `rejected`. Approval and rejection complete the review, but approval does not mean captured data is ready.

`wait_product_request` returns on a status change, a completed review or a timeout. After a timeout, keep the request ID and repeat the call to continue waiting. Check capture availability separately through the catalog tools.

```json
{"requestType":"add","url":"https://example.com/","platform":"desktop","environment":"web"}
```

```json
{"requestType":"update","product":"existing-product-key","platform":"mobile","environment":"web"}
```

```json
{"requestId":"<returned UUID>","knownStatus":"pending","waitSeconds":20}
```