query_selector
Extract element information from web pages using CSS selectors to locate and retrieve specific content during browser automation.
Instructions
Get information about an element matching a CSS selector
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector for the element | |
| tabId | No | Tab ID to operate on (uses active tab if not specified) |
Implementation Reference
- src/tools/content.ts:99-149 (handler)Handler function that executes the query_selector tool: retrieves the page, queries for the CSS selector, checks if element exists, and if so, extracts tag name, truncated text content, all attributes, and bounding box coordinates.
async ({ selector, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; try { const element = await page.$(selector); if (!element) { return handleResult(ok({ exists: false, selector, })); } const info = await element.evaluate((el) => { const rect = el.getBoundingClientRect(); const attributes: Record<string, string> = {}; for (let i = 0; i < el.attributes.length; i++) { const attr = el.attributes[i]; if (attr) { attributes[attr.name] = attr.value; } } return { tagName: el.tagName.toLowerCase(), textContent: el.textContent?.slice(0, 1000) ?? '', attributes, boundingBox: { x: rect.x, y: rect.y, width: rect.width, height: rect.height, }, }; }); return handleResult(ok({ exists: true, selector, ...info, })); } catch (error) { return handleResult(err(normalizeError(error))); } } - src/tools/content.ts:95-150 (registration)Registration of the 'query_selector' tool on the MCP server within registerContentTools, including name, description, schema, and handler.
server.tool( 'query_selector', 'Get information about an element matching a CSS selector', querySelectorSchema.shape, async ({ selector, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; try { const element = await page.$(selector); if (!element) { return handleResult(ok({ exists: false, selector, })); } const info = await element.evaluate((el) => { const rect = el.getBoundingClientRect(); const attributes: Record<string, string> = {}; for (let i = 0; i < el.attributes.length; i++) { const attr = el.attributes[i]; if (attr) { attributes[attr.name] = attr.value; } } return { tagName: el.tagName.toLowerCase(), textContent: el.textContent?.slice(0, 1000) ?? '', attributes, boundingBox: { x: rect.x, y: rect.y, width: rect.width, height: rect.height, }, }; }); return handleResult(ok({ exists: true, selector, ...info, })); } catch (error) { return handleResult(err(normalizeError(error))); } } ); - src/schemas.ts:122-125 (schema)Zod input schema for query_selector tool defining required CSS selector and optional tabId.
export const querySelectorSchema = z.object({ selector: selectorSchema, tabId: tabIdSchema, });