DOM Resources

@frontmcp/react provides two utility functions for reading DOM elements as MCP-compatible resources. These are useful when AI agents need to inspect page content.

readDomById

Reads a DOM element by its id attribute and returns its HTML, text content, and tag name.

import { readDomById } from '@frontmcp/react';

const result = readDomById('main-content');
// {
//   contents: [{
//     uri: 'dom://byId/main-content',
//     mimeType: 'application/json',
//     text: '{"outerHTML":"<div id=\"main-content\">...</div>","textContent":"...","tagName":"div"}'
//   }]
// }

Return Values

Scenario	mimeType	text
Element found	`application/json`	JSON with `outerHTML`, `textContent`, `tagName`
Element not found	`text/plain`	`'Element with id "..." not found'`
No DOM (SSR)	`text/plain`	`'DOM not available (not in a browser environment)'`

readDomBySelector

Reads all elements matching a CSS selector.

import { readDomBySelector } from '@frontmcp/react';

const result = readDomBySelector('.card');
// {
//   contents: [{
//     uri: 'dom://selector/.card',
//     mimeType: 'application/json',
//     text: '[{"outerHTML":"...","textContent":"...","tagName":"div"}, ...]'
//   }]
// }

Return Values

Scenario	mimeType	text
Elements found	`application/json`	JSON array of `{ outerHTML, textContent, tagName }`
No matches	`text/plain`	`'No elements found matching "..."'`
Invalid selector	`text/plain`	`'Invalid selector: "..."'`
No DOM (SSR)	`text/plain`	`'DOM not available (not in a browser environment)'`

Use Case: AI Agent Page Inspection

import { create } from '@frontmcp/sdk';
import { readDomById, readDomBySelector } from '@frontmcp/react';

const server = await create({
  info: { name: 'browser-app', version: '1.0.0' },
  resources: [
    {
      uri: 'dom://byId/{id}',
      name: 'DOM Element by ID',
      read: ({ id }) => readDomById(id),
    },
    {
      uri: 'dom://selector/{selector}',
      name: 'DOM Elements by Selector',
      read: ({ selector }) => readDomBySelector(decodeURIComponent(selector)),
    },
  ],
});

An AI agent can then call readResource('dom://byId/login-form') to inspect a form, or readResource('dom://selector/.error-message') to check for error states on the page.

When using readDomBySelector with complex selectors (e.g., div > .my-class), the selector is embedded in the URI path. Use encodeURIComponent when constructing the URI to avoid parsing issues: dom://selector/${encodeURIComponent('div > .my-class')}.

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

readDomById

Return Values

readDomBySelector

Return Values

Use Case: AI Agent Page Inspection

​readDomById

​Return Values

​readDomBySelector

​Return Values

​Use Case: AI Agent Page Inspection

readDomById

Return Values

readDomBySelector

Return Values

Use Case: AI Agent Page Inspection