@jshookmcp/jshook 0.1.8 → 0.1.9

package/dist/src/server/domains/browser/definitions.tools.security.js

@@ -0,0 +1,227 @@
+export const browserSecurityStateTools = [
+    {
+        name: 'captcha_detect',
+        description: `Detect CAPTCHA on the current page using AI vision analysis.
+
+Detection process:
+1. Takes a screenshot and analyzes it with AI (Vision LLM)
+2. Applies rule-based detection as fallback if AI unavailable
+3. Returns detection result with confidence score
+
+Supported CAPTCHA types:
+- Slider CAPTCHA: drag-to-verify style challenges
+- Image CAPTCHA: select-images challenges
+- Widget CAPTCHA: embedded checkbox or iframe-based challenges
+- Browser Check: interstitial or automatic integrity checks
+- Custom CAPTCHA implementations
+
+Response fields:
+- detected: whether CAPTCHA was found
+- type: CAPTCHA type identifier
+- providerHint: broad provider category if identified
+- confidence: detection confidence (0-100)
+- reasoning: AI analysis explanation
+- screenshotPath: saved screenshot path when a vision-capable model is unavailable
+- suggestions: recommended next steps
+
+Note:
+When the configured MCP model cannot access vision directly, the detector saves a screenshot
+to disk and returns screenshotPath together with prompt guidance in the reasoning field.
+Use an external AI (GPT-4o, Claude 3) to analyze the saved screenshot if needed.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'captcha_wait',
+        description: `Wait for the user to manually solve a CAPTCHA.
+
+Steps:
+1. CAPTCHA is detected on the page
+2. This tool polls the current page until the CAPTCHA is no longer detected
+3. User solves the CAPTCHA manually in the active browser/page
+4. Script resumes automatically after detection
+
+Note: this tool does not switch browser modes on its own.
+
+Timeout: default 300000ms (5 minutes)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                timeout: {
+                    type: 'number',
+                    description: 'Timeout in milliseconds (default: 300000 = 5 minutes)',
+                    default: 300000,
+                },
+            },
+        },
+    },
+    {
+        name: 'captcha_config',
+        description: `Configure CAPTCHA detection behavior.
+
+Parameters:
+- autoDetectCaptcha: enable CAPTCHA auto-handling for browser-mode integrations that use these settings
+- autoSwitchHeadless: allow supported integrations to switch to headed mode when CAPTCHA is detected
+- captchaTimeout: timeout for waiting user to solve CAPTCHA in ms (default: 300000)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                autoDetectCaptcha: {
+                    type: 'boolean',
+                    description: 'Whether to automatically detect CAPTCHA after navigation',
+                },
+                autoSwitchHeadless: {
+                    type: 'boolean',
+                    description: 'Whether to automatically switch to headed mode when CAPTCHA detected',
+                },
+                captchaTimeout: {
+                    type: 'number',
+                    description: 'Timeout for waiting user to complete CAPTCHA (milliseconds)',
+                },
+            },
+        },
+    },
+    {
+        name: 'stealth_inject',
+        description: `Inject modern stealth scripts to bypass bot detection.
+
+Anti-detection patches:
+1. Hide navigator.webdriver flag
+2. Inject window.chrome object
+3. Restore navigator.plugins
+4. Fix Permissions API behavior
+5. Patch Canvas fingerprinting
+6. Patch WebGL fingerprinting
+7. Restore hardware concurrency
+8. Fix Battery API responses
+9. Fix MediaDevices enumeration
+10. Fix Notification API
+
+Compatible with undetected-chromedriver, puppeteer-extra-plugin-stealth, playwright-stealth.
+Call after browser_launch for best results.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'stealth_set_user_agent',
+        description: `Set a realistic User-Agent and browser fingerprint for the target platform.
+
+Updates navigator.userAgent, navigator.platform, navigator.vendor,
+navigator.hardwareConcurrency, and navigator.deviceMemory consistently
+to avoid fingerprint inconsistencies.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    description: 'Target platform',
+                    enum: ['windows', 'mac', 'linux'],
+                    default: 'windows',
+                },
+            },
+        },
+    },
+    {
+        name: 'browser_list_tabs',
+        description: `List all open tabs/pages in the connected browser.
+
+Use this after browser_attach to see all available pages/tabs.
+Returns index, URL, and title for each tab.
+
+Workflow:
+1. browser_attach(browserURL="http://127.0.0.1:9222")
+2. browser_list_tabs() -> see all tabs with their indexes
+3. browser_select_tab(index=N) -> switch to desired tab
+
+Can also connect and list in one call:
+browser_list_tabs(browserURL="http://127.0.0.1:9222")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                browserURL: {
+                    type: 'string',
+                    description: 'Optional: connect to this browser URL before listing (e.g. http://127.0.0.1:9222)',
+                },
+            },
+        },
+    },
+    {
+        name: 'browser_select_tab',
+        description: `Switch the active tab/page by index or URL/title pattern.
+
+After browser_list_tabs, use this to activate a specific tab.
+All subsequent page_* tools will operate on the selected tab.
+
+Examples:
+- browser_select_tab(index=0) -> first tab
+- browser_select_tab(urlPattern="qwen") -> tab whose URL contains "qwen"
+- browser_select_tab(titlePattern="Mini Program") -> tab whose title contains "Mini Program"`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                index: {
+                    type: 'number',
+                    description: 'Tab index from browser_list_tabs (0-based)',
+                },
+                urlPattern: {
+                    type: 'string',
+                    description: 'Substring to match against tab URLs',
+                },
+                titlePattern: {
+                    type: 'string',
+                    description: 'Substring to match against tab titles',
+                },
+            },
+        },
+    },
+    {
+        name: 'framework_state_extract',
+        description: 'Extract React/Vue component state from the live page. Useful for debugging frontend applications and finding hidden state.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                framework: {
+                    type: 'string',
+                    description: 'Framework to target. auto = detect automatically.',
+                    enum: ['auto', 'react', 'vue2', 'vue3'],
+                    default: 'auto',
+                },
+                selector: {
+                    type: 'string',
+                    description: 'CSS selector of root element to inspect (default: #root, #app, [data-reactroot], body)',
+                },
+                maxDepth: {
+                    type: 'number',
+                    description: 'Maximum component tree depth to traverse',
+                    default: 5,
+                },
+            },
+        },
+    },
+    {
+        name: 'indexeddb_dump',
+        description: 'Dump all IndexedDB databases and their contents. Useful for analyzing PWA data, stored tokens, or offline application state.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                database: {
+                    type: 'string',
+                    description: 'Specific database name to dump (default: all databases)',
+                },
+                store: {
+                    type: 'string',
+                    description: 'Specific object store to dump (default: all stores)',
+                },
+                maxRecords: {
+                    type: 'number',
+                    description: 'Maximum records per store to return',
+                    default: 100,
+                },
+            },
+        },
+    },
+];

package/dist/src/server/domains/browser/handlers/page-evaluation.d.ts

@@ -0,0 +1,38 @@
+import type { PageController } from '../../../domains/shared/modules.js';
+import type { DetailedDataManager } from '../../../../utils/DetailedDataManager.js';
+interface PageEvaluationHandlersDeps {
+    pageController: PageController;
+    detailedDataManager: DetailedDataManager;
+    getActiveDriver: () => 'chrome' | 'camoufox';
+    getCamoufoxPage: () => Promise<unknown>;
+}
+export declare class PageEvaluationHandlers {
+    private deps;
+    constructor(deps: PageEvaluationHandlersDeps);
+    handlePageEvaluate(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handlePageScreenshot(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    private _screenshotBatch;
+    handlePageInjectScript(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+    handlePageWaitForSelector(args: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    }>;
+}
+export {};

package/dist/src/server/domains/browser/handlers/page-evaluation.js

@@ -0,0 +1,327 @@
+import { resolveScreenshotOutputPath } from '../../../../utils/outputPaths.js';
+function filterFields(value, fields) {
+    if (Array.isArray(value)) {
+        return value.map((item) => filterFields(item, fields));
+    }
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (!fields.has(k)) {
+                out[k] = filterFields(v, fields);
+            }
+        }
+        return out;
+    }
+    return value;
+}
+function stripBase64Values(value) {
+    if (typeof value === 'string') {
+        if (/^data:[a-z+-]+\/[a-z+-]+;base64,/i.test(value)) {
+            return `[base64 ~${Math.round(value.length / 1024)}KB stripped]`;
+        }
+        if (value.length > 500 && /^[A-Za-z0-9+/=\r\n]+$/.test(value.replace(/\s/g, ''))) {
+            return `[base64 ~${value.length}chars stripped]`;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => stripBase64Values(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = stripBase64Values(v);
+        }
+        return out;
+    }
+    return value;
+}
+export class PageEvaluationHandlers {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async handlePageEvaluate(args) {
+        const code = (args.script ?? args.code);
+        const autoSummarize = args.autoSummarize ?? true;
+        const maxSize = args.maxSize ?? 51200;
+        const fieldFilterArg = args.fieldFilter;
+        const doStripBase64 = args.stripBase64 ?? false;
+        const applyPostFilters = (raw) => {
+            let out = raw;
+            if (fieldFilterArg && fieldFilterArg.length > 0) {
+                out = filterFields(out, new Set(fieldFilterArg));
+            }
+            if (doStripBase64) {
+                out = stripBase64Values(out);
+            }
+            return out;
+        };
+        if (this.deps.getActiveDriver() === 'camoufox') {
+            const page = (await this.deps.getCamoufoxPage());
+            const evaluateExpression = new Function(`return (${code})`);
+            const result = await page.evaluate(evaluateExpression);
+            const processedResult = applyPostFilters(autoSummarize ? this.deps.detailedDataManager.smartHandle(result, maxSize) : result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: true, driver: 'camoufox', result: processedResult }, null, 2),
+                    },
+                ],
+            };
+        }
+        const result = await this.deps.pageController.evaluate(code);
+        const processedResult = applyPostFilters(autoSummarize ? this.deps.detailedDataManager.smartHandle(result, maxSize) : result);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        result: processedResult,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async handlePageScreenshot(args) {
+        const requestedPath = args.path;
+        const type = (args.type || 'png');
+        const quality = args.quality;
+        const fullPage = args.fullPage;
+        const clipArg = args.clip;
+        const rawSelector = args.selector;
+        const selectors = [];
+        if (Array.isArray(rawSelector)) {
+            for (const s of rawSelector) {
+                const trimmed = typeof s === 'string' ? s.trim() : '';
+                if (trimmed.length > 0 && trimmed.toLowerCase() !== 'all')
+                    selectors.push(trimmed);
+            }
+        }
+        else if (typeof rawSelector === 'string') {
+            const trimmed = rawSelector.trim();
+            if (trimmed.length > 0 && trimmed.toLowerCase() !== 'all')
+                selectors.push(trimmed);
+        }
+        if (selectors.length > 1) {
+            return this._screenshotBatch(selectors, requestedPath, type, quality);
+        }
+        const selector = selectors[0] ?? '';
+        const { absolutePath, displayPath, pathRewritten } = await resolveScreenshotOutputPath({
+            requestedPath,
+            type,
+            fallbackName: selector ? 'element' : clipArg ? 'region' : 'page',
+            fallbackDir: 'screenshots/manual',
+        });
+        if (this.deps.getActiveDriver() === 'camoufox') {
+            const page = (await this.deps.getCamoufoxPage());
+            let buffer;
+            if (selector) {
+                const element = await page.$(selector);
+                if (!element) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({ success: false, error: `Element not found: ${selector}` }, null, 2),
+                            }],
+                    };
+                }
+                buffer = await element.screenshot({ path: absolutePath, type, quality });
+            }
+            else {
+                buffer = await page.screenshot({ path: absolutePath, type, quality, fullPage: clipArg ? false : fullPage });
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            driver: 'camoufox',
+                            selector: selector || undefined,
+                            clip: clipArg || undefined,
+                            message: `Screenshot taken: ${displayPath}`,
+                            path: displayPath,
+                            pathRewritten,
+                            size: buffer?.length ?? 0,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        let buffer;
+        if (selector) {
+            const page = await this.deps.pageController.getPage();
+            const element = await page.$(selector);
+            if (!element) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: false, error: `Element not found: ${selector}` }, null, 2),
+                        }],
+                };
+            }
+            buffer = (await element.screenshot({ path: absolutePath, type, quality }));
+        }
+        else {
+            buffer = await this.deps.pageController.screenshot({
+                path: absolutePath,
+                type,
+                quality,
+                fullPage: clipArg ? false : fullPage,
+                clip: clipArg,
+            });
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        selector: selector || undefined,
+                        clip: clipArg || undefined,
+                        message: `Screenshot taken: ${displayPath}`,
+                        path: displayPath,
+                        pathRewritten,
+                        size: buffer.length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async _screenshotBatch(selectors, requestedPath, type, quality) {
+        const isCamoufox = this.deps.getActiveDriver() === 'camoufox';
+        const results = [];
+        for (const selector of selectors) {
+            const { absolutePath, displayPath } = await resolveScreenshotOutputPath({
+                requestedPath: requestedPath
+                    ? requestedPath.replace(/(\.\w+)$/, `-${selector.replace(/[^a-zA-Z0-9]/g, '_')}$1`)
+                    : undefined,
+                type,
+                fallbackName: `element-${selector.replace(/[^a-zA-Z0-9]/g, '_')}`,
+                fallbackDir: 'screenshots/manual',
+            });
+            try {
+                let size = 0;
+                if (isCamoufox) {
+                    const page = (await this.deps.getCamoufoxPage());
+                    const element = await page.$(selector);
+                    if (!element) {
+                        results.push({ selector, success: false, error: `Element not found: ${selector}` });
+                        continue;
+                    }
+                    const buf = await element.screenshot({ path: absolutePath, type, quality });
+                    size = buf?.length ?? 0;
+                }
+                else {
+                    const page = await this.deps.pageController.getPage();
+                    const element = await page.$(selector);
+                    if (!element) {
+                        results.push({ selector, success: false, error: `Element not found: ${selector}` });
+                        continue;
+                    }
+                    const buf = (await element.screenshot({ path: absolutePath, type, quality }));
+                    size = buf.length;
+                }
+                results.push({ selector, success: true, path: displayPath, size });
+            }
+            catch (err) {
+                results.push({ selector, success: false, error: String(err) });
+            }
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        mode: 'batch',
+                        total: selectors.length,
+                        succeeded: results.filter((r) => r.success).length,
+                        results,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async handlePageInjectScript(args) {
+        const script = args.script;
+        await this.deps.pageController.injectScript(script);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        message: 'Script injected',
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async handlePageWaitForSelector(args) {
+        const selector = args.selector;
+        const timeout = args.timeout;
+        if (this.deps.getActiveDriver() === 'camoufox') {
+            const page = (await this.deps.getCamoufoxPage());
+            try {
+                await page.waitForSelector(selector, { timeout: timeout || 30000 });
+                const element = await page.evaluate((sel) => {
+                    const el = document.querySelector(sel);
+                    if (!el)
+                        return null;
+                    return {
+                        tagName: el.tagName.toLowerCase(),
+                        id: el.id || undefined,
+                        className: el.className || undefined,
+                        textContent: el.textContent?.trim().substring(0, 100) || undefined,
+                        attributes: Array.from(el.attributes).reduce((acc, attr) => {
+                            acc[attr.name] = attr.value;
+                            return acc;
+                        }, {}),
+                    };
+                }, selector);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                driver: 'camoufox',
+                                element,
+                                message: `Selector appeared: ${selector}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                driver: 'camoufox',
+                                message: `Timeout waiting for selector: ${selector}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        const result = await this.deps.pageController.waitForSelector(selector, timeout);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+}