pagebolt-mcp 1.1.0 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-compatible-brightgreen)](https://modelcontextprotocol.io)
 
-Take screenshots, generate PDFs, and create OG images directly from your AI coding assistant.
+Take screenshots, generate PDFs, create OG images, inspect pages, and record demo videos directly from your AI coding assistant.
 
 **Works with Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client.**
 
@@ -22,6 +22,8 @@ PageBolt MCP Server connects your AI assistant to [PageBolt's web capture API](h
 - **Generate PDFs** from URLs or HTML (invoices, reports, docs)
 - **Create OG images** for social cards using templates or custom HTML
 - **Run browser sequences** — multi-step automation (navigate, click, fill, screenshot)
+- **Record demo videos** — browser automation as MP4/WebM/GIF with cursor effects, click animations, and auto-zoom
+- **Inspect pages** — get a structured map of interactive elements with CSS selectors (use before sequences)
 - **List device presets** — 25+ devices (iPhone, iPad, MacBook, Galaxy, etc.)
 - **Check usage** — monitor your API quota in real time
 
@@ -164,6 +166,36 @@ Execute multi-step browser automation.
 - "Go to https://example.com, click the pricing link, then screenshot both pages"
 - "Navigate to the login page, fill in test credentials, submit, and screenshot the dashboard"
 
+### `inspect_page`
+
+Inspect a web page and get a structured map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector.
+
+**Key parameters:** `url`/`html`, `width`, `height`, `viewportDevice`, `darkMode`, `cookies`, `headers`, `authorization`, `blockBanners`, `blockAds`, `waitUntil`, `waitForSelector`
+
+**Example prompts:**
+- "Inspect https://example.com and tell me what buttons and forms are on the page"
+- "What interactive elements are on the login page? I need selectors for a sequence"
+
+**Tip:** Use `inspect_page` before `run_sequence` to discover reliable CSS selectors instead of guessing.
+
+### `record_video`
+
+Record a professional demo video of a multi-step browser automation sequence with cursor effects, click animations, and smooth movement.
+
+**Key parameters:**
+- `steps` — same actions as `run_sequence` (except no screenshot/pdf — the whole sequence is the video)
+- `format` — `mp4`, `webm`, or `gif` (default: mp4; webm/gif require Starter+)
+- `framerate` — 24, 30, or 60 fps (default: 30)
+- `pace` — speed preset: `"fast"`, `"normal"`, `"slow"`, `"dramatic"`, `"cinematic"`, or a number 0.25–6.0
+- `cursor` — style (`highlight`/`circle`/`spotlight`/`dot`), color, size, smoothing
+- `clickEffect` — style (`ripple`/`pulse`/`ring`), color
+- `zoom` — auto-zoom on clicks with configurable level and duration
+- `saveTo` — output file path
+
+**Example prompts:**
+- "Record a video of logging into https://example.com with a spotlight cursor"
+- "Make a demo video of the signup flow at slow pace, save as demo.mp4"
+
 ### `list_devices`
 
 List all 25+ available device presets with viewport dimensions.
@@ -204,7 +236,7 @@ Free plan requires no credit card. Starter and Growth include a 14-day free tria
 
 ## Why PageBolt?
 
-- **5 APIs, one key** — screenshot, PDF, OG image, browser automation, and MCP server. Stop paying for separate tools.
+- **6 APIs, one key** — screenshot, PDF, OG image, browser automation, video recording, page inspection. Stop paying for separate tools.
 - **Clean captures** — automatic ad blocking, cookie banner removal, chat widget suppression, tracker blocking.
 - **25+ device presets** — iPhone SE to Galaxy S24 Ultra, iPad Pro, MacBook, Desktop 4K.
 - **Ship in 5 minutes** — plain HTTP, no SDKs required, works in any language.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pagebolt-mcp",
-  "version": "1.1.0",
-  "description": "MCP server for PageBolt — take screenshots, generate PDFs, create OG images, and record demo videos from AI coding assistants like Claude, Cursor, and Windsurf.",
+  "version": "1.2.0",
+  "description": "MCP server for PageBolt — take screenshots, generate PDFs, create OG images, inspect pages, and record demo videos from AI coding assistants like Claude, Cursor, and Windsurf.",
   "main": "src/index.mjs",
   "module": "src/index.mjs",
   "bin": {
@@ -25,6 +25,7 @@
     "browser-automation",
     "video-recording",
     "demo-video",
+    "page-inspection",
     "puppeteer",
     "web-capture",
     "pagebolt",

package/src/index.mjs

@@ -146,7 +146,7 @@ server.tool(
         }),
       ])
     ).optional().describe('Cookies to set — array of "name=value" strings or { name, value, domain? } objects'),
-    headers: z.record(z.string()).optional().describe('Extra HTTP headers to send with the request'),
+    headers: z.record(z.string(), z.string()).optional().describe('Extra HTTP headers to send with the request'),
     authorization: z.string().optional().describe('Authorization header value (e.g. "Bearer <token>")'),
     bypassCSP: z.boolean().optional().describe('Bypass Content-Security-Policy on the page'),
     // ── Content manipulation ──
@@ -410,6 +410,10 @@ server.tool(
       style: z.enum(['ripple', 'pulse', 'ring']).optional().describe('Click effect style (default: ripple)'),
       color: z.string().optional().describe('Click effect color as hex'),
     }).optional().describe('Visual click effect settings'),
+    pace: z.union([
+      z.number().min(0.25).max(6),
+      z.enum(['fast', 'normal', 'slow', 'dramatic', 'cinematic']),
+    ]).optional().describe('Controls how deliberate the video feels. Number (0.25–6.0, higher = slower) or preset: "fast" (0.5×), "normal" (1×), "slow" (2×), "dramatic" (3×), "cinematic" (4.5×). Default: "normal".'),
     darkMode: z.boolean().optional().describe('Emulate dark color scheme (default: false)'),
     blockBanners: z.boolean().optional().describe('Hide cookie consent banners (default: true)'),
     deviceScaleFactor: z.number().min(1).max(3).optional().describe('Device pixel ratio (default: 1)'),
@@ -461,6 +465,150 @@ server.tool(
   }
 );
 
+// ─── Tool: inspect_page ─────────────────────────────────────────
+server.tool(
+  'inspect_page',
+  'Inspect a web page and get a structured map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector. Use this BEFORE run_sequence to discover what elements exist on the page and get reliable selectors. Returns text (not an image), so it is fast and cheap. Costs 1 API request.',
+  {
+    // ── Source ──
+    url: z.string().url().optional().describe('URL to inspect (required if no html)'),
+    html: z.string().optional().describe('Raw HTML to inspect (required if no url)'),
+    // ── Viewport ──
+    width: z.number().int().min(1).max(3840).optional().describe('Viewport width in pixels (default: 1280)'),
+    height: z.number().int().min(1).max(2160).optional().describe('Viewport height in pixels (default: 720)'),
+    viewportDevice: z.string().optional().describe('Device preset for viewport emulation (e.g. "iphone_14_pro"). Use list_devices to see all presets.'),
+    viewportMobile: z.boolean().optional().describe('Enable mobile meta viewport emulation'),
+    viewportHasTouch: z.boolean().optional().describe('Enable touch event emulation'),
+    deviceScaleFactor: z.number().min(1).max(3).optional().describe('Device pixel ratio (default: 1)'),
+    // ── Timing ──
+    waitUntil: z.enum(['load', 'domcontentloaded', 'networkidle0', 'networkidle2']).optional().describe('When to consider navigation finished (default: networkidle2)'),
+    waitForSelector: z.string().optional().describe('Wait for this CSS selector to appear before inspecting'),
+    // ── Emulation ──
+    darkMode: z.boolean().optional().describe('Emulate dark color scheme (default: false)'),
+    reducedMotion: z.boolean().optional().describe('Emulate prefers-reduced-motion'),
+    userAgent: z.string().optional().describe('Override the browser User-Agent string'),
+    // ── Auth & headers ──
+    cookies: z.array(
+      z.union([
+        z.string(),
+        z.object({
+          name: z.string(),
+          value: z.string(),
+          domain: z.string().optional(),
+        }),
+      ])
+    ).optional().describe('Cookies to set — array of "name=value" strings or { name, value, domain? } objects'),
+    headers: z.record(z.string(), z.string()).optional().describe('Extra HTTP headers to send with the request'),
+    authorization: z.string().optional().describe('Authorization header value (e.g. "Bearer <token>")'),
+    bypassCSP: z.boolean().optional().describe('Bypass Content-Security-Policy on the page'),
+    // ── Content manipulation ──
+    hideSelectors: z.array(z.string()).optional().describe('Array of CSS selectors to hide before inspecting'),
+    blockBanners: z.boolean().optional().describe('Hide cookie consent banners (default: false)'),
+    blockAds: z.boolean().optional().describe('Block advertisements on the page'),
+    blockChats: z.boolean().optional().describe('Block live chat widgets'),
+    blockTrackers: z.boolean().optional().describe('Block tracking scripts'),
+    injectCss: z.string().optional().describe('Custom CSS to inject before inspecting'),
+    injectJs: z.string().optional().describe('Custom JavaScript to execute before inspecting'),
+  },
+  async (params) => {
+    if (!params.url && !params.html) {
+      return { content: [{ type: 'text', text: 'Error: Either "url" or "html" is required.' }], isError: true };
+    }
+
+    try {
+      const res = await callApi('/api/v1/inspect', {
+        method: 'POST',
+        body: params,
+      });
+
+      const data = await res.json();
+
+      // Format as structured text for efficient LLM consumption
+      const lines = [];
+
+      // Header
+      lines.push(`Page: ${data.title || '(untitled)'} (${data.url || params.url || 'html content'})`);
+      if (data.metadata) {
+        if (data.metadata.description) lines.push(`Description: ${data.metadata.description}`);
+        if (data.metadata.lang) lines.push(`Language: ${data.metadata.lang}`);
+        if (data.metadata.httpStatusCode) lines.push(`HTTP Status: ${data.metadata.httpStatusCode}`);
+      }
+      lines.push('');
+
+      // Headings
+      if (data.headings && data.headings.length > 0) {
+        lines.push(`Headings (${data.headings.length}):`);
+        for (const h of data.headings) {
+          lines.push(`  H${h.level}: ${h.text} — selector: ${h.selector}`);
+        }
+        lines.push('');
+      }
+
+      // Interactive elements
+      if (data.elements && data.elements.length > 0) {
+        lines.push(`Interactive Elements (${data.elements.length}):`);
+        for (const el of data.elements) {
+          let desc = `[${el.tag}`;
+          if (el.attributes && el.attributes.type) desc += ` type=${el.attributes.type}`;
+          desc += `]`;
+          if (el.text) desc += ` "${el.text}"`;
+          if (el.attributes && el.attributes.placeholder) desc += ` placeholder="${el.attributes.placeholder}"`;
+          if (el.attributes && el.attributes.href) desc += ` → ${el.attributes.href}`;
+          desc += ` — selector: ${el.selector}`;
+          lines.push(`  ${desc}`);
+        }
+        lines.push('');
+      }
+
+      // Forms
+      if (data.forms && data.forms.length > 0) {
+        lines.push(`Forms (${data.forms.length}):`);
+        for (const f of data.forms) {
+          const method = f.method || 'GET';
+          const action = f.action || '(none)';
+          lines.push(`  ${f.selector} (${method} ${action}): ${f.fields.length} field(s)`);
+          for (const field of f.fields) {
+            lines.push(`    - ${field}`);
+          }
+        }
+        lines.push('');
+      }
+
+      // Links
+      if (data.links && data.links.length > 0) {
+        lines.push(`Links (${data.links.length}):`);
+        for (const l of data.links) {
+          lines.push(`  "${l.text || '(no text)'}" → ${l.href} — selector: ${l.selector}`);
+        }
+        lines.push('');
+      }
+
+      // Images
+      if (data.images && data.images.length > 0) {
+        lines.push(`Images (${data.images.length}):`);
+        for (const img of data.images) {
+          const alt = img.alt ? `"${img.alt}"` : '(no alt)';
+          lines.push(`  ${alt} src=${img.src} — selector: ${img.selector}`);
+        }
+        lines.push('');
+      }
+
+      lines.push(`Duration: ${data.duration_ms}ms`);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: lines.join('\n'),
+          },
+        ],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Inspect error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 // ─── Tool: list_devices ─────────────────────────────────────────
 server.tool(
   'list_devices',