Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@semantic-dom-mcp extract the checkout page and write a success-path test"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local MCP server (stdio, Node.js + TypeScript) that drives a real Chromium browser via Playwright to extract a live page's DOM into compact, factual Semantic JSON with Playwright-native locators — so AI-generated Playwright tests are consistent across the whole QA team, not just accurate.
Same page → same extraction → same conventions → same test style, regardless of who runs it.
Evidence: benchmark/RESULTS.md — on real pages the Semantic JSON is 92–97% smaller than the raw DOM an agent would otherwise consume, with every locator uniqueness-verified by Playwright's engine and byte-identical output across runs. Docs: How it works (deep dive) · Team guide (setup + connecting your agent) · Benchmark methodology · Roadmap
No clone, no build — the package is on npm. One-time browser setup (installs the Chromium build matching the package's bundled Playwright):
npx -y -p semantic-dom-mcp playwright install chromiumThen add the server to your MCP client:
{
"mcpServers": {
"semantic-dom": {
"command": "npx",
"args": ["-y", "semantic-dom-mcp"],
"env": {
"QA_MCP_ALLOWED_HOSTS": "staging.yourapp.internal,staging.admin.internal",
"QA_MCP_STORAGE_STATE": "./.auth/staging.json"
}
}
}
}That's the whole setup. Verify by asking your agent to list its MCP tools — you should
see extract_semantic_dom. See docs/GUIDE.md for per-client config
locations (Claude Code, Claude Desktop, Cursor, Windsurf), authenticated staging, and
troubleshooting. To run from a clone instead (contributors), see Development below.
Related MCP server: Playwright MCP Server
Ask your agent: "extract the checkout page and write a success-path test."
The agent calls extract_semantic_dom({ url }) — the server navigates a real Chromium
page, runs the extractor inside the page, and returns Semantic JSON: every interactive node
with a ready-to-paste Playwright locator, uniqueness verified by Playwright's own engine.
The agent uses the write_playwright_test prompt (scenario + the JSON), which injects the
team conventions.
The result is a Playwright test in team style, grounded in real locators — never guessed ones.
Kind | Name | Purpose |
Tool |
| Extract a URL into Semantic JSON ( |
Tool |
| Same, but first runs a short declared action list (fill/click/press/wait, max 20) in the main frame and snapshots the resulting state — for toasts, validation errors, opened dialogs. Refuses to extract if the actions navigated off the allowlist. |
Tool |
| Diagnostic: navigates with the configured storageState and reports whether the session bounced to a login-looking page (expired auth shows up as an answer, not a mystery). |
Tool |
| Diagnostic frame tree with same-origin/reachability classification. |
Prompt |
| Team-standard test-writing prompt ( |
Resource |
| The same team conventions as read-only text. |
Errors (navigation failure, denied host, missing selector) come back as structured JSON in the tool result — the agent can react instead of crashing.
Variable | Meaning |
| Required. Comma-separated hostnames the server may navigate to. Navigation is denied by default. Supports |
| Optional path to a Playwright |
| Optional team name used in the |
Tool inputs are untrusted (they arrive via an LLM): strict schemas (additionalProperties: false),
http/https only, host allowlist enforced before any navigation.
extract_semantic_dom only reads the DOM — it never clicks, submits, or mutates the page.
The one sanctioned exception is extract_semantic_dom_after, which executes only an explicit,
bounded, schema-validated action list, never logs fill values, and aborts without extracting if
the page leaves the allowlisted hosts.
No network egress beyond navigating to the target URL. No telemetry. Page contents are never logged (stderr carries only high-level events) and are not stored beyond the current call.
Snapshot honesty: the JSON is a single moment. A disabled submit button is reported
is_disabled: true with a note — the conventions instruct the model to write the interactions
that change state, not to assume it stays disabled.
Hidden nodes are included and flagged is_visible: false (tests often assert hidden-ness);
pass include_hidden: false to drop them (the count dropped is noted, never silent).
Open shadow DOM is traversed and flagged in_shadow — locators pierce it natively, so no
>>>/::shadow CSS is ever emitted. Closed shadow roots appear as shadow_boundary
marker nodes (detected via pre-navigation attachShadow instrumentation; closed roots created
by declarative shadow DOM parse before scripts run and cannot be detected).
Same-origin iframes are extracted per-frame with frame_path set (chain frameLocator()
in that order). Cross-origin iframes are recorded as opaque cross_origin_frame nodes with
URL/name only — their DOM is never touched.
Notification & dialog surfaces (role="alert", role="status", dialogs) are extracted like
interactive nodes. When a toast library keeps the live region empty and renders the message in a
sibling (a common pattern across UI libraries), the message text is pulled from the enclosing
container and flagged. For UI that renders late after an interaction, wait_selector_after on
extract_semantic_dom_after waits deterministically instead of guessing settle_ms. Since those ARIA roles take names from the author (not contents), their role
locator is getByRole('alert') — or with the aria-label name when one exists. For UI that only
appears after an interaction (login-success toast), use extract_semantic_dom_after.
JS-click cards (product tiles with no anchor/role/test-id) are invisible to the factual
rules by design — pass include_click_targets: true to include cursor-pointer boundary
elements with content, flagged as heuristic and located by their heading text.
Links carry href (schema 1.1) so agents can discover which page to extract next without
scraping. Framework-generated ids (rc_select_*, React useId, Radix, MUI...) are detected
and demoted to last-resort with a note — they change between builds and must never be primary.
viewport: "mobile" (375×812, touch) snapshots responsive states; visibility flags reflect
the active media queries.
Truncation is loud: max_nodes / depth caps set truncated: true plus a note. Non-unique
locators carry is_unique: false and disambiguation guidance.
git clone https://github.com/helmif/semantic-dom-mcp.git && cd semantic-dom-mcp
npm install
npx playwright install chromium
npm run dev # run the server over stdio via tsx
npm run typecheck # tsc --noEmit (strict)
npm test # Vitest suites against real fixture pages in headless Chromium
npm run build # compile to dist/ (clients can then use "command": "node", "args": ["<path>/dist/index.js"])Repo layout: src/index.ts (bootstrap) · src/server.ts (MCP surface) · src/browser.ts
(Playwright layer + orchestration) · src/extractor/ (in-page engine + locator resolution) ·
src/types.ts (frozen v1 contract) · src/conventions.ts (single source of team conventions).
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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page whose frame tree to report. Must be http/https and allowlisted. | |
| wait_for | No | Navigation wait condition. | networkidle |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: navigates with QA_MCP_STORAGE_STATE session, checks for login-looking path, reports result. With no annotations, the description fully informs about nondestructive diagnostic nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'Diagnostic', no wasted words. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the description covers all needed aspects: function, when to use, and behavioral traits. No missing details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters comprehensively (100%). The description adds context about session usage and the purpose of the URL parameter, providing incremental value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it navigates with a session and checks for login page bounce. It distinguishes itself from sibling extraction tools by being a diagnostic for session expiration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies use case: 'when extractions unexpectedly return login forms instead of the requested page.' No ambiguity about when to apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to extract. Must be http/https and on an allowlisted host. | |
| viewport | No | Viewport preset — 'mobile' is 375x812 with touch, for responsive states. | desktop |
| wait_for | No | Navigation wait condition. | networkidle |
| max_nodes | No | Cap on extracted nodes; truncation is flagged, never silent. | |
| wait_selector | No | Optional selector to await before extracting (for SPA content). | |
| include_hidden | No | Keep hidden nodes flagged rather than dropping them. | |
| include_click_targets | No | Opt-in heuristic: also include cursor:pointer elements with content that match no other rule (JS-click product cards without anchors/roles/test-ids). Heuristic nodes carry a context_note. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It mentions navigation to a staging URL, returning semantic JSON, and flags truncation behavior. However, it does not explicitly state that the operation is read-only or address potential side effects, authorization needs, or rate limits. The description adds some behavioral context but lacks completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences. The first sentence delivers the core purpose and key output details, and the second provides clear usage guidance. Every sentence serves a purpose, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters with full schema coverage and no output schema or annotations, the description covers the tool's purpose, usage timing, and parameter behaviors well. It lacks details about the exact JSON output structure and error handling, but the overall context is sufficient for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by providing behavioral details, such as truncation being flagged not silent (max_nodes), mobile viewport size and touch context (viewport), SPA content hint (wait_selector), and heuristics for cursor:pointer elements (include_click_targets). This elevates the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Navigate to a staging URL and return factual Semantic JSON') and clearly identifies the resource (interactive/test-relevant elements with Playwright-native locators). It also distinguishes from the sibling tool 'extract_semantic_dom_after' by indicating this is for use before writing tests, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this before writing any Playwright test so selectors are real, not guessed.' This provides clear context, though it does not explicitly mention when not to use it or name alternative tools (e.g., extract_semantic_dom_after) as exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Like extract_semantic_dom, but first performs a short DECLARED list of actions (fill/click/press/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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page to extract. Must be http/https and on an allowlisted host. | |
| actions | Yes | Declared actions executed in order in the MAIN frame after navigation. | |
| viewport | No | Viewport preset — 'mobile' is 375x812 with touch, for responsive states. | desktop |
| wait_for | No | Navigation wait condition. | networkidle |
| max_nodes | No | Cap on extracted nodes; truncation is flagged, never silent. | |
| settle_ms | No | Wait after the last action before snapshotting (for toasts/animations). | |
| wait_selector | No | Optional selector to await before extracting (for SPA content). | |
| include_hidden | No | Keep hidden nodes flagged rather than dropping them. | |
| wait_selector_after | No | Selector to await (visible) AFTER the actions, before snapshotting — deterministic wait for late-rendering toasts/modals instead of guessing settle_ms. | |
| include_click_targets | No | Opt-in heuristic: also include cursor:pointer elements with content that match no other rule (JS-click product cards without anchors/roles/test-ids). Heuristic nodes carry a context_note. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses that uniqueness reflects capture time and that accumulating UI can multiply matches later. It also mentions the allowlist restriction. It does not explicitly describe side effects of actions, but the actions are declarative and the tool focuses on extraction, so the transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, each adding value. It front-loads the comparison to extract_semantic_dom and efficiently conveys the tool's purpose and key constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, no output schema), the description explains the core functionality, use cases, and behavioral nuances. It implies the return format is the same as extract_semantic_dom, which is sufficient. Minor gaps like explicit return format details are covered by the sibling reference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds limited value beyond the schema. It does provide context for the actions parameter (derive from prior extraction, main frame). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool is like extract_semantic_dom but performs actions first and returns Semantic JSON of the resulting state. It specifies use cases like seeing success/error toasts, validation messages, and opened dialogs, which distinguishes it from the sibling extract_semantic_dom.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (for post-interaction UI) and provides guidance on deriving action locators from a prior extract_semantic_dom call. It also notes the allowlisted host requirement. However, it does not explicitly state when not to use it or compare to other siblings like check_auth or list_frames.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The page whose frame tree to report. Must be http/https and allowlisted. | |
| wait_for | No | Navigation wait condition. | networkidle |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It describes the main action (navigate and return frame info) but does not mention side effects, auth requirements, rate limits, or error handling. The word 'diagnostic' hints at safety but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'Diagnostic', no filler. Every word adds value. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple diagnostic tool with 2 parameters and no output schema, the description covers the action, return fields, and usage hints. It lacks detail on error cases or empty frame trees, but is sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by specifying that the URL must be http/https and allowlisted, and lists the return fields. This extra context improves understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: navigate to a URL and return its frame tree with specific fields. It is distinct from sibling tools (check_auth, extract_semantic_dom, extract_semantic_dom_after) which focus on authentication or extraction, not frame diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes context for when to use it ('before extraction') and labels it as a diagnostic tool. It implies alternatives by mentioning extraction in the context, but does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.4.0check_authextract_semantic_domextract_semantic_dom_afterlist_framesEach tool serves a distinct purpose: auth check, initial DOM extraction, post-action DOM extraction, and frame listing. The two extraction tools are clearly differentiated by the presence of actions, reducing confusion.
Names follow a verb_noun or verb_phrase pattern (check_auth, list_frames, extract_semantic_dom). The 'extract_semantic_dom_after' suffix is a minor deviation but is logically derived from the base name.
With exactly 4 tools, the server is well-scoped for its purpose of semantic DOM extraction and diagnostics. No tool feels extraneous, and the count is ideal for the domain.
The tool set covers core use cases: verifying session validity, extracting initial DOM, extracting DOM after interactions, and exploring frame structure. There are no obvious gaps for the intended workflow of generating Playwright tests.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Headless browser primitives for AI agents when sites need real JS rendering.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/helmif/semantic-dom-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server