rpc-agent 0.4.0 → 0.6.0

package/dist/mcp.js

@@ -1,12 +1,17 @@
 import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 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, defaultRecordOptions, DEFAULT_RECORD_DEVICE, DEFAULT_RECORD_SECONDS, MAX_RECORD_SECONDS, normalizeUrl, } from './options.js';
+import { unpinnedLines, warningWhere } from './motion.js';
+import { record } from './record.js';
 import { DEFAULT_MAX_HEIGHT } from './slices.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const screenshotInput = {
@@ -56,6 +61,17 @@ const screenshotInput = {
         .boolean()
         .optional()
         .describe('Emulate prefers-reduced-motion: reduce. Helps when scroll-triggered entrance animations (GSAP, Framer Motion) leave sections blank.'),
+    finishAnimations: z
+        .boolean()
+        .optional()
+        .describe('Jump GSAP tweens to their end before capture when gsap/ScrollTrigger are on window (scrubbed and pinned ones keep their ' +
+        'scroll position), and finite Web Animations too (the screenshot already ends CSS animations). Use it when the result warns ' +
+        'that elements were still animating. Default false.'),
+    unpin: z
+        .boolean()
+        .optional()
+        .describe('Full page: collapse pinned (GSAP ScrollTrigger-style or sticky) sections so each shows once instead of over a tall blank spacer. ' +
+        'Listed under motion.unpinned. Default true.'),
     waitFor: z.string().optional().describe('CSS selector to wait for (visible) before capturing.'),
     waitMs: z.number().int().min(0).max(30_000).optional().describe('Extra settle delay after load, in ms.'),
     colorScheme: z.enum(COLOR_SCHEMES).optional().describe('Emulate prefers-color-scheme.'),
@@ -65,6 +81,8 @@ const screenshotInput = {
         .boolean()
         .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),
@@ -93,6 +111,67 @@ const screenshotInput = {
         .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}.`),
+};
+const recordInput = {
+    url: z
+        .string()
+        .describe('Page to record. http(s)://, file://, a bare host like localhost:3000, or a path to a local .html file.'),
+    device: z.string().optional().describe(`One device id or alias (see list_devices). Default ${DEFAULT_RECORD_DEVICE}.`),
+    selector: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe('CSS selector of the element to record (a carousel, a marquee, a pinned section). It is scrolled into view and the video is cropped to its box. Default: the whole viewport.'),
+    duration: z
+        .number()
+        .min(0.5)
+        .max(MAX_RECORD_SECONDS)
+        .optional()
+        .describe(`Seconds of video. Default ${DEFAULT_RECORD_SECONDS}, max ${MAX_RECORD_SECONDS}.`),
+    gif: z.boolean().optional().describe('Also write a GIF (10 fps, at most 640 px wide). Default false.'),
+    mp4: z.boolean().optional().describe('Also write an mp4; needs an ffmpeg with H.264 on PATH, skipped with a warning otherwise. Default false.'),
+    reducedMotion: z.boolean().optional().describe('Emulate prefers-reduced-motion: reduce.'),
+    waitFor: z.string().optional().describe('CSS selector to wait for (visible) before recording.'),
+    waitMs: z.number().int().min(0).max(30_000).optional().describe('Extra delay before recording, in ms.'),
+    colorScheme: z.enum(COLOR_SCHEMES).optional().describe('Emulate prefers-color-scheme.'),
+    outDir: z.string().optional().describe(`Output directory, relative to the server's cwd. Default ${DEFAULT_OUT_DIR}.`),
+    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', {
@@ -100,22 +179,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 = {};
-            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);
+            const auth = authFrom(args);
             options = {
                 url: normalizeUrl(args.url),
                 devices: resolveDevices(args.devices ?? DEFAULT_DEVICES).map(d => d.id),
@@ -128,6 +197,8 @@ export function createServer() {
                 timeoutMs: args.timeoutMs ?? DEFAULT_TIMEOUT_MS,
                 emulate: true,
                 reducedMotion: args.reducedMotion ?? false,
+                finishAnimations: args.finishAnimations ?? false,
+                unpin: args.unpin ?? true,
                 maxHeight: args.maxHeight ?? DEFAULT_MAX_HEIGHT,
                 saveSlices: args.saveSlices,
                 maxSlices: args.maxSlices ?? DEFAULT_MAX_SLICES,
@@ -183,9 +254,112 @@ 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('record', {
+        title: 'Record a short video of a page or element',
+        description: 'Record a few seconds of a page, or of one element, as a VP9 webm (plus a GIF or mp4 on request), for motion a ' +
+            'screenshot cannot show: carousels, marquees, pinned scroll sections, looping animations. screenshot warns ' +
+            '"carousel: use rpc record" when it sees one. Returns the file paths, a short summary and the first frame (poster) inline.',
+        inputSchema: { ...recordInput, ...authInput },
+        annotations: { readOnlyHint: false, openWorldHint: true },
+    }, async (args) => {
+        let options;
+        try {
+            const auth = authFrom(args);
+            options = {
+                ...defaultRecordOptions(args.url),
+                device: resolveDevices([args.device ?? DEFAULT_RECORD_DEVICE])[0].id,
+                selector: args.selector,
+                duration: args.duration ?? DEFAULT_RECORD_SECONDS,
+                gif: args.gif ?? false,
+                mp4: args.mp4 ?? false,
+                reducedMotion: args.reducedMotion ?? false,
+                outDir: args.outDir ?? DEFAULT_OUT_DIR,
+                waitFor: args.waitFor,
+                waitMs: args.waitMs ?? 0,
+                colorScheme: args.colorScheme,
+                timeoutMs: args.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                ...(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 r = await record(options, { browser });
+            const content = [{ type: 'text', text: recordSummary(r) + '\n\n' + JSON.stringify(r, null, 2) }];
+            if (r.error)
+                return { isError: true, content };
+            if (r.poster) {
+                const p = await renderPreview(browser, await readFile(r.poster.path), r.poster);
+                content.push({ type: 'text', text: `${r.device}${r.selector ? ` ${r.selector}` : ''}: first frame (poster) ${p.width}x${p.height}` });
+                content.push({ type: 'image', data: p.data.toString('base64'), mimeType: 'image/jpeg' });
+            }
+            return { 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)
@@ -264,8 +438,15 @@ export function headline(shots, options, auth) {
             continue;
         }
         const size = s.shot ? `${s.shot.width}x${s.shot.height}px` : '';
+        const motion = [
+            ...unpinnedLines(s.motion?.unpinned).map(u => `  unpinned: ${u}`),
+            ...(s.warnings ?? []).map(w => {
+                const where = warningWhere(w);
+                return `  WARN [${w.id}] ${w.message}${where ? ` at ${where}` : ''}\n    fix: ${w.fix}`;
+            }),
+        ];
         if (!options.fullPage) {
-            lines.push(`ok ${s.device}: ${size}${s.shot ? ` ${s.shot.path}` : ''}`);
+            lines.push(`ok ${s.device}: ${size}${s.shot ? ` ${s.shot.path}` : ''}`, ...motion);
             continue;
         }
         const parts = [
@@ -294,8 +475,29 @@ export function headline(shots, options, auth) {
                 parts.push(`  full PNG: ${s.shot ? s.shot.path : ''}`);
             }
         }
-        lines.push(parts.join('\n'));
+        lines.push(parts.join('\n'), ...motion);
+    }
+    return lines.join('\n');
+}
+/** First lines of the record tool's result: what was written, or why not. */
+export function recordSummary(r) {
+    const lines = [];
+    if (r.auth)
+        lines.push(`auth: ${describeAuth(r.auth)}`);
+    if (r.error) {
+        lines.push(`FAILED ${r.device}: ${r.error}${r.hint ? `\n  hint: ${r.hint}` : ''}`);
+        return lines.join('\n');
     }
+    const v = r.video;
+    lines.push(`ok ${r.device}${r.selector ? ` ${r.selector}` : ''}: ${v.duration}s webm ${v.width}x${v.height} at ${v.fps} fps ${v.path}`);
+    if (r.poster)
+        lines.push(`  poster: ${r.poster.path}`);
+    if (r.gif)
+        lines.push(`  gif: ${r.gif.path} (${r.gif.width}x${r.gif.height}, ${r.gif.frames} frames)`);
+    if (r.mp4)
+        lines.push(`  mp4: ${r.mp4.path}`);
+    for (const w of r.warnings ?? [])
+        lines.push(`  WARN ${w}`);
     return lines.join('\n');
 }
 function summarise(url, outDir, shots, auth) {