ui-agent-view

npm package that screenshots a web app and sends UI info to an AI agent via the Model Context Protocol (MCP).

Overview

ui-agent-view is an MCP server that gives AI agents instant visual and structural feedback about any web page. It launches a headless Chromium browser (via Playwright) and exposes the following MCP tools:

| Tool | Description | |------|-------------| | navigate | Navigate the browser to a URL and wait until the page is loaded | | screenshot | Take a screenshot of the current page (returns a base64 PNG) | | get_ui_snapshot | Return the ARIA accessibility snapshot of the current page | | get_page_info | Return metadata: URL, title, meta description, viewport | | click | Click an element identified by a CSS selector | | type_text | Type text into an input element identified by a CSS selector | | evaluate | Evaluate arbitrary JavaScript in the page context |

Requirements

• Node.js ≥ 18
• Chromium (installed automatically by Playwright – see Installation)

Installation

From npm (published package)

npm install -g ui-agent-view
npx playwright install chromium   # install the Chromium browser

As a local project dependency

npm install ui-agent-view

From source (development)

git clone <repository-url>
cd ui-agent-view
npm install
npm run build
npm install -g .   # or: sudo npm install -g .
npx playwright install chromium

Usage

As an MCP server (recommended)

Add the server to your MCP client configuration. For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ui-agent-view": {
      "command": "ui-agent-view"
    }
  }
}

Then restart Claude Desktop. The seven tools listed above will appear automatically.

CLI options

ui-agent-view [options]

Options:
  -H, --headless       Run browser in headless mode (default: true)
  --no-headless        Run browser with a visible window
  -t, --timeout <ms>   Navigation / action timeout in milliseconds (default: 30000)
  -h, --help           Show help

As a library

import { BrowserSession, createServer } from "ui-agent-view";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const session = new BrowserSession({ headless: true, timeout: 30_000 });
const server = createServer(session);
const transport = new StdioServerTransport();
await server.connect(transport);

BrowserSession API

const session = new BrowserSession({ headless: true, timeout: 30_000 });

// Navigate
const info = await session.navigate("https://example.com");
// → { url, title, description, viewport }

// Screenshot
const shot = await session.screenshot();
// → { data: "<base64 PNG>", mimeType: "image/png", width, height }

// Accessibility snapshot (ARIA YAML-like string)
const aria = await session.getAccessibilitySnapshot();

// Page metadata
const meta = await session.getPageInfo();

// Interact
await session.click("button#submit");
await session.typeText("input#email", "[email protected]");

// Evaluate JS
const result = await session.evaluate("document.title");

// Clean up
await session.close();

Development

npm install
npx playwright install chromium
npm run build   # compile TypeScript
npm test        # run unit tests
npm run lint    # type-check

License

MIT