rpc-agent 0.3.1 → 0.5.0

package/dist/cli.js

@@ -2,16 +2,22 @@
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { ArgError, parseCli, USAGE } from './args.js';
+import { clearSessions, describeAuth, listSessions, localTime, sessionsDir } from './auth.js';
 import { doctor, installChromium } from './browser.js';
 import { capture } from './capture.js';
+import { checkExitCode, runCheck, summaryLine } from './check.js';
+import { deviceLine, plainReport } from './check-format.js';
 import { CATEGORY_LABELS, CATEGORY_ORDER, DEVICE_ALIASES, DEVICES } from './devices.js';
-import { currentMode, openPath } from './term.js';
+import { currentMode, openPath, waitForEnter } from './term.js';
 const NO_PAINT = { ok: s => s, bad: s => s, warn: s => s };
 let paint = NO_PAINT;
+/** The full palette for check output; identity functions unless FORCE_COLOR. */
+let colours;
 async function plainPaint() {
+    const { default: pc } = await import('picocolors');
+    colours = pc.createColors(currentMode().color);
     if (!currentMode().color)
         return NO_PAINT;
-    const { default: pc } = await import('picocolors');
     const c = pc.createColors(true);
     return { ok: c.green, bad: c.red, warn: c.yellow };
 }
@@ -78,7 +84,7 @@ async function main(argv) {
             return report.ok ? 0 : 1;
         }
         case 'install': {
-            const code = await installChromium();
+            const code = await installChromium({ headed: Boolean(cmd.headed) });
             if (code !== 0)
                 return code;
             if (mode.rich) {
@@ -94,19 +100,124 @@ async function main(argv) {
                 const { ui, c } = await loadUi();
                 return ui.runShot(cmd.options, { open: cmd.open }, c);
             }
-            const result = await capture(cmd.options, cmd.json ? {} : { onDevice: printShot });
+            const result = await capture(cmd.options, cmd.json ? {} : { onDevice: printShot, onAuth: a => console.log(`auth: ${describeAuth(a)}`) });
             if (cmd.json)
                 console.log(JSON.stringify(result, null, 2));
             if (cmd.open && result.shots.some(s => !s.error))
                 openPath(result.outDir);
             return result.shots.some(s => s.error) ? 1 : 0;
         }
+        case 'check': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runCheck(cmd.options, c);
+            }
+            const report = await runCheck(cmd.options, cmd.json
+                ? {}
+                : {
+                    onAuth: a => console.log(`auth: ${describeAuth(a)}`),
+                    onDevice: d => console.log(deviceLine(d, colours)),
+                });
+            if (cmd.json)
+                console.log(JSON.stringify(report, null, 2));
+            else
+                printCheck(report);
+            return checkExitCode(report, cmd.options.failOn);
+        }
+        case 'login': {
+            if (cmd.passwordFromFlag) {
+                console.error(`rpc: ${paint.warn('warning:')} --password is visible in shell history and the process list; set RPC_LOGIN_PASSWORD instead`);
+            }
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runLogin(cmd, c);
+            }
+            return plainLogin(cmd);
+        }
+        case 'sessions': {
+            if (mode.rich) {
+                const { ui, c } = await loadUi();
+                return ui.runSessions(cmd.action, cmd.origin, c);
+            }
+            if (cmd.action === 'clear') {
+                const gone = await clearSessions(cmd.origin);
+                if (cmd.json)
+                    console.log(JSON.stringify({ removed: gone }, null, 2));
+                else if (gone.length === 0)
+                    console.log(cmd.origin ? `No saved session for ${cmd.origin}` : 'No saved sessions');
+                else
+                    for (const o of gone)
+                        console.log(`removed ${o}`);
+                return 0;
+            }
+            const list = await listSessions();
+            if (cmd.json)
+                console.log(JSON.stringify({ dir: sessionsDir(), sessions: list }, null, 2));
+            else if (list.length === 0)
+                console.log(`No saved sessions in ${sessionsDir()}. Create one with: rpc login <url>`);
+            else
+                for (const s of list)
+                    console.log(sessionLine(s));
+            return 0;
+        }
     }
 }
+async function plainLogin(cmd) {
+    const { formLogin, interactiveLogin } = await import('./login.js');
+    let result;
+    if (cmd.form) {
+        if (!cmd.json)
+            console.log(`signing in at ${cmd.url} (headless form)`);
+        result = await formLogin(cmd, cmd.form);
+    }
+    else {
+        const enter = waitForEnter();
+        try {
+            result = await interactiveLogin(cmd, enter.promise, () => {
+                if (!cmd.json)
+                    console.log(`Opened ${cmd.url}. Sign in in the browser window, then press Enter here (or close the window).`);
+            });
+        }
+        finally {
+            enter.stop();
+        }
+    }
+    if (cmd.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(`${paint.ok('saved')} session for ${result.origin}: ${result.path} (${result.cookies} cookie(s), ${result.localStorage} localStorage origin(s))`);
+        if (result.stillOnLogin) {
+            console.error(`${paint.warn('warning:')} the page was still on a login URL (${result.finalUrl}); the sign-in may not have finished`);
+        }
+    }
+    return 0;
+}
+function sessionLine(s) {
+    const when = localTime;
+    const parts = [s.origin, `${s.cookies} cookie(s)`];
+    if (s.savedAt)
+        parts.push(`saved ${when(s.savedAt)}`);
+    if (s.expired)
+        parts.push(paint.bad(`expired ${when(s.expires)}`));
+    else if (s.expires)
+        parts.push(`expires ${when(s.expires)}`);
+    parts.push(rel(s.path));
+    return parts.join('  ');
+}
 function rel(p) {
     const r = relative(process.cwd(), p);
     return r.startsWith('..') ? p : r;
 }
+function printCheck(report) {
+    const body = plainReport(report, colours);
+    if (body)
+        console.log(body);
+    console.log('');
+    const s = report.summary;
+    const line = summaryLine(s);
+    console.log(s.errors ? paint.bad(line) : s.warnings ? paint.warn(line) : paint.ok(line));
+}
 function printDoctor(r) {
     console.log(`node        ${r.node}`);
     console.log(`playwright  ${r.playwright}`);

package/dist/help.js

@@ -15,16 +15,80 @@ const SHOT_OPTIONS = [
     ['    --open', 'open the output folder when done'],
     ['    --json', 'print the result as JSON (no colour, no progress)'],
 ];
+const AUTH_OPTIONS = [
+    ['    --cookie <c>', '"name=value[; Domain=…; Path=…]", repeatable; target origin only'],
+    ['    --header <h>', '"Name: value", repeatable; sent to the target origin only'],
+    ['    --storage-state <file>', 'load a Playwright storageState JSON (cookies + localStorage)'],
+    ['    --no-session', "don't use the session saved by `rpc login` for this origin"],
+    ['    --allow-origin <o>', 'also send headers and loaded cookies to this origin, repeatable'],
+];
+const CHECK_OPTIONS = [
+    ['-d, --devices <ids>', 'comma-separated device ids or aliases (default: iphone-15-pro,desktop-1440)'],
+    ['    --fail-on <level>', 'error (default) or warn: also exit 1 on warnings'],
+    ['    --shots', 'screenshot the elements behind layout-shift and overflow findings'],
+    ['-o, --out <dir>', 'where --shots writes (default: ./.rpc-shots)'],
+    ['    --wait-for <selector>', 'wait for a CSS selector before checking'],
+    ['    --wait <ms>', 'extra settle delay after the scroll (default: 0)'],
+    ['    --color-scheme <s>', 'light | dark | no-preference'],
+    ['    --timeout <ms>', 'navigation timeout (default: 30000)'],
+    ['    --json', 'print the report as JSON (schema in the README)'],
+];
+const LOGIN_OPTIONS = [
+    ['    --save <file>', 'write the storage state here instead of the per-origin session'],
+    ['    --form', 'headless: fill an email + password form (CI, agents)'],
+    ['    --email <email>', 'with --form; default $RPC_LOGIN_EMAIL'],
+    ['    --password <pw>', 'with --form; prefer $RPC_LOGIN_PASSWORD (keeps it out of shell history)'],
+    ['    --email-selector <css>', `default: input[type=email], input[name=email], …`],
+    ['    --password-selector <css>', 'default: input[type=password]'],
+    ['    --submit-selector <css>', 'default: button[type=submit], input[type=submit] (else Enter)'],
+    ['    --timeout <ms>', 'navigation and form timeout (default: 30000)'],
+    ['    --json', 'print the result as JSON'],
+];
 export const COMMANDS = {
     shot: {
         usage: 'rpc shot <url> [options]',
         summary: 'Capture a URL at device viewports, optionally framed in device bezels.',
-        options: SHOT_OPTIONS,
+        options: [...SHOT_OPTIONS, ...AUTH_OPTIONS],
         examples: [
             ['rpc shot localhost:3000 -d iphone-15,ipad,desktop-1440 --bezels', ''],
             ['rpc shot example.com/pricing --full-page --slices', 'whole page + review slices'],
             ['rpc shot localhost:5173 --color-scheme dark --open', 'dark mode, open when done'],
             ['rpc shot localhost:3000 -d pixel --json', 'machine-readable result'],
+            ['rpc shot localhost:3000/billing', 'uses the session saved by rpc login'],
+            ["rpc shot api.example.com/admin --header 'Authorization: Bearer $TOKEN'", ''],
+        ],
+    },
+    check: {
+        usage: 'rpc check <url> [options]',
+        summary: 'Audit one page before launch: meta and social tags, layout shift (CLS), unlabelled controls, web fonts, ' +
+            'mobile viewport bugs and basics (status, mixed content, console errors). Exits 1 when there are errors.',
+        options: [...CHECK_OPTIONS, ...AUTH_OPTIONS],
+        examples: [
+            ['rpc check localhost:3000', 'phone + desktop'],
+            ['rpc check localhost:3000 --fail-on warn --json', 'CI: fail on warnings too'],
+            ['rpc check example.com -d pixel,iphone-se,desktop --shots', 'more devices, element screenshots'],
+            ['rpc check localhost:3000/billing', 'uses the session saved by rpc login'],
+        ],
+    },
+    login: {
+        usage: 'rpc login <url> [--form] [--save <file>]',
+        summary: 'Open a browser window at the URL, sign in, then press Enter (or close the window). The session is saved for that ' +
+            'origin (~/.config/rpc-agent/sessions, mode 0600) and `rpc shot` uses it automatically.',
+        options: LOGIN_OPTIONS,
+        examples: [
+            ['rpc login localhost:3000/sign-in', 'sign in by hand in a window'],
+            ['RPC_LOGIN_EMAIL=me@x.test RPC_LOGIN_PASSWORD=… rpc login localhost:3000/sign-in --form', 'CI / agents'],
+            ['rpc login example.com --save auth.json', 'write a storageState file instead'],
+        ],
+    },
+    sessions: {
+        usage: 'rpc sessions [list] | rpc sessions clear [origin]',
+        summary: 'List the sessions saved by `rpc login` (origins, cookie counts, expiry; never values), or delete them.',
+        options: [['    --json', 'print as JSON']],
+        examples: [
+            ['rpc sessions', ''],
+            ['rpc sessions clear localhost:3000', 'forget one origin'],
+            ['rpc sessions clear', 'forget all'],
         ],
     },
     devices: {
@@ -43,18 +107,25 @@ export const COMMANDS = {
         examples: [['rpc doctor', 'exits 1 when Chromium is missing']],
     },
     install: {
-        usage: 'rpc install',
+        usage: 'rpc install [--headed]',
         summary: "Download Playwright's Chromium with the Playwright version rpc uses, then run doctor.",
-        examples: [['rpc install', '']],
+        options: [['    --headed', 'also download full Chromium, for the window `rpc login` opens']],
+        examples: [
+            ['rpc install', 'headless shell only (captures)'],
+            ['rpc install --headed', 'for rpc login'],
+        ],
     },
     mcp: {
         usage: 'rpc mcp',
-        summary: 'Run the MCP server on stdio (tools: screenshot, list_devices).',
+        summary: 'Run the MCP server on stdio (tools: screenshot, check, list_devices, list_sessions).',
         examples: [['claude mcp add --scope user rpc -- node /abs/path/dist/cli.js mcp', 'add to Claude Code']],
     },
 };
 const TOP = [
     ['shot <url>', 'capture screenshots'],
+    ['check <url>', 'pre-launch audit: meta, layout shift, labels, fonts, mobile'],
+    ['login <url>', 'sign in once; later shots of that origin use the session'],
+    ['sessions', 'list or clear saved sessions'],
     ['devices', 'list device ids and aliases'],
     ['doctor', "check that Playwright's Chromium is installed and launches"],
     ['install', "download Playwright's Chromium (same version rpc uses)"],
@@ -91,6 +162,9 @@ export function richHelp(c) {
         c.bold('Shot options:'),
         ...table(SHOT_OPTIONS, c),
         '',
+        c.bold('Auth options:'),
+        ...table(AUTH_OPTIONS, c),
+        '',
         c.bold('Examples:'),
         ...examples(COMMANDS.shot.examples, c),
         '',

package/dist/login.js

@@ -0,0 +1,150 @@
+// `rpc login`: sign in once, save the browser's storage state for the origin.
+import { chromium } from 'playwright';
+import { isLoginUrl, redact, scopeState, toOrigin, writeSession } from './auth.js';
+import { launchBrowser } from './browser.js';
+export const DEFAULT_SELECTORS = {
+    email: 'input[type=email], input[autocomplete=username], input[name=email], input[name=username], input#email',
+    password: 'input[type=password]',
+    submit: 'button[type=submit], input[type=submit]',
+};
+export class HeadedBrowserMissingError extends Error {
+    name = 'HeadedBrowserMissingError';
+    constructor() {
+        super('rpc login opens a browser window, which needs full Chromium (`rpc install` only downloads the headless shell). ' +
+            'Run `rpc install --headed`, or install Google Chrome, or sign in headlessly with `rpc login <url> --form`.');
+    }
+}
+/** Headed Chromium; falls back to an installed Google Chrome. */
+export async function launchHeaded() {
+    try {
+        return await chromium.launch({ headless: false });
+    }
+    catch (err) {
+        if (!/Executable doesn't exist|playwright install/i.test(err.message))
+            throw err;
+    }
+    try {
+        return await chromium.launch({ headless: false, channel: 'chrome' });
+    }
+    catch {
+        throw new HeadedBrowserMissingError();
+    }
+}
+async function save(state, opts, finalUrl) {
+    const origin = toOrigin(opts.url);
+    const path = await writeSession(state, { origin, savedAt: new Date().toISOString(), url: opts.url }, opts.save);
+    const own = scopeState(state, [origin]);
+    return {
+        origin,
+        path,
+        finalUrl,
+        cookies: own.cookies.length,
+        localStorage: own.origins.length,
+        stillOnLogin: isLoginUrl(finalUrl) && new URL(finalUrl).origin === origin,
+    };
+}
+/**
+ * Open a visible browser at the URL and save the storage state when `done`
+ * resolves (the user pressed Enter) or the window is closed.
+ */
+export async function interactiveLogin(opts, done, onOpen) {
+    const browser = await launchHeaded();
+    try {
+        const context = await browser.newContext({ viewport: null, ignoreHTTPSErrors: true });
+        const page = await context.newPage();
+        let lastUrl = opts.url;
+        page.on('framenavigated', f => {
+            if (f === page.mainFrame())
+                lastUrl = f.url();
+        });
+        await page.goto(opts.url, { timeout: opts.timeoutMs }).catch(() => { });
+        onOpen?.();
+        // Snapshot regularly: once the window is closed the context can't be read.
+        let snapshot = await context.storageState();
+        const timer = setInterval(() => {
+            context.storageState().then(s => (snapshot = s), () => { });
+        }, 1000);
+        const closed = new Promise(res => {
+            page.on('close', res);
+            browser.on('disconnected', res);
+        });
+        try {
+            await Promise.race([done, closed]);
+        }
+        finally {
+            clearInterval(timer);
+        }
+        const state = await context.storageState().catch(() => snapshot);
+        if (!page.isClosed())
+            lastUrl = page.url();
+        return await save(state, opts, lastUrl);
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}
+/**
+ * Headless: fill an email + password form, submit, wait to leave the login
+ * URL, save. For CI and agents.
+ */
+export async function formLogin(opts, form) {
+    const browser = await launchBrowser();
+    try {
+        const context = await browser.newContext({ ignoreHTTPSErrors: true });
+        const page = await context.newPage();
+        await page.goto(opts.url, { waitUntil: 'load', timeout: opts.timeoutMs });
+        // Let client-side forms hydrate, so submit runs the app's handler rather
+        // than a native GET that would put the password in the URL.
+        await page.waitForLoadState('networkidle', { timeout: Math.min(opts.timeoutMs, 10_000) }).catch(() => { });
+        const start = new URL(page.url());
+        const email = page.locator(form.emailSelector ?? DEFAULT_SELECTORS.email).first();
+        const password = page.locator(form.passwordSelector ?? DEFAULT_SELECTORS.password).first();
+        await waitVisible(email, 'email field', form.emailSelector ? '--email-selector' : undefined, opts.timeoutMs);
+        await email.fill(form.email);
+        await waitVisible(password, 'password field', form.passwordSelector ? '--password-selector' : undefined, opts.timeoutMs);
+        await password.fill(form.password);
+        const submit = page.locator(form.submitSelector ?? DEFAULT_SELECTORS.submit).first();
+        if (form.submitSelector || (await submit.count()) > 0) {
+            await waitVisible(submit, 'submit button', form.submitSelector ? '--submit-selector' : undefined, opts.timeoutMs);
+            await submit.click();
+        }
+        else {
+            await password.press('Enter');
+        }
+        try {
+            await page.waitForURL(u => u.origin + u.pathname !== start.origin + start.pathname, { timeout: opts.timeoutMs });
+        }
+        catch {
+            const shown = await pageMessage(page);
+            const message = shown && redact(shown, [form.password]);
+            throw new Error(`Still on ${start.origin}${start.pathname} ${Math.round(opts.timeoutMs / 1000)} s after submitting the form` +
+                `${message ? ` (the page says: "${message}")` : ''}. Check the credentials, or the selectors (--email-selector, --password-selector, --submit-selector).`);
+        }
+        await page.waitForLoadState('networkidle', { timeout: Math.min(opts.timeoutMs, 10_000) }).catch(() => { });
+        return await save(await context.storageState(), opts, page.url());
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}
+async function waitVisible(loc, what, flag, timeoutMs) {
+    try {
+        await loc.waitFor({ state: 'visible', timeout: Math.min(timeoutMs, 15_000) });
+    }
+    catch {
+        throw new Error(`No ${what} found on the page${flag ? ` for ${flag}` : ''}. Pass ${flag ?? `--${what.split(' ')[0]}-selector`} with a CSS selector that matches it.`);
+    }
+}
+/** A visible alert or error message, if the login page shows one. */
+async function pageMessage(page) {
+    const loc = page.locator('[role=alert], [aria-live=assertive], .error, [data-error]').filter({ hasText: /\S/ }).first();
+    try {
+        if ((await loc.count()) === 0)
+            return undefined;
+        const t = (await loc.innerText({ timeout: 1000 })).trim().replace(/\s+/g, ' ');
+        return t ? t.slice(0, 160) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp.js

@@ -2,10 +2,13 @@ import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { describeAuth, listSessions, resolveAuth, sessionsDir, toOrigin } from './auth.js';
 import { capture, launchBrowser } from './capture.js';
+import { runCheck } from './check.js';
+import { textSummary } from './check-format.js';
 import { renderPreview } from './composite.js';
 import { CATEGORY_LABELS, CATEGORY_ORDER, DEFAULT_DEVICES, DEVICE_ALIASES, DEVICES, resolveDevices, } from './devices.js';
-import { COLOR_SCHEMES, DEFAULT_MAX_SLICES, DEFAULT_OUT_DIR, DEFAULT_SLICE_WIDTH, DEFAULT_TIMEOUT_MS, normalizeUrl, } from './options.js';
+import { COLOR_SCHEMES, DEFAULT_MAX_SLICES, DEFAULT_OUT_DIR, DEFAULT_SLICE_WIDTH, DEFAULT_TIMEOUT_MS, defaultCheckOptions, normalizeUrl, } from './options.js';
 import { DEFAULT_MAX_HEIGHT } from './slices.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const screenshotInput = {
@@ -65,6 +68,70 @@ const screenshotInput = {
         .optional()
         .describe('Return JPEG previews inline: one per device, or the full-page slices when fullPage. Default true.'),
 };
+const authInput = {
+    cookies: z
+        .array(z.object({
+        name: z.string().min(1),
+        value: z.string(),
+        domain: z.string().optional().describe('Default: the target host only. Must match the target host (or an allowOrigins host).'),
+        path: z.string().optional().describe('Default /.'),
+    }))
+        .max(50)
+        .optional()
+        .describe('Cookies set on the target origin before loading. Values are never echoed back.'),
+    headers: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Request headers, e.g. {"Authorization": "Bearer …"}. Sent only to the target origin (and allowOrigins), never to third-party requests or redirects. Values are never echoed back.'),
+    storageState: z
+        .string()
+        .optional()
+        .describe("Path to a Playwright storageState JSON (cookies + localStorage), relative to the server's cwd. Only the target origin's entries are loaded."),
+    useSession: z
+        .boolean()
+        .optional()
+        .describe('Use the session saved by `rpc login <url>` for the target origin. Default true when one exists (see list_sessions). Ignored when storageState is set.'),
+    allowOrigins: z
+        .array(z.string())
+        .max(10)
+        .optional()
+        .describe('Extra origins (e.g. an API host) that also get the headers and loaded cookies.'),
+};
+const checkInput = {
+    url: z
+        .string()
+        .describe('Page to audit. http(s)://, file://, a bare host like localhost:3000, or a path to a local .html file.'),
+    devices: z
+        .array(z.string())
+        .min(1)
+        .max(8)
+        .optional()
+        .describe(`Device ids or aliases (see list_devices). Default: ${DEFAULT_DEVICES.join(', ')}. ` +
+        'The mobile viewport checks (100vh, sideways scroll, tap targets, input zoom) run on phones only.'),
+    shots: z
+        .boolean()
+        .optional()
+        .describe('Save PNGs of the elements behind layout-shift and horizontal-overflow findings (paths in the report). Default false.'),
+    outDir: z.string().optional().describe(`Where shots go, relative to the server's cwd. Default ${DEFAULT_OUT_DIR}.`),
+    waitFor: z.string().optional().describe('CSS selector to wait for (visible) before checking.'),
+    waitMs: z.number().int().min(0).max(30_000).optional().describe('Extra settle delay after the scroll, in ms.'),
+    colorScheme: z.enum(COLOR_SCHEMES).optional().describe('Emulate prefers-color-scheme.'),
+    timeoutMs: z.number().int().min(1000).max(120_000).optional().describe(`Navigation timeout. Default ${DEFAULT_TIMEOUT_MS}.`),
+};
+function authFrom(args) {
+    const auth = {};
+    if (args.cookies?.length)
+        auth.cookies = args.cookies;
+    if (args.headers && Object.keys(args.headers).length)
+        auth.headers = args.headers;
+    if (args.storageState)
+        auth.storageState = args.storageState;
+    if (args.useSession === false)
+        auth.useSession = false;
+    if (args.allowOrigins?.length)
+        auth.allowOrigins = args.allowOrigins.map(toOrigin);
+    return auth;
+}
 export function createServer() {
     const server = new McpServer({ name: 'rpc', version: pkg.version });
     server.registerTool('screenshot', {
@@ -72,11 +139,12 @@ export function createServer() {
         description: 'Load a URL in headless Chromium at one or more device viewports (with device pixel ratio, mobile user agent and touch) ' +
             'and save PNG screenshots, optionally framed in a device bezel. Use it to check responsive layout of a page you are building, ' +
             'including local dev servers. Returns file paths, page title, HTTP status and console errors, plus inline previews.',
-        inputSchema: screenshotInput,
+        inputSchema: { ...screenshotInput, ...authInput },
         annotations: { readOnlyHint: false, openWorldHint: true },
     }, async (args) => {
         let options;
         try {
+            const auth = authFrom(args);
             options = {
                 url: normalizeUrl(args.url),
                 devices: resolveDevices(args.devices ?? DEFAULT_DEVICES).map(d => d.id),
@@ -93,7 +161,9 @@ export function createServer() {
                 saveSlices: args.saveSlices,
                 maxSlices: args.maxSlices ?? DEFAULT_MAX_SLICES,
                 sliceWidth: args.sliceWidth ?? DEFAULT_SLICE_WIDTH,
+                ...(Object.keys(auth).length ? { auth } : {}),
             };
+            resolveAuth(options.url, auth); // bad cookies/headers/storage state: a tool error, before launching
         }
         catch (err) {
             return { isError: true, content: [{ type: 'text', text: err.message }] };
@@ -111,9 +181,9 @@ export function createServer() {
             const content = [
                 {
                     type: 'text',
-                    text: headline(result.shots, options) +
+                    text: headline(result.shots, options, result.auth) +
                         '\n\n' +
-                        JSON.stringify(summarise(result.url, result.outDir, result.shots), null, 2),
+                        JSON.stringify(summarise(result.url, result.outDir, result.shots, result.auth), null, 2),
                 },
             ];
             if (inline) {
@@ -142,9 +212,58 @@ export function createServer() {
             await browser.close();
         }
     });
+    server.registerTool('check', {
+        title: 'Pre-launch check of a page',
+        description: 'Audit one URL before calling the work done: meta and social tags (title, description, canonical, lang, viewport zoom, ' +
+            'favicon, Open Graph, twitter:card, and whether og:image loads and its size), layout shift (CLS with the elements that moved), ' +
+            'buttons/links/images/fields without an accessible name, web fonts (font-display, preloads), mobile viewport bugs on phones ' +
+            '(100vh, sideways scroll, tap targets under 44px, inputs under 16px) and basics (HTTP status, mixed content, console errors). ' +
+            'Returns a short summary, then the JSON report: each finding has id, severity (error|warn|info), message, selector or url, ' +
+            'devices and a fix. Fix the errors (and ideally warnings), then run it again.',
+        inputSchema: { ...checkInput, ...authInput },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (args) => {
+        let options;
+        try {
+            const auth = authFrom(args);
+            options = {
+                ...defaultCheckOptions(args.url),
+                devices: resolveDevices(args.devices ?? DEFAULT_DEVICES).map(d => d.id),
+                outDir: args.outDir ?? DEFAULT_OUT_DIR,
+                waitFor: args.waitFor,
+                waitMs: args.waitMs ?? 0,
+                colorScheme: args.colorScheme,
+                timeoutMs: args.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                shots: args.shots ?? false,
+                ...(Object.keys(auth).length ? { auth } : {}),
+            };
+            resolveAuth(options.url, auth);
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: err.message }] };
+        }
+        let browser;
+        try {
+            browser = await launchBrowser();
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: `Could not start the browser: ${err.message}` }] };
+        }
+        try {
+            const report = await runCheck(options, { browser });
+            const content = [
+                { type: 'text', text: (report.auth ? `auth: ${describeAuth(report.auth)}\n` : '') + textSummary(report) },
+                { type: 'text', text: JSON.stringify(report, null, 2) },
+            ];
+            return report.devices.every(d => d.error) ? { isError: true, content } : { content };
+        }
+        finally {
+            await browser.close();
+        }
+    });
     server.registerTool('list_devices', {
         title: 'List device presets',
-        description: 'List device ids, CSS viewport sizes and pixel ratios usable in screenshot.devices, plus short aliases.',
+        description: 'List device ids, CSS viewport sizes and pixel ratios usable in screenshot.devices and check.devices, plus short aliases.',
         inputSchema: {
             category: z
                 .enum(CATEGORY_ORDER)
@@ -168,6 +287,29 @@ export function createServer() {
             lines.push(`${a} -> ${id}`);
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
+    server.registerTool('list_sessions', {
+        title: 'List saved login sessions',
+        description: 'List the origins that have a session saved by `rpc login` (used automatically by screenshot for that origin): ' +
+            'cookie count, when it was saved, and whether it has expired. Never returns cookie values.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const list = await listSessions();
+        if (list.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No saved sessions in ${sessionsDir()}. The user can create one with \`rpc login <url>\` ` +
+                            '(a browser window) or `rpc login <url> --form` with RPC_LOGIN_EMAIL / RPC_LOGIN_PASSWORD set.',
+                    },
+                ],
+            };
+        }
+        const lines = list.map(s => `${s.origin}: ${s.cookies} cookie(s)${s.savedAt ? `, saved ${s.savedAt}` : ''}` +
+            `${s.expired ? `, EXPIRED ${s.expires} (run \`rpc login ${s.origin}\`)` : s.expires ? `, expires ${s.expires}` : ''}`);
+        return { content: [{ type: 'text', text: lines.join('\n') + '\n\n' + JSON.stringify({ dir: sessionsDir(), sessions: list }, null, 2) }] };
+    });
     return server;
 }
 /** Framed first screen (the hero), then the first maxSlices slices, each with a label. */
@@ -187,8 +329,10 @@ async function fullPageImages(browser, s, maxSlices) {
     return out;
 }
 /** Plain-language first lines: failures with hints, and what full-page output covers. */
-export function headline(shots, options) {
+export function headline(shots, options, auth) {
     const lines = [];
+    if (auth)
+        lines.push(`auth: ${describeAuth(auth)}`);
     const failed = shots.filter(s => s.error);
     if (failed.length === shots.length)
         lines.push(`All ${shots.length} device(s) failed.`);
@@ -232,11 +376,12 @@ export function headline(shots, options) {
     }
     return lines.join('\n');
 }
-function summarise(url, outDir, shots) {
+function summarise(url, outDir, shots, auth) {
     return {
         url,
         outDir,
         shots: shots.map(({ buffers: _b, ...s }) => s),
+        ...(auth ? { auth } : {}),
     };
 }
 export async function runMcpServer() {