yatt-ts
Yatt-ts is an MCP server that gives AI clients full control over the YATT UI-testing toolbox.
Manage tests: create, read, update, delete, rename, duplicate, validate, list, and export as Playwright/Jest specs.
Run tests headlessly: execute saved tests or data-driven dataset runs, with per-step timeouts, browser selection, and saved HTML/JSON reports.
Control a live browser: open/close/status, navigate, evaluate JS, run YATT steps, click at coordinates, scroll, take viewable PNG previews, and manage tabs.
Handle sessions: save, list, delete, and restore cookies/localStorage for authenticated flows.
Work with visual baselines: list and retrieve reference images for visual asserts.
Query the app database read-only: run SELECT/WITH/EXPLAIN/PRAGMA SQL via SQLite, Postgres, or an in-process provider.
Inspect the server: ping health, schema docs, report list/get/delete, and test library resources.
Configure the server: stdio or HTTP transport, bearer auth, permission policies (read-only/allow/deny), session persistence, retention, paths, locale, and engine options.
Embed it: expose MCP over your own HTTP framework or use the programmatic API for custom integrations.
Allows running read-only SQL queries (SELECT, WITH, EXPLAIN, PRAGMA) against a PostgreSQL database, with configurable connection parameters, SSL support, and optional password providers.
Allows running read-only SQL queries against a SQLite database file, supporting file paths or file: URLs.
Click on "Deploy 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., "@yatt-ts run my login test and show me the report"
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.
yatt-ts
Your own highly configurable YATT MCP server, as an npm library.
yatt-ts spins up a complete Model Context Protocol server that gives AI clients (Claude, Cursor, your own agents) full access to YATT — a UI-testing toolbox with 35 tools: a test library (create/edit/validate), a headless Playwright runner with HTML reports, a live Chromium browser with screenshots the AI can actually see, session management, visual baselines, spec export, and read-only SQL against your app's database.
Everything is configurable from a single typed config object: transport (stdio/HTTP), bearer auth, per-tool permissions, session persistence, artifact paths, browser defaults, retention. Strict validation fails fast and names the offending key — never a silent misconfiguration.
Runtime: Node ≥ 22.5 or Bun 1.4+ (dual-runtime, including the SQLite layer)
Engine: vendored Playwright Chromium, headless-first (screenshots always available), auto-downloaded on first use
License: MIT
Install
npm install yatt-ts
# or
bun add yatt-tsNode 22.5+ or Bun 1.4+. On first browser use, Chromium (and chromium-headless-shell) is downloaded automatically — no extra setup.
Related MCP server: MCP Playwright Server
Quickstart (30 seconds)
Stdio server, zero config — the data root is your current working directory:
import { createYattServer } from 'yatt-ts';
const server = await createYattServer(); // all defaults (C28: zero-config works)
await server.start(); // speaks MCP over stdioHTTP + bearer token — connect remote clients over the network:
import { createYattServer, generateToken } from 'yatt-ts';
const server = await createYattServer({
http: { enabled: true, port: 3191, host: '127.0.0.1' },
auth: { token: generateToken() }, // or your own string (min 16 chars) / tokenHash
});
await server.start();
// Clients send: Authorization: Bearer <token> (401 otherwise; token never logged)Or from the terminal (no code at all):
npx yatt-ts --version
npx yatt-ts --http --port 3191 --token my-secret-token-16ch
npx yatt-ts --read-only --root /path/to/yatt-data --locale es--http without a token generates a crypto-secure ephemeral one and prints it once to stderr.
Point your MCP client at it (Claude Desktop / Cursor style):
{
"mcpServers": {
"yatt": { "command": "npx", "args": ["yatt-ts", "--root", "/path/to/yatt-data"] }
}
}What you get
35 MCP tools —
ping,schema, test CRUD + validate/rename/duplicate/export (test_*), headless runner (test_run,test_run_dataset), reports (report_*), live browser (browser_*,tab_*,session_*), baselines (baseline_*), and read-only SQL (db_query).Resources:
yatt://schema,yatt://tests/{name},yatt://reports/{name}.Prompts: 5 ready-made work prompts, in English or Spanish.
Real browser evidence:
browser_previewreturns a PNG the AI can see; failed steps attach an evidence screenshot.
Configuration
Everything is optional; omitted keys take defaults. Unknown keys are rejected with an error that names the key.
Domain | Keys (default) | What it controls |
|
| Where every artifact lives. Relative paths resolve against |
|
| Streamable HTTP transport instead of stdio. |
|
| Bearer auth for HTTP. Plain token (≥16 chars) or its SHA-256 hex digest — never both. stdio ignores auth. |
|
| Mutating tools denied with an announced reason; denied tools stay visible ('error') or vanish from listings ('hide'); |
|
|
|
|
| Opt-in report cleanup. Absent = never deletes anything. |
|
| The vendored Playwright engine. |
|
| Headless-first with full screenshot support; floating toolbar OFF unless you turn it on. |
|
| Headless run defaults. |
|
| The app-under-test database for |
|
| Server diagnostics go to stderr (never the protocol channel). |
|
| Language for prompts, tool descriptions, and messages. |
Invalid values (wrong type, impossible path, both token forms, …) throw ConfigError at boot naming the exact key.
App database provider (embedding)
With appDb: { type: 'provider', provider } the db_query tool executes in your process through your own function — typically a live TypeORM/NestJS DataSource (its pool, its credentials, its network position). Works with engine: { enabled: false }:
const yatt = await createYattServer({
appDb: { type: 'provider', provider: (sql) => dataSource.query(sql) },
});The provider returns the full rows array (TypeORM's native shape); yatt-ts applies the read-only guard (SELECT/WITH/EXPLAIN/PRAGMA — rejected statements never reach your function), the 30 s timeout and the 200-row output cap (totalRows keeps the real count). The per-call db connection override does not apply in this mode.
Timeout caveat: when the 30 s timeout fires, yatt-ts stops waiting but cannot cancel the query already handed to your provider — JavaScript offers no way to abort the host call, so the statement keeps running on your pool. Set your own limit host-side (e.g. PostgreSQL statement_timeout or an equivalent pool-level query timeout) so abandoned queries cannot pile up.
Still use a read-only DB role — yatt-ts guards the SQL, but the privilege level is yours (defense in depth).
Honest boundary: the headless runner's
db_assert/db_waitsteps execute in the engine child process, which cannot call a host function. With a provider-only config those runs are rejected with a clear message; configure sqlite/postgresappDbfor them. A one-line notice is logged at startup.Full NestJS + TypeORM recipe:
examples/10-typeorm-provider.ts.
Security notes
CORS is permissive by default.
http.cors.originsdefaults to['*'], mirroring the base YATT tool. For untrusted environments, restrict it to an explicit origin list in your config.test_runvariable overrides travel as CLI arguments to the one-shot engine process (e.g.--override token=…), matching the base-tool behavior. They are visible in the host process list (e.g.ps) for the duration of the run — avoid secret values in overrides, or contribute env-based override passing later.
Recipes
Permission, session, retention, and connection examples live in examples/ — each one is a runnable, self-contained file:
01-zero-config-stdio · 02-http-with-token · 03-read-only-server · 04-deny-list · 05-ephemeral-sessions · 06-custom-paths · 07-report-retention · 08-appdb-postgres-object · 09-nestjs-mcp-handler · 10-typeorm-provider
Embed in your HTTP framework (NestJS)
Instead of the built-in HTTP server (http.enabled), you can expose the MCP endpoint at any route of your own HTTP framework — NestJS, Express, Fastify, plain node:http — with createMcpHttpHandler:
import { createYattServer, createMcpHttpHandler } from 'yatt-ts';
const yatt = await createYattServer({ engine: { enabled: false } });
const mcp = createMcpHttpHandler(yatt);
// Any framework route (Nest controller, Express router, …):
app.use('/api/mcp', (req, res) => mcp.handle(req, res, req.body));When to use which:
http.enabledfor a standalone MCP endpoint you own end-to-end; the handler when an existing backend should host it (shared middleware, TLS, deployment).Lifecycle is yours: do NOT call
yatt.start()in handler mode (the handler connects the MCP server per session itself); on teardown callmcp.close()first, thenyatt.shutdown(). In a Nest app callapp.enableShutdownHooks()— without it Nest never firesonModuleDestroyon SIGINT/SIGTERM, so graceful teardown never runs.Auth via host guards: no auth by default — your framework's guards/middleware rule. Or pass
authenticate: (req) => boolean(false→ 401 JSON, throw → controlled 500). Exception: if you configuredauth.token/auth.tokenHashon the server itself, the handler wires it as the default bearer check (and logs a one-line notice) unless you pass your ownauthenticate.Body size: the raw-request path rejects bodies over 2 MB with
413(maxBodyBytesoption to change it). Bodies pre-parsed by your framework bypass the cap — your parser owns that limit.One client at a time per server (single browser engine): when a second client initializes, the stale session is evicted (new-wins).
Full NestJS recipe (controller + service + bearer guard):
examples/09-nestjs-mcp-handler.ts.
Public API
import {
createYattServer, // (config?) → { server, ctx, start(transport?), shutdown() }
createMcpHttpHandler, // mount the MCP endpoint inside your own HTTP framework
resolveConfig, // validate + apply defaults yourself
ConfigError, // named-key config failures
generateToken, // crypto-secure 64-hex token
verifyToken, hashToken, redact,
evaluateToolAccess, isToolListed,
applyReportRetention,
Store, openDatabase,
VERSION,
} from 'yatt-ts';start() with no argument picks the transport from config (HTTP when http.enabled, stdio otherwise) and handles SIGINT/SIGTERM; pass an MCP Transport (e.g. InMemoryTransport) to embed the server in your own process and own the lifecycle yourself. shutdown() is idempotent and always safe to call.
CLI
yatt-ts [serve] [--http] [--port N] [--host H] [--root PATH]
[--token T | --token-hash HEX64] [--read-only] [--locale en|es]
[--no-engine] [--allow-tool NAME] [--deny-tool NAME]
[--deny-behavior error|hide]
yatt-ts --version | --help--http without --token/--token-hash generates an ephemeral token and prints it once to stderr. App-database credentials are never accepted on the command line — configure them programmatically (D22).
Engine notes
Chromium only, headless-first.
browser_openruns headless by default (D10); screenshots/preview work exactly the same. Passheadless: falsewhen a human needs to watch.Auto-download. First browser use installs
chromium+chromium-headless-shellvia the bundled Playwright. Disable withengine.autoInstallBrowser: false.Floating toolbar OFF by default (D11). Enable with
browser.toolbarInjection: true.Runtime selection. The engine child process resolves
bun → nodeautomatically (override:engine.runtime). One browser at a time — engine calls are serialized by design (single concurrent MCP client).No network needed for the server itself; the only download is the browser on first use.
Requirements
Node ≥ 22.5 (uses the built-in
node:sqlite) or Bun ≥ 1.4 (bun:sqlite)~300 MB disk for the auto-downloaded Chromium
Development
npm run build # tsc → dist/ (+ executable bin)
npm test # vitest unit suite
npm run typecheck # src + test + examples
YATT_TS_E2E=1 npx vitest run test/e2e # real-Chromium e2e smokes
node test/e2e/install.mjs # npm pack + fresh-consumer install proofLicense
Available Tools
35 toolsbaseline_getC
Returns a reference image as PNG (for visual comparison).
Inputs: name (required).
baseline_listA
Lists the saved reference images (visual asserts).
Inputs: no named parameters.
browser_click_atA
Click at viewport coordinates (x, y in CSS pixels); returns the resolved selector of the clicked element (data-testid → id → CSS path) plus the updated preview. Prefer browser_run_step with a selector for reproducible steps.
Inputs: x (required), y (required).
browser_closeA
Closes the controlled browser (clears the browser session).
Inputs: no named parameters.
browser_conditionA
Checks whether an element exists in the page (or whether a variable condition holds); waits for the condition with optional polling (timeoutMs > 0 repeats the check until true or the timeout expires). Returns {value, elapsedMs}.
Inputs: value, selector, timeoutMs, intervalMs.
browser_evalA
Executes arbitrary JavaScript in the current page and returns the value (useful to inspect the DOM, read texts, count elements, try selectors).
Inputs: expression (required).
browser_openB
Open (or reopen) the controlled browser. headless=true by default; visible only when you need to point by hand.
Inputs: url, browser, session, headless, +3 more.
browser_previewA
Captures the current viewport as a PNG image (the AI sees the page) + url, title, scroll and dimensions. It is the main visual inspection tool.
Inputs: no named parameters.
browser_run_stepA
Runs a YATT (leaf) step in the current page: click, type, hover, assert_*, goto, wait_visible, etc. Returns ok/error, duration and, on failure, an evidence screenshot. With vars it interpolates {{name}} into the step before running it. Structure steps (if/repeat/for_each/run_flow) run with test_run, not here.
Inputs: step (required), vars, timeoutMs.
browser_scrollA
Scrolls the page vertically (dy in pixels, positive moves down) and returns the updated preview.
Inputs: dy (required).
browser_statusB
State of the controlled browser: open/closed, engine, URL and interaction.
Inputs: no named parameters.
db_queryA
Executes a read-only query (SELECT/WITH/EXPLAIN/PRAGMA) against the app-under-test database. Pass the connection in db (SQLite path or "file:" / postgres:// URL); otherwise the engine-side YATT_APP_DB/--app-db configuration applies. Returns {columns, rows, totalRows}; rows are capped at 200.
Inputs: sql (required), db.
pingA
Checks that the MCP server and the engine (sidecar) respond.
Inputs: no named parameters.
report_deleteA
Deletes a saved report (DB + file under reports/).
Inputs: name (required).
report_getA
Returns the content of a report (parseable JSON). To diagnose failures, the report has steps[] with status ok/fail, error and ms.
Inputs: name (required).
report_listA
Lists the saved run reports (names .json and .html).
Inputs: no named parameters.
schemaA
Complete documentation of the YATT test format (schema v1): fields, actions, variables, dataset and usage guide. Read it before creating tests.
Inputs: no named parameters.
session_deleteA
Deletes a saved session.
Inputs: name (required).
session_listB
Lists the saved sessions.
Inputs: no named parameters.
session_saveA
Saves the current session state (cookies/localStorage) under a name, for tests with prior authentication.
Inputs: name (required).
tab_closeA
Closes a tab (by index; without an index closes the active one).
Inputs: index.
tab_listA
Lists the open tabs: index, active, title and URL.
Inputs: no named parameters.
tab_openA
Opens a new tab (optionally with a URL) and returns the tab list.
Inputs: url.
tab_switchA
Switches to the tab with the given index (0-based).
Inputs: index (required).
test_createA
Creates a new test. Accepts the content as a JSON string or as an object. Validates the schema (schemaVersion, steps, actions). Fails if the name already exists unless overwrite: true.
Inputs: content (required), name, overwrite.
test_deleteA
Deletes a test from the library (database and tests/.yatt.json file).
Inputs: name (required).
test_duplicateA
Duplicates an existing test under a new name (default " (copy)").
Inputs: name (required), newName.
test_export_playwrightA
Generates the code of a saved test as a TypeScript spec (.spec.ts), in Playwright (@playwright/test) or Jest (jest-environment-playwright) format, with sub-flows embedded as functions. Returns the content; with write: true it saves the file into exports/.spec.ts like the app.
Inputs: name (required), write, format.
test_getB
Returns a saved test as a full JSON object (steps, variables, environments, dataset).
Inputs: name (required).
test_listA
Lists the tests saved in the YATT library (names).
Inputs: no named parameters.
test_renameA
Renames a test in the library (updates the DB and the mirror file).
Inputs: name (required), newName (required).
test_runB
Runs a saved test headless (Chromium engine by default) and saves a report in the library. Parameters: variable environment, per-run overrides, per-step timeout. Returns the summary with the steps and the report name.
Inputs: name (required), env, url, browser, +3 more.
test_run_datasetA
Data-driven: runs a test once per row of overrides and returns each row result plus totals. No report is saved.
Inputs: name (required), rows (required), env, browser, +1 more.
test_updateA
Replaces the full content of an existing test (same validation as test_create).
Inputs: name (required), content (required).
test_validateA
Validates test content (JSON string or object) without saving it. Returns {ok: true, doc: summary} or {ok: false, error}. Useful before test_create/test_update.
Inputs: content (required), name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
The tool set is organized by clear resource prefixes (test_, report_, browser_, tab_, session_), and each operation targets a distinct resource or action. A few browser-related tools such as browser_run_step, browser_condition, and browser_click_at have overlapping interaction/inspection responsibilities, but the descriptions clarify their boundaries.
The vast majority of tools follow a consistent snake_case verb_noun pattern, e.g. test_create, browser_open, and session_delete. The exceptions are ping and schema, which are single-word names that do not follow the pattern but are still clear and unlikely to confuse.
35 tools is well over the 25+ threshold and creates a heavy selection surface for an agent. The tools are logically grouped, but the overall count feels excessive for a single MCP server even though each tool has a legitimate role in the testing workflow.
The test lifecycle is well covered: create, read, update, delete, rename, duplicate, validate, run, and export are all present. Minor gaps exist in baseline management, which only offers list and get with no create/delete, and reports lack comparison or export operations, but these are workable gaps.
Maintenance
Related MCP Connectors
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Write, run and check natural-language browser tests of your web app from your AI assistant.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that provides browser automation capabilities using Playwright, enabling LLMs to interact with web pages, take screenshots, generate test code, scrape web content, and execute JavaScript in a real browser environment.32MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to control web browsers through Playwright automation, providing 50+ tools for navigation, interaction, testing, accessibility audits, and visual testing across Chromium, Firefox, and WebKit.-
- AlicenseNot gradedqualityFmaintenanceEnables Model Context Protocol tools for automating web browsers and Electron desktop applications using Playwright's accessibility tree snapshots. It supports window management and JavaScript execution in the main process, providing deterministic automation through structured data.473 npm17Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI-powered browser automation controlled through natural language, integrating Playwright with the Model Context Protocol to perform web interactions like navigation, form filling, and screenshots.10MIT