@imenam/simple-scraper 1.0.6 → 1.0.8

package/dist/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import dotenv from 'dotenv';
+import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { z } from 'zod';
@@ -9,6 +10,7 @@ import { setupLogging } from './logger.js';
 import { getBrowser, closeBrowser, getDefaultTimeout } from './browser.js';
 import { loadAllCookies } from './cookies.js';
 import { GuiLauncher } from '@imenam/mcp-gui-interface';
+import { createSession, getSession, closeSession, closeAllSessions, listSessions, getSessionLogs, clearSessionLogs } from './sessions.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, '..');
 const envPath = path.join(rootDir, '.env');
@@ -25,6 +27,7 @@ const server = new McpServer({
     name: 'simple-scraper-mcp',
     version: '1.0.0',
 });
+// ─── One-shot helpers ─────────────────────────────────────────────────────────
 async function setCookies(page, cookies, pageUrl) {
     const prepared = cookies.map(c => {
         if (!c.domain) {
@@ -40,6 +43,129 @@ async function applyCookies(page, pageUrl) {
         await setCookies(page, cookies, pageUrl);
     }
 }
+// ─── Page-level helpers (shared between one-shot and session tools) ───────────
+async function extractInputs(page, opts) {
+    return page.evaluate(({ selector: sel, showHidden }) => {
+        function extractMeta(el) {
+            if (el.tagName === 'SELECT') {
+                const select = el;
+                return {
+                    tagName: 'SELECT',
+                    type: select.type,
+                    value: select.value,
+                    options: Array.from(select.options).map(o => ({ value: o.value, text: o.text.trim() })),
+                };
+            }
+            if (el.type === 'checkbox' || el.type === 'radio') {
+                const input = el;
+                return { tagName: 'INPUT', type: input.type, value: input.value, checked: input.checked };
+            }
+            return { tagName: el.tagName, type: el.type || 'text', value: el.value };
+        }
+        function nestValue(obj, keys, value, isArray) {
+            if (!obj)
+                obj = {};
+            if (keys.length === 0)
+                return isArray ? [value] : value;
+            const key = keys[0];
+            if (keys.length === 1) {
+                if (isArray) {
+                    return { ...obj, [key]: [...(obj[key] || []), value] };
+                }
+                return { ...obj, [key]: value };
+            }
+            return { ...obj, [key]: nestValue(obj[key] || {}, keys.slice(1), value, isArray) };
+        }
+        const scope = sel ? document.querySelector(sel) ?? document : document;
+        const query = showHidden ? 'input, select, textarea' : 'input:not([type=hidden]), select, textarea';
+        const inputs = Array.from(scope.querySelectorAll(query))
+            .filter(el => el.name);
+        const fields = inputs.reduce((page, el) => {
+            const keys = el.name.replace(/-/g, '_').replace(/\]/g, '').split('[');
+            const isArray = keys[keys.length - 1] === '';
+            if (isArray)
+                keys.pop();
+            return nestValue(page, keys, extractMeta(el), isArray);
+        }, {});
+        const buttons = Array.from((sel ? document.querySelector(sel) ?? document : document).querySelectorAll('button, input[type=submit]')).map(el => ({
+            tagName: el.tagName,
+            type: el.type || null,
+            name: el.name || null,
+            value: el.value || null,
+            text: el.textContent?.trim() || null,
+            id: el.id || null,
+            class: el.className || null,
+        }));
+        return { ...fields, buttons };
+    }, opts);
+}
+async function extractShowPage(page, opts) {
+    return page.evaluate((payload) => {
+        const { keysMap: km, boxSelector: bs, tablesMaxItems } = payload;
+        function cleanText(text) {
+            return text
+                .split('\n')
+                .map(s => s.trim())
+                .filter(Boolean)
+                .join(' ')
+                .trim();
+        }
+        function parseKeyValueBox(box) {
+            const result = {};
+            Array.from(box.querySelectorAll('.box-body > .row > div')).forEach(entry => {
+                const labelEl = entry.querySelector('strong');
+                const valueEl = entry.querySelector('p');
+                if (!labelEl)
+                    return;
+                let key = cleanText(labelEl.textContent || '');
+                if (km[key])
+                    key = km[key];
+                result[key] = valueEl ? cleanText(valueEl.textContent || '') : '';
+            });
+            return result;
+        }
+        function parseTableBox(table) {
+            const dataRows = Array.from(table.querySelectorAll('tbody tr'))
+                .filter(row => row.querySelector('td') !== null);
+            const theadThs = Array.from(table.querySelectorAll('thead tr th'));
+            let colKeys = null;
+            if (theadThs.length > 0) {
+                colKeys = theadThs.map((th, i) => cleanText(th.textContent || '') || `col_${i + 1}`);
+            }
+            else {
+                const firstBodyRow = table.querySelector('tbody tr');
+                if (firstBodyRow && firstBodyRow.querySelector('td') === null) {
+                    const ths = Array.from(firstBodyRow.querySelectorAll('th'));
+                    if (ths.length > 0) {
+                        colKeys = ths.map((th, i) => cleanText(th.textContent || '') || `col_${i + 1}`);
+                    }
+                }
+            }
+            return dataRows.slice(0, tablesMaxItems).map(row => {
+                const cells = Array.from(row.querySelectorAll('td'));
+                const output = {};
+                cells.forEach((td, i) => {
+                    const key = colKeys ? (colKeys[i] ?? `col_${i + 1}`) : `col_${i + 1}`;
+                    output[key] = cleanText(td.textContent || '');
+                });
+                return output;
+            });
+        }
+        const result = {};
+        const boxes = Array.from(document.querySelectorAll(bs));
+        boxes.forEach(box => {
+            const titleEl = box.querySelector('.box-header h3, .box-header h4') ??
+                box.querySelector('.box-body > h3, .box-body > h4');
+            const title = titleEl ? cleanText(titleEl.textContent || '') : '';
+            const key = title || `section_${Object.keys(result).length + 1}`;
+            const hasKvPairs = box.querySelector('.box-body > .row > div strong') !== null;
+            const table = box.querySelector('.dataTables_scrollBody table') ??
+                box.querySelector('table');
+            result[key] = hasKvPairs ? parseKeyValueBox(box) : (table ? parseTableBox(table) : parseKeyValueBox(box));
+        });
+        return result;
+    }, opts);
+}
 // ─── scrape_page ──────────────────────────────────────────────────────────────
 server.tool('scrape_page', 'Navigate to a URL using a headless browser and return the full rendered HTML content of the page.', {
     url: z.string().url().describe('URL of the page to scrape'),
@@ -67,9 +193,9 @@ server.tool('scrape_page', 'Navigate to a URL using a headless browser and retur
     }
 });
 // ─── execute_js ───────────────────────────────────────────────────────────────
-server.tool('execute_js', 'Navigate to a URL and execute custom JavaScript code in the page context. Returns the result of the script execution.', {
+server.tool('execute_js', 'Navigate to a URL and execute custom JavaScript in the page context. The script is executed as a JavaScript function body with new Function(script)(), so it must use an explicit return statement to send data back to the tool. A bare expression such as document.title returns undefined. Return serializable values only; objects and arrays are returned as formatted JSON, primitives as text. For async work, return a Promise, for example: return (async () => { /* ... */ return data; })();', {
     url: z.string().url().describe('URL of the page'),
-    script: z.string().describe('JavaScript code to execute in the page context'),
+    script: z.string().describe('JavaScript function body to execute in the page context. Use an explicit return statement to provide the tool result, e.g. return { title: document.title };. Bare expressions such as document.title evaluate to undefined because the code runs via new Function(script)(). For async code, return a Promise, e.g. return (async () => { return await fetch("/api/data").then(r => r.json()); })();'),
     wait_for: z.string().optional().describe('CSS selector to wait for before executing the script'),
     timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
 }, async ({ url, script, wait_for, timeout }) => {
@@ -99,14 +225,29 @@ server.tool('execute_js', 'Navigate to a URL and execute custom JavaScript code
     }
 });
 // ─── get_page_inputs ──────────────────────────────────────────────────────────
-server.tool('get_page_inputs', 'Navigate to a URL and return a structured JSON object representing all form inputs (input, select, textarea) found on the page, organized by their name attributes.', {
-    url: z.string().url().describe('URL of the page'),
+server.tool('get_page_inputs', 'Return a structured JSON object of all form inputs (input, select, textarea) found on a page. If session_id is provided, extracts inputs from the active session page without navigating. If url is provided, opens a one-shot page, extracts, and closes. Exactly one of session_id or url must be provided.', {
+    session_id: z.string().optional().describe('Session ID of an active browser session. If provided, url is ignored.'),
+    url: z.string().url().optional().describe('URL of the page (one-shot mode, required if session_id is not provided)'),
     selector: z.string().optional().describe('CSS selector to scope the search (e.g. "#my-form")'),
-    wait_for: z.string().optional().describe('CSS selector to wait for before extracting inputs'),
+    wait_for: z.string().optional().describe('CSS selector to wait for before extracting inputs (one-shot mode only)'),
     show_hidden: z.boolean().optional().describe('Include input[type=hidden] fields (default: false)'),
     timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
-}, async ({ url, selector, wait_for, show_hidden, timeout }) => {
+}, async ({ session_id, url, selector, wait_for, show_hidden, timeout }) => {
     const effectiveTimeout = timeout ?? getDefaultTimeout();
+    if (!session_id && !url) {
+        return { content: [{ type: 'text', text: 'Error: either session_id or url must be provided.' }], isError: true };
+    }
+    if (session_id) {
+        try {
+            const page = getSession(session_id);
+            const result = await extractInputs(page, { selector, showHidden: show_hidden ?? false });
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+        }
+    }
     const browser = await getBrowser();
     const page = await browser.newPage();
     try {
@@ -115,59 +256,7 @@ server.tool('get_page_inputs', 'Navigate to a URL and return a structured JSON o
         if (wait_for) {
             await page.waitForSelector(wait_for, { timeout: effectiveTimeout });
         }
-        const result = await page.evaluate(({ selector: sel, showHidden }) => {
-            function extractMeta(el) {
-                if (el.tagName === 'SELECT') {
-                    const select = el;
-                    return {
-                        tagName: 'SELECT',
-                        type: select.type,
-                        value: select.value,
-                        options: Array.from(select.options).map(o => ({ value: o.value, text: o.text.trim() })),
-                    };
-                }
-                if (el.type === 'checkbox' || el.type === 'radio') {
-                    const input = el;
-                    return { tagName: 'INPUT', type: input.type, value: input.value, checked: input.checked };
-                }
-                return { tagName: el.tagName, type: el.type || 'text', value: el.value };
-            }
-            function nestValue(obj, keys, value, isArray) {
-                if (!obj)
-                    obj = {};
-                if (keys.length === 0)
-                    return isArray ? [value] : value;
-                const key = keys[0];
-                if (keys.length === 1) {
-                    if (isArray) {
-                        return { ...obj, [key]: [...(obj[key] || []), value] };
-                    }
-                    return { ...obj, [key]: value };
-                }
-                return { ...obj, [key]: nestValue(obj[key] || {}, keys.slice(1), value, isArray) };
-            }
-            const scope = sel ? document.querySelector(sel) ?? document : document;
-            const query = showHidden ? 'input, select, textarea' : 'input:not([type=hidden]), select, textarea';
-            const inputs = Array.from(scope.querySelectorAll(query))
-                .filter(el => el.name);
-            const fields = inputs.reduce((page, el) => {
-                const keys = el.name.replace(/-/g, '_').replace(/\]/g, '').split('[');
-                const isArray = keys[keys.length - 1] === '';
-                if (isArray)
-                    keys.pop();
-                return nestValue(page, keys, extractMeta(el), isArray);
-            }, {});
-            const buttons = Array.from((sel ? document.querySelector(sel) ?? document : document).querySelectorAll('button, input[type=submit]')).map(el => ({
-                tagName: el.tagName,
-                type: el.type || null,
-                name: el.name || null,
-                value: el.value || null,
-                text: el.textContent?.trim() || null,
-                id: el.id || null,
-                class: el.className || null,
-            }));
-            return { ...fields, buttons };
-        }, { selector, showHidden: show_hidden ?? false });
+        const result = await extractInputs(page, { selector, showHidden: show_hidden ?? false });
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     }
     catch (error) {
@@ -202,89 +291,321 @@ server.tool('get_show_page', 'Navigate to a URL and automatically parse a show/d
         if (wait_for) {
             await page.waitForSelector(wait_for, { timeout: effectiveTimeout });
         }
-        const result = await page.evaluate((payload) => {
-            const { keysMap: km, boxSelector: bs, tablesMaxItems } = payload;
-            function cleanText(text) {
-                return text
-                    .split('\n')
-                    .map(s => s.trim())
-                    .filter(Boolean)
-                    .join(' ')
-                    .trim();
+        const result = await extractShowPage(page, {
+            keysMap: keys_map ?? {},
+            boxSelector: box_selector ?? '.box.box-primary',
+            tablesMaxItems: tables_max_items ?? 2,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+    finally {
+        await page.close();
+    }
+});
+// ─── open_session ─────────────────────────────────────────────────────────────
+server.tool('open_session', 'Open a persistent browser session on a URL. The page stays alive between tool calls, allowing you to interact with it (click, type, evaluate JS, etc.) before taking a screenshot or extracting data. Returns a session_id to use with all session_* tools and screenshot.', {
+    url: z.string().url().describe('URL to navigate to when opening the session'),
+    wait_for: z.string().optional().describe('CSS selector to wait for before the session is considered ready'),
+    timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
+}, async ({ url, wait_for, timeout }) => {
+    try {
+        const sessionId = await createSession(url, { waitFor: wait_for, timeout });
+        return { content: [{ type: 'text', text: JSON.stringify({ session_id: sessionId }) }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── close_session ────────────────────────────────────────────────────────────
+server.tool('close_session', 'Close a persistent browser session and free its resources. Always call this when you are done with a session.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+}, async ({ session_id }) => {
+    try {
+        await closeSession(session_id);
+        return { content: [{ type: 'text', text: `Session "${session_id}" closed.` }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── list_sessions ────────────────────────────────────────────────────────────
+server.tool('list_sessions', 'List all currently active browser sessions with their ID and activity timestamps.', {}, async () => {
+    const all = listSessions();
+    return { content: [{ type: 'text', text: JSON.stringify(all, null, 2) }] };
+});
+// ─── session_goto ─────────────────────────────────────────────────────────────
+server.tool('session_goto', 'Navigate the browser session to a new URL without closing the session.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    url: z.string().url().describe('URL to navigate to'),
+    wait_for: z.string().optional().describe('CSS selector to wait for after navigation'),
+    timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
+}, async ({ session_id, url, wait_for, timeout }) => {
+    const effectiveTimeout = timeout ?? getDefaultTimeout();
+    try {
+        const page = getSession(session_id);
+        await page.goto(url, { waitUntil: 'networkidle2', timeout: effectiveTimeout });
+        if (wait_for) {
+            await page.waitForSelector(wait_for, { timeout: effectiveTimeout });
+        }
+        return { content: [{ type: 'text', text: `Navigated to ${url}` }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_click ────────────────────────────────────────────────────────────
+server.tool('session_click', 'Click on an element in the browser session identified by a CSS selector.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    selector: z.string().describe('CSS selector of the element to click'),
+    timeout: z.number().optional().describe('Timeout in milliseconds to wait for the element (default: 30000)'),
+}, async ({ session_id, selector, timeout }) => {
+    const effectiveTimeout = timeout ?? getDefaultTimeout();
+    try {
+        const page = getSession(session_id);
+        await page.waitForSelector(selector, { timeout: effectiveTimeout });
+        await page.click(selector);
+        return { content: [{ type: 'text', text: `Clicked "${selector}"` }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_type ─────────────────────────────────────────────────────────────
+server.tool('session_type', 'Type text into an input element in the browser session. Optionally clears the field first.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    selector: z.string().describe('CSS selector of the input element'),
+    text: z.string().describe('Text to type into the element'),
+    clear: z.boolean().optional().describe('Clear the field before typing (default: false)'),
+    timeout: z.number().optional().describe('Timeout in milliseconds to wait for the element (default: 30000)'),
+}, async ({ session_id, selector, text, clear, timeout }) => {
+    const effectiveTimeout = timeout ?? getDefaultTimeout();
+    try {
+        const page = getSession(session_id);
+        await page.waitForSelector(selector, { timeout: effectiveTimeout });
+        if (clear) {
+            await page.click(selector, { clickCount: 3 });
+        }
+        await page.type(selector, text);
+        return { content: [{ type: 'text', text: `Typed into "${selector}"` }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_wait_for ─────────────────────────────────────────────────────────
+server.tool('session_wait_for', 'Wait for a CSS selector to appear in the active browser session page. Returns a confirmation message on success, or an error if the selector does not appear before the timeout.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    selector: z.string().describe('CSS selector to wait for'),
+    timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
+}, async ({ session_id, selector, timeout }) => {
+    const effectiveTimeout = timeout ?? getDefaultTimeout();
+    try {
+        const page = getSession(session_id);
+        await page.waitForSelector(selector, { timeout: effectiveTimeout });
+        return { content: [{ type: 'text', text: `Selector "${selector}" found.` }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_evaluate ─────────────────────────────────────────────────────────
+server.tool('session_evaluate', 'Execute custom JavaScript in the context of an active browser session page. Same conventions as execute_js: use an explicit return statement, return serializable values only.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    script: z.string().describe('JavaScript function body to execute. Use an explicit return statement to get a result back.'),
+    wait_for: z.string().optional().describe('CSS selector to wait for before executing the script'),
+    timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
+}, async ({ session_id, script, wait_for, timeout }) => {
+    const effectiveTimeout = timeout ?? getDefaultTimeout();
+    try {
+        const page = getSession(session_id);
+        if (wait_for) {
+            await page.waitForSelector(wait_for, { timeout: effectiveTimeout });
+        }
+        const result = await page.evaluate((code) => {
+            return new Function(code)();
+        }, script);
+        const serialized = typeof result === 'object' && result !== null
+            ? JSON.stringify(result, null, 2)
+            : String(result ?? 'undefined');
+        return { content: [{ type: 'text', text: serialized }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_html ─────────────────────────────────────────────────────────────
+server.tool('session_html', 'Return the current full rendered HTML of an active browser session page.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+}, async ({ session_id }) => {
+    try {
+        const page = getSession(session_id);
+        const html = await page.content();
+        return { content: [{ type: 'text', text: html }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_query_selector ───────────────────────────────────────────────────
+server.tool('session_query_selector', 'Query the active session page with a CSS selector and return matching elements with their key attributes (tagName, id, class, textContent, href, name, type, value). Useful for finding the right selector before clicking or typing.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    selector: z.string().describe('CSS selector to query'),
+    limit: z.number().optional().describe('Max number of elements to return (default: 10)'),
+}, async ({ session_id, selector, limit }) => {
+    try {
+        const page = getSession(session_id);
+        const results = await page.$$eval(selector, (elements, maxItems) => elements.slice(0, maxItems).map(el => {
+            const text = (el.textContent ?? '').trim().slice(0, 100);
+            return {
+                tagName: el.tagName,
+                id: el.id || null,
+                class: el.className || null,
+                textContent: text || null,
+                href: el.href || null,
+                name: el.name || null,
+                type: el.type || null,
+                value: el.value || null,
+            };
+        }), limit ?? 10);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_get_console_logs ─────────────────────────────────────────────────
+server.tool('session_get_console_logs', 'Return all console messages (log, warn, error, info, debug, …) captured from the active browser session page since it was opened or last cleared.', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    clear: z.boolean().optional().describe('Clear the log buffer after reading (default: false)'),
+}, async ({ session_id, clear }) => {
+    try {
+        const logs = getSessionLogs(session_id);
+        if (clear)
+            clearSessionLogs(session_id);
+        return { content: [{ type: 'text', text: JSON.stringify({ logs }, null, 2) }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── session_scroll ───────────────────────────────────────────────────────────
+server.tool('session_scroll', 'Scroll the active session page. Use selector to scroll a specific element into view, or x/y to scroll by a pixel amount, or to_bottom: true to scroll to the page bottom (useful for triggering lazy-load).', {
+    session_id: z.string().describe('Session ID returned by open_session'),
+    selector: z.string().optional().describe('CSS selector of an element to scroll into view'),
+    x: z.number().optional().describe('Horizontal scroll offset in pixels'),
+    y: z.number().optional().describe('Vertical scroll offset in pixels'),
+    to_bottom: z.boolean().optional().describe('Scroll to the very bottom of the page'),
+}, async ({ session_id, selector, x, y, to_bottom }) => {
+    if (!selector && !to_bottom && x == null && y == null) {
+        return { content: [{ type: 'text', text: 'Error: provide at least one of selector, to_bottom, x, or y.' }], isError: true };
+    }
+    try {
+        const page = getSession(session_id);
+        if (selector) {
+            await page.$eval(selector, el => el.scrollIntoView());
+            return { content: [{ type: 'text', text: `Scrolled "${selector}" into view.` }] };
+        }
+        if (to_bottom) {
+            await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+            return { content: [{ type: 'text', text: 'Scrolled to bottom of page.' }] };
+        }
+        await page.evaluate((dx, dy) => window.scrollBy(dx, dy), x ?? 0, y ?? 0);
+        return { content: [{ type: 'text', text: `Scrolled by x=${x ?? 0}, y=${y ?? 0}.` }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+    }
+});
+// ─── screenshot ───────────────────────────────────────────────────────────────
+server.tool('screenshot', 'Take a screenshot of a page. Provide either session_id (captures the page in its current interactive state) or url (one-shot: navigates, captures, closes). The selector parameter restricts the capture to a specific element. output controls the return format: "inline" returns a base64 image directly in the response, "file" writes the image to disk and returns the path, "both" does both.', {
+    session_id: z.string().optional().describe('Session ID of an active browser session. If provided, url is ignored and the current page state is captured.'),
+    url: z.string().url().optional().describe('URL to navigate to for a one-shot screenshot (required if session_id is not provided)'),
+    wait_for: z.string().optional().describe('CSS selector to wait for before capturing (one-shot mode only)'),
+    timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000)'),
+    selector: z.string().optional().describe('CSS selector of a specific element to capture instead of the full page'),
+    full_page: z.boolean().optional().describe('Capture the full scrollable page height (default: false, ignored when selector is provided)'),
+    format: z.enum(['png', 'jpeg']).optional().describe('Image format (default: png)'),
+    output: z.enum(['inline', 'file', 'both']).describe('Return format: "inline" embeds the image in the response, "file" saves to disk and returns the path, "both" does both'),
+    path: z.string().optional().describe('Absolute or relative file path for the saved image (used when output is "file" or "both"). Relative paths are resolved from the MCP server\'s working directory. Defaults to <server_root>/screenshots/<timestamp>.<format>'),
+}, async ({ session_id, url, wait_for, timeout, selector, full_page, format, output, path: filePath }) => {
+    const effectiveTimeout = timeout ?? getDefaultTimeout();
+    const fmt = format ?? 'png';
+    const mimeType = fmt === 'jpeg' ? 'image/jpeg' : 'image/png';
+    let page = null;
+    let ownedPage = false;
+    try {
+        if (session_id) {
+            page = getSession(session_id);
+        }
+        else {
+            if (!url) {
+                return { content: [{ type: 'text', text: 'Error: either session_id or url must be provided.' }], isError: true };
             }
-            function parseKeyValueBox(box) {
-                const result = {};
-                Array.from(box.querySelectorAll('.box-body > .row > div')).forEach(entry => {
-                    const labelEl = entry.querySelector('strong');
-                    const valueEl = entry.querySelector('p');
-                    if (!labelEl)
-                        return;
-                    let key = cleanText(labelEl.textContent || '');
-                    if (km[key])
-                        key = km[key];
-                    result[key] = valueEl ? cleanText(valueEl.textContent || '') : '';
-                });
-                return result;
+            const browser = await getBrowser();
+            page = await browser.newPage();
+            ownedPage = true;
+            await applyCookies(page, url);
+            await page.goto(url, { waitUntil: 'networkidle2', timeout: effectiveTimeout });
+            if (wait_for) {
+                await page.waitForSelector(wait_for, { timeout: effectiveTimeout });
             }
-            function parseTableBox(table) {
-                // Rows with actual data (exclude <tbody tr> that contain only <th>, e.g. AdminLTE sub-headers)
-                const dataRows = Array.from(table.querySelectorAll('tbody tr'))
-                    .filter(row => row.querySelector('td') !== null);
-                // 1st attempt: standard <thead th>
-                const theadThs = Array.from(table.querySelectorAll('thead tr th'));
-                let colKeys = null;
-                if (theadThs.length > 0) {
-                    colKeys = theadThs.map((th, i) => cleanText(th.textContent || '') || `col_${i + 1}`);
-                }
-                else {
-                    // 2nd attempt: first <tbody tr> containing only <th> (AdminLTE pattern)
-                    const firstBodyRow = table.querySelector('tbody tr');
-                    if (firstBodyRow && firstBodyRow.querySelector('td') === null) {
-                        const ths = Array.from(firstBodyRow.querySelectorAll('th'));
-                        if (ths.length > 0) {
-                            colKeys = ths.map((th, i) => cleanText(th.textContent || '') || `col_${i + 1}`);
-                        }
-                    }
-                }
-                return dataRows.slice(0, tablesMaxItems).map(row => {
-                    const cells = Array.from(row.querySelectorAll('td'));
-                    const output = {};
-                    cells.forEach((td, i) => {
-                        const key = colKeys ? (colKeys[i] ?? `col_${i + 1}`) : `col_${i + 1}`;
-                        output[key] = cleanText(td.textContent || '');
-                    });
-                    return output;
-                });
+        }
+        let imageBuffer;
+        if (selector) {
+            await page.waitForSelector(selector, { timeout: effectiveTimeout });
+            const element = await page.$(selector);
+            if (!element) {
+                return { content: [{ type: 'text', text: `Error: selector "${selector}" not found.` }], isError: true };
             }
-            const result = {};
-            const boxes = Array.from(document.querySelectorAll(bs));
-            boxes.forEach(box => {
-                // Support both standard AdminLTE pattern (.box-header h3) and
-                // inline title pattern where h3/h4 is placed directly inside .box-body.
-                const titleEl = box.querySelector('.box-header h3, .box-header h4') ??
-                    box.querySelector('.box-body > h3, .box-body > h4');
-                const title = titleEl ? cleanText(titleEl.textContent || '') : '';
-                const key = title || `section_${Object.keys(result).length + 1}`;
-                // Prefer key-value parsing if the box has strong/p pairs,
-                // only fall back to table parsing when there are no such pairs.
-                const hasKvPairs = box.querySelector('.box-body > .row > div strong') !== null;
-                // DataTables with scrollY splits the table into two: a header-only table
-                // inside .dataTables_scrollHeadInner and the actual data table inside
-                // .dataTables_scrollBody. Always prefer the scroll-body table when present.
-                const table = box.querySelector('.dataTables_scrollBody table') ??
-                    box.querySelector('table');
-                result[key] = hasKvPairs ? parseKeyValueBox(box) : (table ? parseTableBox(table) : parseKeyValueBox(box));
-            });
-            return result;
-        }, { keysMap: keys_map ?? {}, boxSelector: box_selector ?? '.box.box-primary', tablesMaxItems: tables_max_items ?? 2 });
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            imageBuffer = Buffer.from(await element.screenshot({ type: fmt }));
+        }
+        else {
+            imageBuffer = Buffer.from(await page.screenshot({ type: fmt, fullPage: full_page ?? false }));
+        }
+        const base64 = imageBuffer.toString('base64');
+        // Resolve file path
+        const resolvedPath = (() => {
+            if (filePath)
+                return path.resolve(filePath);
+            const ts = Date.now();
+            const dir = path.join(rootDir, 'screenshots');
+            return path.join(dir, `screenshot-${ts}.${fmt}`);
+        })();
+        const resultContent = [];
+        if (output === 'inline' || output === 'both') {
+            resultContent.push({ type: 'image', data: base64, mimeType });
+        }
+        if (output === 'file' || output === 'both') {
+            const dir = path.dirname(resolvedPath);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(resolvedPath, imageBuffer);
+            resultContent.push({ type: 'text', text: `Screenshot saved to: ${resolvedPath}` });
+        }
+        return { content: resultContent };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
     }
     finally {
-        await page.close();
+        if (ownedPage && page) {
+            await page.close();
+        }
     }
 });
 async function main() {
@@ -300,6 +621,7 @@ async function main() {
 }
 main().catch(async (err) => {
     console.error('[MCP] Fatal error:', err);
+    await closeAllSessions();
     await closeBrowser();
     process.exit(1);
 });