pagebolt-mcp 1.6.0 → 1.7.1

package/README.md

@@ -8,6 +8,8 @@ Take screenshots, generate PDFs, create OG images, inspect pages, and record dem
 
 **Works with Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client.**
 
+<img width="1280" height="1279" alt="pagebolt-screenshot_1" src="https://github.com/user-attachments/assets/fd21a372-df4d-41cd-baf4-5b6dd6a9a685" />
+
 ---
 
 ## What It Does

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagebolt-mcp",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "MCP server for PageBolt — take screenshots, generate PDFs, create OG images, inspect pages, record demo videos with Audio Guide narration, from AI coding assistants like Claude, Cursor, and Windsurf.",
   "main": "src/index.mjs",
   "module": "src/index.mjs",

package/src/index.mjs

@@ -57,7 +57,7 @@ async function callApi(endpoint, options = {}) {
   const method = options.method || 'GET';
   const headers = {
     'x-api-key': API_KEY,
-    'user-agent': 'pagebolt-mcp/1.5.2',
+    'user-agent': 'pagebolt-mcp/1.7.0',
     ...(options.body ? { 'Content-Type': 'application/json' } : {}),
   };
 
@@ -146,6 +146,8 @@ PageBolt gives you 8 tools for web capture and browser automation. All tools use
 | inspect_page | Get structured map of page elements with CSS selectors | 1 request |
 | list_devices | List 25+ device presets (iPhone, iPad, MacBook, etc.) | 0 (free) |
 | check_usage | Check current API usage and plan limits | 0 (free) |
+| create_session | Create a persistent browser session (Starter+ only) | 0 (free to create) |
+| destroy_session | Destroy a persistent browser session | 0 (free) |
 
 ## Key Workflow: Inspect Before You Interact
 
@@ -168,13 +170,17 @@ record_video supports polished video output:
 - frame: { enabled: true, style: "macos" } — browser chrome around the video
 - background: { enabled: true, type: "gradient", gradient: "ocean" } — gradient/glass background with padding
 - cursor: { style: "classic", persist: true } — always-visible cursor
-- Per-step zoom: add zoom: { enabled: true } on click steps
 - **Step notes (IMPORTANT)**: Add a "note" field to EVERY action step for guided-tour-style tooltip annotations. Notes appear as beautiful styled tooltips near the element being interacted with. Example: { action: "click", selector: "#btn", note: "Click here to open settings" }. The only steps that should NOT have notes are wait/wait_for pauses.
 - **Audio Guide**: Add audioGuide: { enabled: true, script: "Welcome. {{1}} Click here. {{2}} Done." } for AI voice narration. Two modes: (1) Per-step — add "narration" text to individual steps. (2) Script — provide a single "script" with {{N}} markers for continuous narration synchronized to steps.
 - Audio Guide voices: ava, andrew, emma, brian, aria, guy, jenny, davis, christopher, michelle (Azure) or alloy, echo, fable, nova, onyx, shimmer (OpenAI).
-- **Live wait steps**: Add live: true to wait steps to capture animated content (transitions, loading spinners) instead of freezing the last frame.
 - **Variables**: Pass variables: { "base_url": "https://example.com" } and use {{base_url}} in step URLs/values for reusable recordings.
 
+## IMPORTANT: Video Step Best Practices
+
+- **Do NOT add wait steps between every action.** The "pace" parameter already adds natural pauses between steps. Only use wait when: (1) the page needs time to load after navigation, or (2) you want to hold on a view for narration. A typical video should have very few wait steps.
+- **Do NOT use zoom unless the user explicitly asks for it.** Zoom adds visual complexity and encoding time. Omit zoom entirely by default.
+- **Keep videos concise.** A good demo has 5-15 action steps (navigate, click, fill, hover, scroll). More steps = longer encoding time and larger files.
+
 ## Common Parameters (available on most tools)
 
 - blockBanners: true — hides cookie consent banners (GDPR popups, OneTrust, CookieBot, etc.)
@@ -213,7 +219,7 @@ Use blockBanners on almost every request to get clean captures. Combine blockAds
 function createConfiguredServer() {
   const srv = new McpServer({
     name: 'pagebolt',
-    version: '1.5.0',
+    version: '1.7.0',
   }, {
     instructions: SERVER_INSTRUCTIONS,
   });
@@ -300,6 +306,8 @@ server.tool(
     extractMetadata: z.boolean().optional().describe('Extract page metadata (title, description, OG tags) alongside the screenshot'),
     // ── Styling ──
     style: styleSchema,
+    // ── Session ──
+    session_id: z.string().optional().describe('Persistent session ID (Starter+ only). Reuse a live browser page created with create_session — browser state (cookies, localStorage, auth) carries over from previous requests in this session.'),
   },
   async (params) => {
     if (!params.url && !params.html && !params.markdown) {
@@ -479,7 +487,7 @@ server.tool(
           'screenshot', 'pdf',
         ]).describe('The action to perform'),
         url: z.string().url().optional().describe('URL to navigate to (for navigate action)'),
-        selector: z.string().optional().describe('CSS selector for the target element'),
+        selector: z.string().optional().describe('CSS selector for the target element (also used for element screenshots)'),
         value: z.string().optional().describe('Value to type or select'),
         ms: z.number().int().min(0).max(10000).optional().describe('Milliseconds to wait (for wait action)'),
         timeout: z.number().int().min(0).max(15000).optional().describe('Timeout in ms for wait_for (default: 10000)'),
@@ -491,7 +499,6 @@ server.tool(
         fullPage: z.boolean().optional().describe('Capture full scrollable page (for screenshot action)'),
         fullPageScroll: z.boolean().optional().describe('Auto-scroll for lazy images (for screenshot action)'),
         quality: z.number().int().min(1).max(100).optional().describe('JPEG/WebP quality (for screenshot action)'),
-        selector: z.string().optional().describe('Element selector (for screenshot action)'),
         omitBackground: z.boolean().optional().describe('Transparent background (for screenshot action)'),
         delay: z.number().int().min(0).max(10000).optional().describe('Pre-capture delay in ms (for screenshot action)'),
         landscape: z.boolean().optional().describe('Landscape orientation (for pdf action)'),
@@ -511,6 +518,7 @@ server.tool(
     blockChats: z.boolean().optional().describe('Block live chat widgets'),
     blockTrackers: z.boolean().optional().describe('Block tracking scripts'),
     deviceScaleFactor: z.number().min(1).max(3).optional().describe('Device pixel ratio (default: 1)'),
+    session_id: z.string().optional().describe('Persistent session ID (Starter+ only). Reuse a live browser page created with create_session — browser state (cookies, localStorage, auth) carries over from previous requests in this session.'),
   },
   async (params) => {
     if (!params.steps || params.steps.length === 0) {
@@ -565,7 +573,7 @@ server.tool(
 // ═══════════════════════════════════════════════════════════════════
 server.tool(
   'record_video',
-  'Record a professional demo video of a multi-step browser automation sequence. Produces MP4/WebM/GIF with cursor highlighting, click effects, smooth movement, per-step zoom, step notes, browser frame (macOS/Windows), gradient/glass backgrounds, and more. Costs 3 API requests. Saves to disk.',
+  'Record a professional demo video of a multi-step browser automation sequence. Produces MP4/WebM/GIF with cursor highlighting, click effects, smooth movement, step notes, browser frame (macOS/Windows), gradient/glass backgrounds, and more. Costs 3 API requests. Saves to disk. BEST PRACTICE: Keep videos concise (5-15 action steps). Do NOT add wait steps between every action — the pace parameter handles timing. Only use wait for page loads or narration holds. Do NOT use zoom unless the user explicitly asks for it.',
   {
     steps: z.array(
       z.object({
@@ -576,7 +584,7 @@ server.tool(
         url: z.string().url().optional().describe('URL to navigate to (for navigate action)'),
         selector: z.string().optional().describe('CSS selector for the target element'),
         value: z.string().optional().describe('Value to type or select'),
-        ms: z.number().int().min(0).max(10000).optional().describe('Milliseconds to wait (for wait action)'),
+        ms: z.number().int().min(0).max(10000).optional().describe('Milliseconds to wait (for wait action). Only use wait steps when the page needs loading time or to hold for narration — the pace parameter handles inter-step timing automatically.'),
         timeout: z.number().int().min(0).max(15000).optional().describe('Timeout in ms for wait_for (default: 10000)'),
         x: z.number().optional().describe('Horizontal scroll position'),
         y: z.number().optional().describe('Vertical scroll position'),
@@ -585,11 +593,11 @@ server.tool(
         narration: z.string().max(500).optional().describe('Text to speak at this step (max 500 chars, requires audioGuide.enabled). Used in per-step mode.'),
         live: z.boolean().optional().describe('For wait steps: true captures animated content in real-time, false freezes a single frame (default: false)'),
         zoom: z.object({
-          enabled: z.boolean().optional().describe('Enable zoom on this step (default: false)'),
+          enabled: z.boolean().optional().describe('Enable zoom on this step (default: false). Only use when user explicitly requests zoom.'),
           level: z.number().min(1.2).max(4).optional().describe('Zoom magnification (inherits from global zoom.level if not set)'),
-        }).optional().describe('Per-step zoom override (for click/dblclick steps). Overrides global zoom settings.'),
+        }).optional().describe('Per-step zoom override. Do NOT add zoom unless the user specifically requests it — it adds encoding time and visual complexity.'),
       })
-    ).min(1).max(50).describe('Array of steps to execute and record. Max steps depends on plan (10-50).'),
+    ).min(1).max(50).describe('Array of action steps to record. Keep concise: 5-15 steps is ideal. Do NOT pad with wait steps — pace handles timing.'),
     viewport: z.object({
       width: z.number().int().min(320).max(3840).optional().describe('Viewport width (default: 1280)'),
       height: z.number().int().min(200).max(2160).optional().describe('Viewport height (default: 720)'),
@@ -612,8 +620,8 @@ server.tool(
       level: z.number().min(1.2).max(4).optional().describe('Default zoom magnification (default: 1.5)'),
       duration: z.number().int().min(400).max(3000).optional().describe('Zoom animation duration in ms (default: 1200)'),
       easing: z.enum(['ease-in-out', 'linear', 'ease']).optional().describe('Zoom animation easing (default: ease-in-out)'),
-    }).optional().describe('Global zoom settings. Per-step zoom on click/dblclick steps overrides these.'),
-    autoZoom: z.boolean().optional().describe('Shorthand: set to true to enable auto-zoom with defaults (same as zoom.enabled=true)'),
+    }).optional().describe('Global zoom settings. Only use when the user explicitly requests zoom. Do NOT enable by default.'),
+    autoZoom: z.boolean().optional().describe('Enable auto-zoom on all clicks (default: false). Only use when user explicitly requests zoom.'),
     // ── Click effects ──
     clickEffect: z.object({
       enabled: z.boolean().optional().describe('Show click ripple effects (default: true)'),
@@ -935,6 +943,87 @@ server.tool(
   }
 );
 
+// ═══════════════════════════════════════════════════════════════════
+// Tool: create_session — Persistent browser session (Starter+ only)
+// ═══════════════════════════════════════════════════════════════════
+server.tool(
+  'create_session',
+  'Create a persistent browser session (Starter+ plan required). The session keeps a live browser page open so you can reuse cookies, localStorage, and auth state across multiple take_screenshot or run_sequence calls. Pass the returned session_id to those tools. Sessions expire after 10 minutes of inactivity (hard cap: 30 minutes). Useful for AI agent workflows that log in once and then take multiple screenshots of authenticated pages.',
+  {
+    cookies: z.array(cookieSchema).optional().describe('Cookies to pre-load into the session browser page'),
+    viewport: z.object({
+      width: z.number().int().optional(),
+      height: z.number().int().optional(),
+    }).optional().describe('Viewport dimensions for the session browser page'),
+    stealth: z.boolean().optional().describe('Launch this session with stealth mode (bypasses bot detection). Note: stealth sessions use a dedicated browser and consume more memory.'),
+  },
+  async (params) => {
+    const res = await callApi('/api/v1/sessions', {
+      method: 'POST',
+      body: params,
+    });
+    const data = await res.json();
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `Session created.\n` +
+            `  session_id: ${data.session_id}\n` +
+            `  expires_at: ${data.expires_at}\n\n` +
+            `Pass session_id to take_screenshot or run_sequence to reuse this browser page.\n` +
+            `Note: ${data.note || 'Sessions do not persist across server restarts.'}`,
+        },
+      ],
+    };
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════
+// Tool: list_sessions — List active persistent browser sessions
+// ═══════════════════════════════════════════════════════════════════
+server.tool(
+  'list_sessions',
+  'List all active persistent browser sessions for your API key. Returns session IDs, creation times, and expiry times. Useful for checking which sessions are still alive before reusing them.',
+  {},
+  async () => {
+    const data = await callApi('/api/v1/sessions', { method: 'GET' });
+    const sessions = data.sessions || [];
+    if (sessions.length === 0) {
+      return { content: [{ type: 'text', text: 'No active sessions.' }] };
+    }
+    const lines = sessions.map(s =>
+      `• ${s.session_id}  expires: ${s.expires_at}  created: ${s.created_at}`
+    );
+    return {
+      content: [{ type: 'text', text: `Active sessions (${sessions.length}):\n${lines.join('\n')}` }],
+    };
+  }
+);
+
+// Tool: destroy_session — Explicitly close a persistent session
+// ═══════════════════════════════════════════════════════════════════
+server.tool(
+  'destroy_session',
+  'Explicitly destroy a persistent browser session before it expires. Frees the browser page immediately. Use this when you are done with a session to free up capacity.',
+  {
+    session_id: z.string().describe('The session ID to destroy (returned by create_session)'),
+  },
+  async (params) => {
+    await callApi(`/api/v1/sessions/${encodeURIComponent(params.session_id)}`, {
+      method: 'DELETE',
+    });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Session ${params.session_id} destroyed successfully.`,
+        },
+      ],
+    };
+  }
+);
+
 } // end registerTools
 
 // ─── Prompts ────────────────────────────────────────────────────
@@ -1039,15 +1128,15 @@ Please follow this workflow:
 
 Important tips:
 - Use selectors from the inspect_page results — never guess selectors
-- Add wait steps (ms: 800-1200) between interactions for visual clarity
-- Use wait_for after navigation to ensure the page loads
+- Do NOT add wait steps between every action — the pace parameter already handles timing between steps. Only use wait when: (1) the page needs time to load new content after navigation, or (2) you need to hold on a view for narration.
+- Do NOT use zoom unless I specifically ask for it
 - **ALWAYS add a "note" field on every meaningful step** — notes render as styled tooltip annotations that explain what's happening, creating a guided tour experience. Examples:
   - navigate: note: "Opening the dashboard"
   - click: note: "This button creates a new project"
   - fill: note: "Enter your email to get started"
   - hover: note: "Hover to reveal the dropdown menu"
   - The ONLY steps without notes should be wait/wait_for (pauses)
-- Keep to 15 steps or fewer for best results
+- Keep to 5-15 action steps for best results. Fewer steps = faster encoding and smaller files.
 - Each video costs 3 API requests`,
             },
           },