abu-browser-bridge 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Abu Browser Bridge — MCP Server + WebSocket Server
+ *
+ * This process acts as a bridge between Abu (via MCP stdio transport)
+ * and the Chrome Extension (via WebSocket).
+ *
+ * Usage:
+ *   npx abu-browser-bridge [--port 9876]
+ *
+ * Abu connects to this as an MCP server (stdio).
+ * Chrome Extension connects via WebSocket (ws://127.0.0.1:9876).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Abu Browser Bridge — MCP Server + WebSocket Server
+ *
+ * This process acts as a bridge between Abu (via MCP stdio transport)
+ * and the Chrome Extension (via WebSocket).
+ *
+ * Usage:
+ *   npx abu-browser-bridge [--port 9876]
+ *
+ * Abu connects to this as an MCP server (stdio).
+ * Chrome Extension connects via WebSocket (ws://127.0.0.1:9876).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { execSync } from 'child_process';
+import { startWSServer, stopWSServer } from './wsServer.js';
+import { registerTools } from './tools.js';
+const DEFAULT_WS_PORT = 9876;
+const PORT_RANGE = 5; // ports 9876-9880
+/**
+ * Kill any stale abu-browser-bridge processes listening on our port range.
+ * This ensures the Extension always connects to the newest bridge.
+ * Cross-platform: uses lsof on macOS/Linux, netstat+taskkill on Windows.
+ */
+function killStaleBridges(basePort) {
+    const myPid = process.pid;
+    const isWindows = process.platform === 'win32';
+    try {
+        let pids;
+        if (isWindows) {
+            // Windows: use netstat to find PIDs on each port
+            pids = new Set();
+            const output = execSync('netstat -ano -p TCP', { encoding: 'utf-8', timeout: 5000 });
+            for (let p = basePort; p < basePort + PORT_RANGE; p++) {
+                // Match lines like "  TCP    127.0.0.1:9876    0.0.0.0:0    LISTENING    12345"
+                const regex = new RegExp(`127\\.0\\.0\\.1:${p}\\s+.*LISTENING\\s+(\\d+)`, 'g');
+                let match;
+                while ((match = regex.exec(output)) !== null) {
+                    const pid = parseInt(match[1], 10);
+                    if (pid && pid !== myPid)
+                        pids.add(pid);
+                }
+            }
+            for (const pid of pids) {
+                try {
+                    execSync(`taskkill /PID ${pid} /F`, { timeout: 3000 });
+                    console.error(`[abu-bridge] Killed stale process ${pid}`);
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+        }
+        else {
+            // macOS/Linux: single lsof call with multiple -i flags
+            const portFlags = Array.from({ length: PORT_RANGE }, (_, i) => `-ti:${basePort + i}`);
+            const output = execSync(`lsof ${portFlags.join(' ')}`, { encoding: 'utf-8', timeout: 5000 }).trim();
+            if (!output)
+                return;
+            pids = new Set(output.split('\n').map(l => parseInt(l.trim(), 10)).filter(pid => pid && pid !== myPid));
+            for (const pid of pids) {
+                try {
+                    process.kill(pid, 'SIGTERM');
+                    console.error(`[abu-bridge] Killed stale process ${pid}`);
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+        }
+    }
+    catch {
+        // Command not available or no processes found — that's fine
+    }
+}
+async function main() {
+    // Parse CLI args
+    const args = process.argv.slice(2);
+    let wsPort = DEFAULT_WS_PORT;
+    const portIndex = args.indexOf('--port');
+    if (portIndex !== -1 && args[portIndex + 1]) {
+        wsPort = parseInt(args[portIndex + 1], 10);
+        if (isNaN(wsPort) || wsPort < 1 || wsPort > 65535) {
+            console.error(`Invalid port: ${args[portIndex + 1]}`);
+            process.exit(1);
+        }
+    }
+    // 0. Kill any stale bridge processes so the Extension connects to us
+    killStaleBridges(wsPort);
+    // 1. Start WebSocket server (for Chrome Extension)
+    // startWSServer already tries ports 9876-9880 with fallback if a port is still in TIME_WAIT
+    try {
+        const actualPort = await startWSServer(wsPort);
+        if (actualPort !== wsPort) {
+            console.error(`[abu-bridge] Note: using port ${actualPort} instead of ${wsPort}`);
+        }
+    }
+    catch (err) {
+        console.error(`Failed to start WS server:`, err);
+        process.exit(1);
+    }
+    // 2. Create MCP server (for Abu)
+    const mcpServer = new McpServer({
+        name: 'abu-browser-bridge',
+        version: '0.1.0',
+    });
+    // 3. Register browser tools
+    registerTools(mcpServer);
+    // 4. Connect MCP server to stdio transport
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+    console.error('[abu-bridge] MCP server connected via stdio');
+    console.error('[abu-bridge] Ready — waiting for Chrome Extension connection...');
+    // Graceful shutdown
+    const cleanup = () => {
+        console.error('[abu-bridge] Shutting down...');
+        stopWSServer();
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tool definitions for browser automation.
+ * Each tool sends a request to the Chrome Extension via WebSocket.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTools(server: McpServer): void;

package/dist/tools.js

@@ -0,0 +1,182 @@
+/**
+ * MCP Tool definitions for browser automation.
+ * Each tool sends a request to the Chrome Extension via WebSocket.
+ */
+import { z } from 'zod';
+import { sendToExtension, isExtensionConnected } from './wsServer.js';
+// --- Element Locator Schema (reusable) ---
+const LocatorDescription = `How to find the element. Supports multiple strategies:
+- { "text": "按钮文字" } — find by visible text content (most common)
+- { "css": "#id" } or { "css": ".class" } — find by CSS selector
+- { "role": "button", "name": "Submit" } — find by ARIA role
+- { "testId": "submit-btn" } — find by data-testid attribute
+- { "ref": "e3" } — use reference ID from a previous snapshot
+- { "xpath": "//div[@class='x']" } — find by XPath (fallback)`;
+// --- Helper ---
+function ensureConnected() {
+    if (!isExtensionConnected()) {
+        throw new Error('Chrome Extension is not connected. Please install the Abu Browser Extension and ensure it is enabled.');
+    }
+}
+function formatResult(response) {
+    if (!response.success) {
+        return `Error: ${response.error ?? 'Unknown error'}`;
+    }
+    if (typeof response.data === 'string') {
+        return response.data;
+    }
+    return JSON.stringify(response.data, null, 2);
+}
+// --- Register all tools ---
+export function registerTools(server) {
+    // 1. browser_get_tabs
+    server.tool('get_tabs', 'Get a list of all open browser tabs with their URLs and titles. Use this first to find the target tab.', async () => {
+        ensureConnected();
+        const res = await sendToExtension('get_tabs');
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 2. browser_snapshot
+    server.tool('snapshot', `Get a structured snapshot of all interactive elements on the page (buttons, inputs, links, selects, etc.). Returns each element with a short reference ID (e.g., "e1") that can be used in subsequent actions. This is the primary way to understand what's on a page before taking action.`, {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        selector: z.string().optional().describe('Optional CSS selector to scope the snapshot to a specific area of the page'),
+    }, async ({ tabId, selector }) => {
+        ensureConnected();
+        const res = await sendToExtension('snapshot', { tabId, selector });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 3. browser_click
+    server.tool('click', 'Click an element on the page. Returns the result of the click action.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        locator: z.string().describe(`JSON string of element locator. ${LocatorDescription}`),
+    }, async ({ tabId, locator }) => {
+        ensureConnected();
+        const parsed = JSON.parse(locator);
+        const res = await sendToExtension('click', { tabId, locator: parsed });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 4. browser_fill
+    server.tool('fill', 'Fill in a text input, textarea, or other editable field. Clears existing content and types the new value, triggering proper input/change events for framework compatibility (React, Vue, etc.).', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        locator: z.string().describe(`JSON string of element locator. ${LocatorDescription}`),
+        value: z.string().describe('The text value to fill into the field'),
+    }, async ({ tabId, locator, value }) => {
+        ensureConnected();
+        const parsed = JSON.parse(locator);
+        const res = await sendToExtension('fill', { tabId, locator: parsed, value });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 5. browser_select
+    server.tool('select', 'Select an option from a <select> dropdown element.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        locator: z.string().describe(`JSON string of element locator. ${LocatorDescription}`),
+        value: z.string().describe('The option value or visible text to select'),
+    }, async ({ tabId, locator, value }) => {
+        ensureConnected();
+        const parsed = JSON.parse(locator);
+        const res = await sendToExtension('select', { tabId, locator: parsed, value });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 6. browser_wait_for
+    server.tool('wait_for', `Wait for a condition to be met on the page. Useful for waiting for elements to appear after a click, waiting for loading to complete, or waiting for page navigation. Returns when the condition is met or times out.`, {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        condition: z.string().describe(`JSON string of wait condition. Options:
+- { "type": "appear", "locator": { "text": "成功" } } — wait for element to appear
+- { "type": "disappear", "locator": { "css": ".loading" } } — wait for element to disappear
+- { "type": "enabled", "locator": { "text": "提交" } } — wait for element to become clickable
+- { "type": "textContains", "locator": { "css": "#status" }, "text": "完成" } — wait for text content
+- { "type": "urlContains", "pattern": "/success" } — wait for URL change`),
+        timeout: z.number().optional().default(30000).describe('Maximum wait time in ms (default: 30000)'),
+    }, async ({ tabId, condition, timeout }) => {
+        ensureConnected();
+        const parsed = JSON.parse(condition);
+        const res = await sendToExtension('wait_for', { tabId, condition: parsed, timeout }, timeout + 5000);
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 7. browser_extract_text
+    server.tool('extract_text', 'Extract text content from the page or a specific element. Useful for reading content, checking values, or verifying results.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        selector: z.string().optional().describe('CSS selector to extract text from. If omitted, extracts the full page text (may be large).'),
+    }, async ({ tabId, selector }) => {
+        ensureConnected();
+        const res = await sendToExtension('extract_text', { tabId, selector });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 8. browser_extract_table
+    server.tool('extract_table', 'Extract structured data from an HTML table on the page. Returns headers and rows as arrays.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        selector: z.string().optional().describe('CSS selector for the target table. If omitted, extracts the largest table on the page.'),
+    }, async ({ tabId, selector }) => {
+        ensureConnected();
+        const res = await sendToExtension('extract_table', { tabId, selector });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 9. browser_scroll
+    server.tool('scroll', 'Scroll the page or a specific element.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        direction: z.enum(['up', 'down', 'left', 'right']).describe('Scroll direction'),
+        amount: z.number().optional().default(500).describe('Scroll amount in pixels (default: 500)'),
+        selector: z.string().optional().describe('CSS selector for the scrollable element. If omitted, scrolls the whole page.'),
+    }, async ({ tabId, direction, amount, selector }) => {
+        ensureConnected();
+        const res = await sendToExtension('scroll', { tabId, direction, amount, selector });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 10. browser_navigate
+    server.tool('navigate', 'Navigate a tab to a specific URL, or go back/forward in history.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        url: z.string().optional().describe('URL to navigate to. Omit for back/forward.'),
+        action: z.enum(['goto', 'back', 'forward', 'reload']).optional().default('goto').describe('Navigation action (default: goto)'),
+    }, async ({ tabId, url, action }) => {
+        ensureConnected();
+        const res = await sendToExtension('navigate', { tabId, url, action });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 11. browser_keyboard
+    server.tool('keyboard', 'Send keyboard events to the page. Supports key combinations.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        key: z.string().describe('Key to press (e.g., "Enter", "Tab", "Escape", "a", "ArrowDown")'),
+        modifiers: z.array(z.enum(['ctrl', 'shift', 'alt', 'meta'])).optional().describe('Modifier keys to hold'),
+    }, async ({ tabId, key, modifiers }) => {
+        ensureConnected();
+        const res = await sendToExtension('keyboard', { tabId, key, modifiers });
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 12. browser_execute_js
+    server.tool('execute_js', 'Execute arbitrary JavaScript code in the context of the page. Use this as a fallback when other tools cannot achieve the desired result. Returns the result of the expression.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+        code: z.string().describe('JavaScript code to execute. The last expression value is returned.'),
+    }, async ({ tabId, code }) => {
+        ensureConnected();
+        const res = await sendToExtension('execute_js', { tabId, code }, 60_000);
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 13. browser_screenshot
+    server.tool('screenshot', 'Take a screenshot of the visible area of a tab. Returns a base64-encoded PNG image. Useful for visual confirmation of actions.', {
+        tabId: z.number().describe('Tab ID from get_tabs'),
+    }, async ({ tabId }) => {
+        ensureConnected();
+        const res = await sendToExtension('screenshot', { tabId });
+        if (res.success && typeof res.data === 'string') {
+            return {
+                content: [{
+                        type: 'image',
+                        data: res.data.replace(/^data:image\/png;base64,/, ''),
+                        mimeType: 'image/png',
+                    }]
+            };
+        }
+        return { content: [{ type: 'text', text: formatResult(res) }] };
+    });
+    // 14. browser_connection_status
+    server.tool('connection_status', 'Check whether the Chrome Extension is connected to this bridge. Use this to verify the extension is ready before performing browser actions.', async () => {
+        const connected = isExtensionConnected();
+        return {
+            content: [{
+                    type: 'text',
+                    text: connected
+                        ? 'Chrome Extension is connected and ready.'
+                        : 'Chrome Extension is NOT connected. Please ensure the Abu Browser Extension is installed and enabled in Chrome.'
+                }]
+        };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared types for Abu Browser Bridge communication protocol.
+ *
+ * Single source of truth — imported by both:
+ *   - abu-browser-bridge (MCP server)
+ *   - abu-chrome-extension (Chrome Extension)
+ */
+export interface BridgeRequest {
+    id: string;
+    action: string;
+    payload: Record<string, unknown>;
+}
+export interface BridgeResponse {
+    id: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+export interface ElementLocator {
+    css?: string;
+    text?: string;
+    tag?: string;
+    role?: string;
+    name?: string;
+    xpath?: string;
+    testId?: string;
+    ref?: string;
+}
+export interface ElementInfo {
+    ref: string;
+    tag: string;
+    type?: string;
+    text?: string;
+    placeholder?: string;
+    value?: string;
+    href?: string;
+    role?: string;
+    ariaLabel?: string;
+    enabled: boolean;
+    visible: boolean;
+    checked?: boolean;
+    selected?: boolean;
+    options?: {
+        value: string;
+        text: string;
+    }[];
+}
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    elements: ElementInfo[];
+}
+export type WaitCondition = {
+    type: 'appear';
+    locator: ElementLocator;
+    timeout?: number;
+} | {
+    type: 'disappear';
+    locator: ElementLocator;
+    timeout?: number;
+} | {
+    type: 'enabled';
+    locator: ElementLocator;
+    timeout?: number;
+} | {
+    type: 'textContains';
+    locator: ElementLocator;
+    text: string;
+    timeout?: number;
+} | {
+    type: 'urlContains';
+    pattern: string;
+    timeout?: number;
+};
+export interface TabInfo {
+    tabId: number;
+    url: string;
+    title: string;
+    active: boolean;
+    focused: boolean;
+    windowId: number;
+    windowFocused: boolean;
+}
+export interface ClickResult {
+    success: boolean;
+    message: string;
+    elementText?: string;
+}
+export interface FillResult {
+    success: boolean;
+    message: string;
+    previousValue?: string;
+}
+export interface WaitResult {
+    success: boolean;
+    message: string;
+    timedOut: boolean;
+    elapsed: number;
+}
+export interface ExtractTableResult {
+    headers: string[];
+    rows: string[][];
+    rowCount: number;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for Abu Browser Bridge communication protocol.
+ *
+ * Single source of truth — imported by both:
+ *   - abu-browser-bridge (MCP server)
+ *   - abu-chrome-extension (Chrome Extension)
+ */
+export {};

package/dist/wsServer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WebSocket server that accepts connections from the Chrome Extension.
+ * Routes requests from MCP tools to the extension and returns responses.
+ */
+import type { BridgeResponse } from './types.js';
+/**
+ * Start the WebSocket server. If the default port is occupied (by a stale bridge),
+ * try a few alternative ports. The Extension will discover the port via a well-known range.
+ */
+export declare function startWSServer(port?: number): Promise<number>;
+/**
+ * Send a request to the Chrome Extension and wait for response.
+ */
+export declare function sendToExtension(action: string, payload?: Record<string, unknown>, timeoutMs?: number): Promise<BridgeResponse>;
+/**
+ * Check if the Chrome Extension is currently connected.
+ */
+export declare function isExtensionConnected(): boolean;
+/**
+ * Get the port the WS server is actually listening on.
+ */
+export declare function getActivePort(): number | null;
+export declare function stopWSServer(): void;

package/dist/wsServer.js

@@ -0,0 +1,184 @@
+/**
+ * WebSocket server that accepts connections from the Chrome Extension.
+ * Routes requests from MCP tools to the extension and returns responses.
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import { createConnection } from 'net';
+const DEFAULT_PORT = 9876;
+const HEARTBEAT_INTERVAL = 30_000;
+let wss = null;
+let extensionSocket = null;
+let heartbeatTimer = null;
+const pendingRequests = new Map();
+let requestCounter = 0;
+let activePort = null;
+function generateId() {
+    return `req_${Date.now().toString(36)}_${(++requestCounter).toString(36)}`;
+}
+/**
+ * Check if a port is in use by trying to connect to it.
+ * Cross-platform — works on macOS, Windows, Linux.
+ */
+function isPortInUse(port, host) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host });
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.setTimeout(1000, () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+/**
+ * Start the WebSocket server. If the default port is occupied (by a stale bridge),
+ * try a few alternative ports. The Extension will discover the port via a well-known range.
+ */
+export async function startWSServer(port = DEFAULT_PORT) {
+    const MAX_RETRIES = 5;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        const tryPort = port + attempt;
+        const inUse = await isPortInUse(tryPort, '127.0.0.1');
+        if (inUse) {
+            console.error(`[abu-bridge] Port ${tryPort} is in use, trying ${tryPort + 1}...`);
+            continue;
+        }
+        try {
+            await listenOnPort(tryPort);
+            activePort = tryPort;
+            return tryPort;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // EADDRINUSE can still happen in a race condition
+            if (msg.includes('EADDRINUSE') && attempt < MAX_RETRIES - 1) {
+                console.error(`[abu-bridge] Port ${tryPort} race condition, trying next...`);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error(`All ports ${port}-${port + MAX_RETRIES - 1} are in use`);
+}
+function listenOnPort(port) {
+    return new Promise((resolve, reject) => {
+        wss = new WebSocketServer({ port, host: '127.0.0.1' });
+        wss.on('listening', () => {
+            console.error(`[abu-bridge] WS server listening on ws://127.0.0.1:${port}`);
+            startHeartbeat();
+            resolve();
+        });
+        wss.on('error', (err) => {
+            console.error(`[abu-bridge] WS server error:`, err.message);
+            reject(err);
+        });
+        wss.on('connection', (ws, req) => {
+            const origin = req.headers.origin ?? 'unknown';
+            console.error(`[abu-bridge] Extension connected (origin: ${origin})`);
+            // Only allow one extension connection at a time
+            if (extensionSocket && extensionSocket.readyState === WebSocket.OPEN) {
+                console.error('[abu-bridge] Replacing existing extension connection');
+                extensionSocket.close(1000, 'Replaced by new connection');
+            }
+            extensionSocket = ws;
+            ws.on('message', (data) => {
+                try {
+                    const msg = JSON.parse(data.toString());
+                    handleResponse(msg);
+                }
+                catch (err) {
+                    console.error('[abu-bridge] Invalid message from extension:', err);
+                }
+            });
+            ws.on('close', (code, reason) => {
+                console.error(`[abu-bridge] Extension disconnected (code: ${code}, reason: ${reason.toString()})`);
+                if (extensionSocket === ws) {
+                    extensionSocket = null;
+                }
+                // Reject all pending requests
+                for (const [id, pending] of pendingRequests) {
+                    pending.reject(new Error('Extension disconnected'));
+                    clearTimeout(pending.timer);
+                    pendingRequests.delete(id);
+                }
+            });
+            ws.on('error', (err) => {
+                console.error('[abu-bridge] Extension socket error:', err.message);
+            });
+        });
+    });
+}
+function startHeartbeat() {
+    heartbeatTimer = setInterval(() => {
+        if (extensionSocket && extensionSocket.readyState === WebSocket.OPEN) {
+            extensionSocket.ping();
+        }
+    }, HEARTBEAT_INTERVAL);
+}
+function handleResponse(msg) {
+    const pending = pendingRequests.get(msg.id);
+    if (!pending) {
+        console.error(`[abu-bridge] Received response for unknown request: ${msg.id}`);
+        return;
+    }
+    clearTimeout(pending.timer);
+    pendingRequests.delete(msg.id);
+    pending.resolve(msg);
+}
+/**
+ * Send a request to the Chrome Extension and wait for response.
+ */
+export function sendToExtension(action, payload = {}, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        if (!extensionSocket || extensionSocket.readyState !== WebSocket.OPEN) {
+            reject(new Error('Chrome Extension is not connected. Please install and enable the Abu Browser Extension, then check the connection status in the extension popup.'));
+            return;
+        }
+        const id = generateId();
+        const request = { id, action, payload };
+        const timer = setTimeout(() => {
+            pendingRequests.delete(id);
+            reject(new Error(`Request timed out after ${timeoutMs}ms (action: ${action})`));
+        }, timeoutMs);
+        pendingRequests.set(id, { resolve, reject, timer });
+        extensionSocket.send(JSON.stringify(request));
+    });
+}
+/**
+ * Check if the Chrome Extension is currently connected.
+ */
+export function isExtensionConnected() {
+    return extensionSocket !== null && extensionSocket.readyState === WebSocket.OPEN;
+}
+/**
+ * Get the port the WS server is actually listening on.
+ */
+export function getActivePort() {
+    return activePort;
+}
+export function stopWSServer() {
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+    }
+    for (const [id, pending] of pendingRequests) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error('Server shutting down'));
+        pendingRequests.delete(id);
+    }
+    if (extensionSocket) {
+        extensionSocket.close(1000, 'Server shutting down');
+        extensionSocket = null;
+    }
+    if (wss) {
+        wss.close();
+        wss = null;
+    }
+    activePort = null;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "abu-browser-bridge",
+  "version": "0.1.0",
+  "description": "MCP Server that bridges Abu AI assistant with Chrome Extension for browser automation",
+  "type": "module",
+  "license": "MIT",
+  "author": "pm-shawn",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/abu"
+  },
+  "keywords": ["mcp", "browser", "automation", "chrome-extension", "abu"],
+  "bin": {
+    "abu-browser-bridge": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "cp ../abu-browser-shared/types.ts src/types.ts",
+    "build": "tsc",
+    "dev": "cp ../abu-browser-shared/types.ts src/types.ts && tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0"
+  }
+}