real-browser-mcp-server 1.1.7 → 1.1.8

package/dist/src/ai/page-analyzer.js

@@ -0,0 +1,264 @@
+"use strict";
+// @ts-nocheck
+class PageAnalyzer {
+    constructor() {
+        this.analysisTypes = ['full', 'interactive', 'forms', 'navigation', 'content', 'media'];
+    }
+    /**
+     * Analyze page structure
+     */
+    async analyze(page, options = {}) {
+        const { analysisType = 'full', includeSelectors = true, includeScreenshot = false, maxDepth = 10 } = options;
+        const analysis = await page.evaluate(({ analysisType, includeSelectors, maxDepth }) => {
+            const result = {
+                url: window.location.href,
+                title: document.title,
+                timestamp: new Date().toISOString(),
+                viewport: {
+                    width: window.innerWidth,
+                    height: window.innerHeight
+                }
+            };
+            // Helper to generate selector
+            const getSelector = (el) => {
+                if (!includeSelectors)
+                    return null;
+                if (el.id)
+                    return `#${el.id}`;
+                if (el.name)
+                    return `[name="${el.name}"]`;
+                if (el.className && typeof el.className === 'string') {
+                    const cls = el.className.split(' ').filter(c => c)[0];
+                    if (cls)
+                        return `${el.tagName.toLowerCase()}.${cls}`;
+                }
+                return el.tagName.toLowerCase();
+            };
+            // Analyze interactive elements
+            if (analysisType === 'full' || analysisType === 'interactive') {
+                result.interactive = {
+                    buttons: [],
+                    links: [],
+                    inputs: []
+                };
+                // Buttons
+                document.querySelectorAll('button, [role="button"], input[type="button"], input[type="submit"]').forEach(el => {
+                    const rect = el.getBoundingClientRect();
+                    if (rect.width > 0 && rect.height > 0) {
+                        result.interactive.buttons.push({
+                            selector: getSelector(el),
+                            text: el.textContent?.trim().substring(0, 50),
+                            type: el.type || 'button',
+                            disabled: el.disabled,
+                            visible: true
+                        });
+                    }
+                });
+                // Links
+                document.querySelectorAll('a[href]').forEach(el => {
+                    const rect = el.getBoundingClientRect();
+                    if (rect.width > 0 && rect.height > 0) {
+                        result.interactive.links.push({
+                            selector: getSelector(el),
+                            text: el.textContent?.trim().substring(0, 50),
+                            href: el.href,
+                            target: el.target || '_self',
+                            visible: true
+                        });
+                    }
+                });
+                // Inputs
+                document.querySelectorAll('input, textarea, select').forEach(el => {
+                    const rect = el.getBoundingClientRect();
+                    if (rect.width > 0 && rect.height > 0) {
+                        result.interactive.inputs.push({
+                            selector: getSelector(el),
+                            type: el.type || 'text',
+                            name: el.name,
+                            placeholder: el.placeholder,
+                            required: el.required,
+                            disabled: el.disabled,
+                            value: el.type === 'password' ? '***' : el.value?.substring(0, 20),
+                            visible: true
+                        });
+                    }
+                });
+            }
+            // Analyze forms
+            if (analysisType === 'full' || analysisType === 'forms') {
+                result.forms = [];
+                document.querySelectorAll('form').forEach(form => {
+                    const formData = {
+                        selector: getSelector(form),
+                        action: form.action,
+                        method: form.method,
+                        fields: []
+                    };
+                    form.querySelectorAll('input, textarea, select').forEach(field => {
+                        formData.fields.push({
+                            selector: getSelector(field),
+                            type: field.type || field.tagName.toLowerCase(),
+                            name: field.name,
+                            label: document.querySelector(`label[for="${field.id}"]`)?.textContent?.trim(),
+                            required: field.required,
+                            placeholder: field.placeholder
+                        });
+                    });
+                    // Find submit button
+                    const submitBtn = form.querySelector('button[type="submit"], input[type="submit"], button:not([type])');
+                    if (submitBtn) {
+                        formData.submitButton = {
+                            selector: getSelector(submitBtn),
+                            text: submitBtn.textContent?.trim() || submitBtn.value
+                        };
+                    }
+                    result.forms.push(formData);
+                });
+            }
+            // Analyze navigation
+            if (analysisType === 'full' || analysisType === 'navigation') {
+                result.navigation = {
+                    menus: [],
+                    breadcrumbs: null,
+                    pagination: null
+                };
+                // Find menus
+                document.querySelectorAll('nav, [role="navigation"], .nav, .menu, header ul').forEach(nav => {
+                    const links = [];
+                    nav.querySelectorAll('a').forEach(a => {
+                        links.push({
+                            text: a.textContent?.trim().substring(0, 30),
+                            href: a.href,
+                            selector: getSelector(a)
+                        });
+                    });
+                    if (links.length > 0) {
+                        result.navigation.menus.push({
+                            selector: getSelector(nav),
+                            type: nav.tagName.toLowerCase(),
+                            links: links.slice(0, 20)
+                        });
+                    }
+                });
+                // Find breadcrumbs
+                const breadcrumb = document.querySelector('[aria-label*="breadcrumb"], .breadcrumb, .breadcrumbs');
+                if (breadcrumb) {
+                    result.navigation.breadcrumbs = {
+                        selector: getSelector(breadcrumb),
+                        items: Array.from(breadcrumb.querySelectorAll('a, span')).map(el => el.textContent?.trim()).filter(Boolean)
+                    };
+                }
+                // Find pagination
+                const pagination = document.querySelector('.pagination, [aria-label*="pagination"], nav[role="navigation"] a[href*="page"]');
+                if (pagination) {
+                    result.navigation.pagination = {
+                        selector: getSelector(pagination.closest('nav, .pagination, div')),
+                        found: true
+                    };
+                }
+            }
+            // Analyze main content
+            if (analysisType === 'full' || analysisType === 'content') {
+                result.content = {
+                    headings: [],
+                    paragraphs: 0,
+                    mainContent: null
+                };
+                // Headings
+                document.querySelectorAll('h1, h2, h3').forEach(h => {
+                    result.content.headings.push({
+                        level: parseInt(h.tagName[1]),
+                        text: h.textContent?.trim().substring(0, 100),
+                        selector: getSelector(h)
+                    });
+                });
+                // Count paragraphs
+                result.content.paragraphs = document.querySelectorAll('p').length;
+                // Find main content area
+                const main = document.querySelector('main, [role="main"], article, .content, #content');
+                if (main) {
+                    result.content.mainContent = {
+                        selector: getSelector(main),
+                        textLength: main.textContent?.length || 0
+                    };
+                }
+            }
+            // Analyze media
+            if (analysisType === 'full' || analysisType === 'media') {
+                result.media = {
+                    images: [],
+                    videos: [],
+                    iframes: []
+                };
+                // Images
+                document.querySelectorAll('img').forEach(img => {
+                    const rect = img.getBoundingClientRect();
+                    if (rect.width > 50 && rect.height > 50) {
+                        result.media.images.push({
+                            selector: getSelector(img),
+                            src: img.src?.substring(0, 100),
+                            alt: img.alt,
+                            width: Math.round(rect.width),
+                            height: Math.round(rect.height)
+                        });
+                    }
+                });
+                // Videos
+                document.querySelectorAll('video').forEach(video => {
+                    result.media.videos.push({
+                        selector: getSelector(video),
+                        src: video.src || video.querySelector('source')?.src,
+                        duration: video.duration,
+                        controls: video.controls
+                    });
+                });
+                // Iframes (potential embedded content)
+                document.querySelectorAll('iframe').forEach(iframe => {
+                    result.media.iframes.push({
+                        selector: getSelector(iframe),
+                        src: iframe.src?.substring(0, 100),
+                        title: iframe.title
+                    });
+                });
+            }
+            // Summary stats
+            result.summary = {
+                totalButtons: result.interactive?.buttons?.length || 0,
+                totalLinks: result.interactive?.links?.length || 0,
+                totalInputs: result.interactive?.inputs?.length || 0,
+                totalForms: result.forms?.length || 0,
+                totalImages: result.media?.images?.length || 0,
+                hasNavigation: (result.navigation?.menus?.length || 0) > 0,
+                isLoginPage: !!(result.interactive?.inputs?.find(i => i.type === 'password')),
+                isSearchPage: !!(result.interactive?.inputs?.find(i => i.type === 'search' || i.name?.includes('search') || i.placeholder?.toLowerCase().includes('search')))
+            };
+            return result;
+        }, { analysisType, includeSelectors, maxDepth });
+        // Add screenshot if requested
+        if (includeScreenshot) {
+            // Playwright/Patchright returns a Buffer; convert to base64 ourselves
+            const buf = await page.screenshot({ type: 'jpeg', quality: 50 });
+            analysis.screenshot = Buffer.from(buf).toString('base64');
+        }
+        return analysis;
+    }
+    /**
+     * Get quick summary of page
+     */
+    async quickSummary(page) {
+        return await page.evaluate(() => {
+            return {
+                url: window.location.href,
+                title: document.title,
+                buttons: document.querySelectorAll('button, [role="button"]').length,
+                links: document.querySelectorAll('a[href]').length,
+                inputs: document.querySelectorAll('input, textarea').length,
+                forms: document.querySelectorAll('form').length,
+                images: document.querySelectorAll('img').length,
+                hasLogin: !!document.querySelector('input[type="password"]'),
+                hasSearch: !!document.querySelector('input[type="search"], [name*="search"], [placeholder*="earch"]')
+            };
+        });
+    }
+}
+module.exports = PageAnalyzer;

package/dist/src/ai/selector-healer.js

@@ -0,0 +1,215 @@
+"use strict";
+// @ts-nocheck
+/**
+ * AI Selector Healer - Auto-fix broken CSS selectors
+ *
+ * When a selector stops working (page updated, dynamic content, etc.),
+ * this module tries to find alternative selectors that match the same element.
+ */
+class SelectorHealer {
+    constructor() {
+        this.healingStrategies = [
+            'byId',
+            'byName',
+            'byAriaLabel',
+            'byText',
+            'byClasses',
+            'byAttributes',
+            'byStructure',
+            'byPosition'
+        ];
+    }
+    /**
+     * Heal a broken selector by finding alternatives
+     */
+    async heal(page, brokenSelector, options = {}) {
+        const { lastKnownText = null, lastKnownAttributes = {}, elementType = null, maxAlternatives = 5 } = options;
+        const context = {
+            brokenSelector,
+            lastKnownText,
+            lastKnownAttributes,
+            elementType
+        };
+        // Try to extract info from broken selector
+        const selectorInfo = this.parseSelector(brokenSelector);
+        // Find alternatives using multiple strategies
+        const alternatives = await page.evaluate(({ context, selectorInfo }) => {
+            const results = [];
+            // Strategy 1: Find by similar ID
+            if (selectorInfo.id) {
+                const elements = document.querySelectorAll(`[id*="${selectorInfo.id}"]`);
+                for (const el of elements) {
+                    results.push({
+                        selector: `#${el.id}`,
+                        confidence: 0.9,
+                        strategy: 'byId',
+                        reason: 'Similar ID found'
+                    });
+                }
+            }
+            // Strategy 2: Find by name attribute
+            if (selectorInfo.name) {
+                const elements = document.querySelectorAll(`[name*="${selectorInfo.name}"]`);
+                for (const el of elements) {
+                    results.push({
+                        selector: `[name="${el.name}"]`,
+                        confidence: 0.85,
+                        strategy: 'byName',
+                        reason: 'Similar name attribute found'
+                    });
+                }
+            }
+            // Strategy 3: Find by last known text
+            if (context.lastKnownText) {
+                const allElements = document.querySelectorAll('button, a, input, label, span, div, [role]');
+                for (const el of allElements) {
+                    const text = el.textContent?.trim();
+                    if (text && text.toLowerCase().includes(context.lastKnownText.toLowerCase())) {
+                        let selector = '';
+                        if (el.id) {
+                            selector = `#${el.id}`;
+                        }
+                        else if (el.className) {
+                            selector = `${el.tagName.toLowerCase()}.${el.className.split(' ')[0]}`;
+                        }
+                        else {
+                            selector = `${el.tagName.toLowerCase()}`;
+                        }
+                        results.push({
+                            selector,
+                            confidence: 0.8,
+                            strategy: 'byText',
+                            reason: `Contains text: "${text.substring(0, 30)}"`
+                        });
+                    }
+                }
+            }
+            // Strategy 4: Find by similar classes
+            if (selectorInfo.classes.length > 0) {
+                for (const cls of selectorInfo.classes) {
+                    const elements = document.querySelectorAll(`[class*="${cls}"]`);
+                    for (const el of elements) {
+                        const rect = el.getBoundingClientRect();
+                        if (rect.width > 0 && rect.height > 0) {
+                            results.push({
+                                selector: `.${cls}`,
+                                confidence: 0.7,
+                                strategy: 'byClasses',
+                                reason: `Similar class: ${cls}`
+                            });
+                        }
+                    }
+                }
+            }
+            // Strategy 5: Find by tag and type
+            if (selectorInfo.tag) {
+                let selector = selectorInfo.tag;
+                if (selectorInfo.type) {
+                    selector += `[type="${selectorInfo.type}"]`;
+                }
+                const elements = document.querySelectorAll(selector);
+                for (const el of elements) {
+                    const rect = el.getBoundingClientRect();
+                    if (rect.width > 0 && rect.height > 0) {
+                        let uniqueSelector = selector;
+                        if (el.placeholder) {
+                            uniqueSelector += `[placeholder="${el.placeholder}"]`;
+                        }
+                        else if (el.value) {
+                            uniqueSelector += `[value="${el.value}"]`;
+                        }
+                        results.push({
+                            selector: uniqueSelector,
+                            confidence: 0.6,
+                            strategy: 'byAttributes',
+                            reason: `Similar element structure`
+                        });
+                    }
+                }
+            }
+            // Strategy 6: Find by aria-label
+            if (context.lastKnownAttributes?.['aria-label']) {
+                const label = context.lastKnownAttributes['aria-label'];
+                const elements = document.querySelectorAll(`[aria-label*="${label}"]`);
+                for (const el of elements) {
+                    results.push({
+                        selector: `[aria-label="${el.getAttribute('aria-label')}"]`,
+                        confidence: 0.85,
+                        strategy: 'byAriaLabel',
+                        reason: 'Similar aria-label found'
+                    });
+                }
+            }
+            // Deduplicate
+            const seen = new Set();
+            return results.filter(r => {
+                if (seen.has(r.selector))
+                    return false;
+                seen.add(r.selector);
+                return true;
+            });
+        }, { context, selectorInfo });
+        // Sort by confidence and return top alternatives
+        return alternatives
+            .sort((a, b) => b.confidence - a.confidence)
+            .slice(0, maxAlternatives);
+    }
+    /**
+     * Parse a CSS selector to extract components
+     */
+    parseSelector(selector) {
+        const info = {
+            tag: null,
+            id: null,
+            classes: [],
+            name: null,
+            type: null,
+            attributes: {}
+        };
+        // Extract ID
+        const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
+        if (idMatch)
+            info.id = idMatch[1];
+        // Extract classes
+        const classMatches = selector.matchAll(/\.([a-zA-Z0-9_-]+)/g);
+        for (const match of classMatches) {
+            info.classes.push(match[1]);
+        }
+        // Extract tag
+        const tagMatch = selector.match(/^([a-zA-Z]+)/);
+        if (tagMatch)
+            info.tag = tagMatch[1];
+        // Extract attributes
+        const attrMatches = selector.matchAll(/\[([a-zA-Z-]+)(?:=["']?([^"'\]]+)["']?)?\]/g);
+        for (const match of attrMatches) {
+            const key = match[1];
+            const value = match[2] || true;
+            info.attributes[key] = value;
+            if (key === 'name')
+                info.name = value;
+            if (key === 'type')
+                info.type = value;
+        }
+        return info;
+    }
+    /**
+     * Test if a selector works
+     */
+    async testSelector(page, selector) {
+        try {
+            const element = await page.$(selector);
+            if (!element)
+                return { valid: false };
+            const info = await element.evaluate(el => ({
+                visible: el.offsetWidth > 0 && el.offsetHeight > 0,
+                tag: el.tagName.toLowerCase(),
+                text: el.textContent?.substring(0, 50)
+            }));
+            return { valid: true, ...info };
+        }
+        catch {
+            return { valid: false };
+        }
+    }
+}
+module.exports = SelectorHealer;

package/dist/src/index.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+"use strict";
+// @ts-nocheck
+/**
+ * Real Browser MCP Server
+ *
+ * Usage:
+ *   node src/index.js             - Start MCP Server (default)
+ *   node src/index.js --help      - Show help
+ *   node src/index.js --list      - List all available tools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const { TOOLS, TOOL_DISPLAY, CATEGORIES } = require('./shared/tools');
+// ANSI colors for terminal
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+};
+/**
+ * Display help message
+ */
+function showHelp() {
+    console.log(`
+${colors.bright}${colors.cyan}🦁 Real Browser MCP Server${colors.reset}
+
+${colors.bright}USAGE:${colors.reset}
+  node src/index.js [options]
+
+${colors.bright}OPTIONS:${colors.reset}
+  ${colors.yellow}--help, -h${colors.reset}    Show this help message
+  ${colors.yellow}--verbose, -v${colors.reset} Show detailed tool information
+  ${colors.yellow}--list${colors.reset}        List all available tools
+
+${colors.bright}EXAMPLES:${colors.reset}
+  node src/index.js              # Start MCP server
+  node src/index.js --list       # List all tools
+
+${colors.bright}NPM SCRIPTS:${colors.reset}
+  npm run dev                    # Start MCP server
+  npm run mcp                    # Start MCP server only
+
+${colors.bright}ARCHITECTURE:${colors.reset}
+  ${colors.cyan}MCP Server${colors.reset} → STDIO transport → AI Agents (Claude, Cursor, Copilot)
+
+${colors.bright}TOOL CATEGORIES (${TOOLS.length} tools):${colors.reset}
+${Object.entries(CATEGORIES).map(([key, cat]) => {
+        const count = TOOLS.filter(t => t.category === key).length;
+        return `  ${cat.emoji} ${colors.yellow}${cat.name.padEnd(15)}${colors.reset} ${colors.dim}(${count} tools)${colors.reset}`;
+    }).join('\n')}
+  `);
+}
+/**
+ * List all available tools
+ */
+function listTools() {
+    console.log(`\n${colors.bright}${colors.cyan}🦁 Available Tools (${TOOLS.length}):${colors.reset}\n`);
+    for (const [key, cat] of Object.entries(CATEGORIES)) {
+        const tools = TOOLS.filter(t => t.category === key);
+        if (tools.length === 0)
+            continue;
+        console.log(`${colors.bright}${cat.emoji} ${cat.name}${colors.reset} ${colors.dim}(${tools.length})${colors.reset}`);
+        console.log(`${colors.dim}${'─'.repeat(50)}${colors.reset}`);
+        for (const tool of tools) {
+            console.log(`  ${tool.emoji} ${colors.yellow}${tool.name.padEnd(25)}${colors.reset} ${colors.dim}${tool.description.substring(0, 40)}${colors.reset}`);
+        }
+        console.log('');
+    }
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const args = process.argv.slice(2);
+    // Parse arguments
+    const hasHelp = args.includes('--help') || args.includes('-h');
+    const hasList = args.includes('--list');
+    if (hasHelp) {
+        showHelp();
+        process.exit(0);
+    }
+    if (hasList) {
+        listTools();
+        process.exit(0);
+    }
+    console.error('');
+    console.error(`${colors.bright}${colors.cyan}╔════════════════════════════════════════════════════════════╗${colors.reset}`);
+    console.error(`${colors.bright}${colors.cyan}║${colors.reset}  ${colors.bright}${colors.magenta}🦁 Real Browser MCP Server${colors.reset}                                ${colors.cyan}║${colors.reset}`);
+    console.error(`${colors.bright}${colors.cyan}║${colors.reset}  ${colors.dim}MCP (AI Agents) Server running on STDIO${colors.reset}                  ${colors.cyan}║${colors.reset}`);
+    console.error(`${colors.bright}${colors.cyan}╚════════════════════════════════════════════════════════════╝${colors.reset}`);
+    console.error('');
+    console.error(`${colors.bright}${colors.blue}🚀 Starting MCP Server...${colors.reset}`);
+    // Import and run MCP server
+    require('./mcp/index');
+}
+// Export for programmatic use
+module.exports = {
+    TOOLS,
+    TOOL_DISPLAY,
+    CATEGORIES,
+    startMCP: () => require('./mcp/index'),
+    startBoth: () => require('./mcp/index'),
+};
+// Run if called directly
+if (require.main === module) {
+    main().catch(error => {
+        console.error(`${colors.red}❌ Fatal error:${colors.reset}`, error.message);
+        process.exit(1);
+    });
+}