semantic-dom-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| QA_MCP_TEAM_NAME | No | Optional team name used in the write_playwright_test prompt. | QA |
| QA_MCP_ALLOWED_HOSTS | Yes | Comma-separated hostnames the server may navigate to. Navigation is denied by default. Supports host, host:port, and *.domain entries. | |
| QA_MCP_STORAGE_STATE | No | Optional 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
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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 |
| 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 |
| 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 |
| session_extractA | Snapshot the CURRENT state of an open session as Semantic JSON (same shape as extract_semantic_dom, plus |
| 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
| Name | Description |
|---|---|
| write_playwright_test | Team-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
| Name | Description |
|---|---|
| playwright-conventions | The team's non-negotiable Playwright test-writing conventions (read-only). |
TDQS
Scored across 13 tools
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.
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.
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.
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.