Skip to main content
Glama
helmif

semantic-dom-mcp

by helmif

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
QA_MCP_TEAM_NAMENoOptional team name used in the write_playwright_test prompt.QA
QA_MCP_ALLOWED_HOSTSYesComma-separated hostnames the server may navigate to. Navigation is denied by default. Supports host, host:port, and *.domain entries.
QA_MCP_STORAGE_STATENoOptional path to a Playwright storageState JSON for pre-authenticated staging sessions.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": true
}
prompts
{
  "listChanged": true
}
resources
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
extract_semantic_domA

Navigate to a staging URL and return factual Semantic JSON of all interactive/test-relevant elements with Playwright-native locators and live state. Use this before writing any Playwright test so selectors are real, not guessed.

extract_semantic_dom_afterA

Like extract_semantic_dom, but first performs a short DECLARED list of actions (fill/click/press/select/goto/wait) in the main frame, then returns Semantic JSON of the RESULTING state. Use it for post-interaction UI a plain snapshot cannot see: success/error toasts, validation messages, opened dialogs. Derive action locators from a prior extract_semantic_dom call. The page must remain on allowlisted hosts after the actions, or nothing is extracted. Uniqueness reflects capture time — accumulating UI (chat threads, lists) can multiply matches later. The result's observed block lists navigations, xhr/fetch requests (method, path, status), console errors, dialogs and popups seen while the actions ran — use them for waitForURL/waitForResponse.

list_framesA

Diagnostic: navigate to a URL and return its frame tree (frame_path, url, name, same_origin, reachable). Useful for debugging cross-origin iframe boundaries before extraction.

check_authA

Diagnostic: navigates with the configured QA_MCP_STORAGE_STATE session and reports whether the page bounced to a login-looking path (session likely expired). Use when extractions unexpectedly return login forms instead of the requested page.

extract_outlineA

The page as a MAP, a few thousand characters: landmark regions (header/nav/main/forms/tables/lists/dialogs) each with a selector you can pass as scope to extract_semantic_dom / session_extract, structured tables (headers, row identity for getByRole('row', { name }), cells) and open dialogs (label/value fields), plus current alert text. Start here on any page you have not seen; then extract one region.

verify_locatorsA

Count every given Playwright expression against the live page (same engine that verified the extraction). Use after writing a test: paste the spec's getBy*/locator expressions and get matches, uniqueness, and the first matched element per expression, plus a summary. Also the drift check to run in CI against a page.

get_conventionsA

The team's Playwright test-writing conventions as text (same content as the write_playwright_test prompt), for clients that do not surface MCP prompts.

session_openA

Open a persistent browser session at a staging URL for a MULTI-STEP flow (login → cart → checkout). The page stays open across calls: use session_act to perform declared actions and session_extract to snapshot or diff, then session_close. Fresh context per session (storageState applied if configured). Sessions expire after an idle TTL and are capped in number; the allowlist is re-checked after every step.

session_actA

Perform a short DECLARED action list (fill/click/press/select/goto/wait, max 20) in an open session's main frame. Returns the page's resulting URL/title and observed: main-frame navigations, xhr/fetch requests (method, path, status — bodies and query strings never captured), console errors, dialogs (auto-dismissed) and popups (recorded, closed). These are the facts for waitForURL/waitForResponse. Derive action locators from a prior extraction (paste its playwright expression). Pass then_extract to get the diff (or a scoped extraction / outline) in the same call. If the actions leave the allowlisted hosts the session is closed and nothing further is extracted.

session_extractA

Snapshot the CURRENT state of an open session as Semantic JSON (same shape as extract_semantic_dom, plus snapshot_id). Pass diff_against: 'previous' (or a snapshot_id) to receive only what changed: added nodes (new toasts/dialogs/fields), removed nodes, changed properties (value, is_disabled, aria_invalid, described_by…) and the behavior observed in between — far smaller than a full re-extraction and exactly the assertion list for the step. Diff identity: frame + test-id, else id, else placeholder, else tag+role+accessible name (+ document-order index); a renamed node with no stable attribute shows as removed + added; primary_locator.playwright changes say which locator is valid in which state.

session_verify_locatorsB

verify_locators against an open session's current page (after acting, without a fresh navigation).

session_closeA

Close an open session and release its browser context. Always call this when the flow is done. Idempotent: closing an unknown or already-closed id succeeds with was_open: false.

session_listA

Diagnostic: list open sessions (id, URL, expiry, counts) — recover a session id after losing context.

Prompts

Interactive templates invoked by user choice

NameDescription
write_playwright_testTeam-standard prompt for writing a Playwright test in TypeScript from a Semantic DOM extraction or a session diff. Ensures every engineer gets identical conventions: locator usage, frame chaining, structure, assertions, and single-snapshot state honesty.

Resources

Contextual data attached and managed by the client

NameDescription
playwright-conventionsThe team's non-negotiable Playwright test-writing conventions (read-only).

TDQS

A3.9/5.0

Scored across 13 tools

Disambiguation4/5

The set has a clear two-tier structure (one-shot extraction/verification vs. persistent session tools), and descriptions carefully separate them. However, extract_semantic_dom_after overlaps conceptually with the session_open/session_act/session_extract flow, and extract_semantic_dom vs session_extract require reading descriptions carefully to pick correctly.

Naming Consistency4/5

Almost everything is consistent snake_case verb_noun, and the session_* prefix gives a clean, predictable grouping. Minor deviation: extract_semantic_dom_after uses a temporal suffix rather than a distinct verb, which slightly breaks the pattern.

Tool Count5/5

13 tools is well within the sweet spot and each one earns its place, covering extraction, diagnostics, verification, conventions, and full session lifecycle without filler.

Completeness5/5

The surface covers the full Playwright test-authoring workflow: page mapping, snapshot extraction, post-interaction observation, locator verification, auth/frame diagnostics, conventions, and end-to-end session management with open/act/extract/verify/close/list. No obvious dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues