aether-mcp-server 2.0.2 → 2.1.1

package/dist/index.js

@@ -3,17 +3,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
-const ws_server_1 = require("./ws-server");
 const mcp_server_1 = require("./mcp-server");
 const cdp_client_1 = require("./cdp-client");
-const WS_PORT = 3009;
-const MODE = process.env.AETHER_MODE || "cdp"; // "cdp" or "extension"
+const logger_1 = require("./logger");
+const log = (0, logger_1.createLogger)("index");
 // Graceful shutdown handler
 async function shutdown() {
-    console.error("\n[Server] Shutting down...");
+    log.info("Shutting down...");
     const client = (0, cdp_client_1.getCdpClient)();
     if (client.isConnected()) {
-        console.error("[Server] Killing browser...");
+        log.info("Killing browser...");
         await client.killBrowser();
     }
     process.exit(0);
@@ -22,11 +21,11 @@ async function shutdown() {
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
 process.on("uncaughtException", (err) => {
-    console.error("[Server] Uncaught Exception:", err);
+    log.error("Uncaught Exception", { error: String(err) });
     shutdown();
 });
 process.on("unhandledRejection", (reason, promise) => {
-    console.error("[Server] Unhandled Rejection at:", promise, "reason:", reason);
+    log.error("Unhandled Rejection", { reason: String(reason) });
     shutdown();
 });
 process.on("exit", () => {
@@ -36,36 +35,25 @@ process.on("exit", () => {
     }
 });
 async function main() {
-    console.error(`Starting MCP Browser Server (mode: ${MODE})...`);
-    let wsServer = null;
-    if (MODE === "extension") {
-        // 1. Kill any stale server on the port
-        await (0, ws_server_1.ensurePortAvailable)(WS_PORT);
-        // 2. Start WebSocket Server for Extension
-        wsServer = (0, ws_server_1.StartWebSocketServer)(WS_PORT);
-        console.error("WebSocket server started for extension mode");
-    }
-    else {
-        console.error("CDP mode enabled - no extension needed");
-        console.error("To connect to a browser, use the 'launch_browser' or 'connect_browser' tool");
-    }
-    // 3. Initialize MCP Server
+    log.info("Starting Aether MCP Browser Server (CDP mode — no extension needed)...");
+    log.info("Use 'launch_browser' or 'connect_browser' tool to connect to a browser.");
+    // Initialize MCP Server
     const server = new index_js_1.Server({
-        name: "mcp-browser-control",
-        version: "2.0.0",
+        name: "aether-mcp-server",
+        version: "2.1.0",
     }, {
         capabilities: {
             tools: {},
         },
     });
-    // 4. Register Tools
-    (0, mcp_server_1.RegisterMcpTools)(server, wsServer);
-    // 5. Connect Transport
+    // Register Tools
+    (0, mcp_server_1.RegisterMcpTools)(server);
+    // Connect Transport
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
-    console.error("MCP Server connected via Stdio");
+    log.info("MCP Server connected via Stdio. Ready.");
 }
 main().catch((err) => {
-    console.error("Fatal Error:", err);
+    log.error("Fatal Error", { error: String(err) });
     process.exit(1);
 });

package/dist/locator-engine.js

@@ -9,15 +9,12 @@ class LocatorEngine {
     }
     async list(maxElements = 50, includeText = true, withOverlay = false) {
         const capped = Math.max(0, Math.min(Number(maxElements || 50), 200));
-        const result = await this.client.evaluate(locatorScript({
-            target: "",
-            role: "",
-            selector: "",
-            maxCandidates: capped,
-            includeText,
-            mode: "list",
-        }));
-        const candidates = normalizeCandidates(result?.candidates).slice(0, capped);
+        const result = await this.client.evaluate(`window.__aetherLocate(${JSON.stringify(JSON.stringify({
+            target: "", role: "", selector: "",
+            maxCandidates: capped, includeText, mode: "list",
+        }))})`);
+        const parsed = safeJsonParse(result);
+        const candidates = normalizeCandidates(parsed?.candidates).slice(0, capped);
         if (withOverlay && candidates.length > 0) {
             await this.client.getInteractiveElements(true).catch(() => ({ elements: [], somInjected: false }));
         }
@@ -34,14 +31,11 @@ class LocatorEngine {
             return { success: false, message: "target, role, or selector required" };
         }
         while (Date.now() - started < timeout) {
-            const result = await this.client.evaluate(locatorScript({
-                target,
-                role,
-                selector,
-                maxCandidates,
-                includeText: true,
-                mode: "resolve",
-            })).catch((error) => ({ error: error.message }));
+            const resultJson = await this.client.evaluate(`window.__aetherLocate(${JSON.stringify(JSON.stringify({
+                target, role, selector: selector,
+                maxCandidates, includeText: true, mode: "resolve",
+            }))})`).catch((error) => ({ error: error.message }));
+            const result = safeJsonParse(resultJson);
             const candidates = normalizeCandidates(result?.candidates);
             const best = candidates[0];
             if (best && (selector || best.score > 0 || role)) {
@@ -81,246 +75,14 @@ function normalizeCandidates(value) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function locatorScript(input) {
-    return `
-        (function() {
-            const target = ${JSON.stringify(input.target)};
-            const targetLower = target.toLowerCase();
-            const roleHint = ${JSON.stringify(input.role)};
-            const selectorHint = ${JSON.stringify(input.selector)};
-            const maxCandidates = ${JSON.stringify(input.maxCandidates)};
-            const includeText = ${JSON.stringify(input.includeText)};
-            const mode = ${JSON.stringify(input.mode)};
-            const interactiveSelector = [
-                'a[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea',
-                '[onclick]', '[role]', '[tabindex]:not([tabindex="-1"])', 'label', 'summary',
-                '[contenteditable="true"]', '[aria-label]', '[placeholder]'
-            ].join(', ');
-
-            function norm(value) {
-                return String(value || '').trim().replace(/\\s+/g, ' ');
-            }
-
-            function visible(el) {
-                const rect = el.getBoundingClientRect();
-                const style = window.getComputedStyle(el);
-                return style.display !== 'none' &&
-                    style.visibility !== 'hidden' &&
-                    style.opacity !== '0' &&
-                    rect.width > 0 &&
-                    rect.height > 0;
-            }
-
-            function cssPath(el) {
-                if (!el || el.nodeType !== Node.ELEMENT_NODE) return '';
-                if (el.id) return '#' + CSS.escape(el.id);
-                const path = [];
-                let node = el;
-                while (node && node.nodeType === Node.ELEMENT_NODE && node !== node.ownerDocument.body) {
-                    let part = node.nodeName.toLowerCase();
-                    if (node.classList && node.classList.length) {
-                        part += '.' + Array.from(node.classList).slice(0, 2).map((c) => CSS.escape(c)).join('.');
-                    }
-                    const parent = node.parentElement;
-                    if (parent) {
-                        const same = Array.from(parent.children).filter((child) => child.nodeName === node.nodeName);
-                        if (same.length > 1) part += ':nth-of-type(' + (same.indexOf(node) + 1) + ')';
-                    }
-                    path.unshift(part);
-                    node = parent;
-                }
-                return path.join(' > ');
-            }
-
-            function xpath(el) {
-                const parts = [];
-                let node = el;
-                while (node && node.nodeType === Node.ELEMENT_NODE) {
-                    let index = 1;
-                    let sibling = node.previousElementSibling;
-                    while (sibling) {
-                        if (sibling.nodeName === node.nodeName) index++;
-                        sibling = sibling.previousElementSibling;
-                    }
-                    parts.unshift(node.nodeName.toLowerCase() + '[' + index + ']');
-                    node = node.parentElement;
-                }
-                return '/' + parts.join('/');
-            }
-
-            function inferRole(el) {
-                const explicit = (el.getAttribute('role') || '').toLowerCase();
-                if (explicit) return explicit;
-                const tag = el.tagName.toLowerCase();
-                const type = (el.getAttribute('type') || '').toLowerCase();
-                if (tag === 'button' || type === 'button' || type === 'submit' || type === 'reset') return 'button';
-                if (tag === 'a') return 'link';
-                if (tag === 'textarea') return 'textbox';
-                if (tag === 'select') return 'combobox';
-                if (tag === 'input' && ['checkbox', 'radio'].includes(type)) return type;
-                if (tag === 'input') return 'textbox';
-                if (el.isContentEditable) return 'textbox';
-                if (tag === 'summary') return 'button';
-                return tag;
-            }
-
-            function byId(doc, id) {
-                if (!id) return '';
-                const el = doc.getElementById(id);
-                return el ? norm(el.innerText || el.textContent) : '';
-            }
-
-            function labelFor(el) {
-                const doc = el.ownerDocument;
-                const labelledBy = norm((el.getAttribute('aria-labelledby') || '').split(/\\s+/).map((id) => byId(doc, id)).join(' '));
-                if (labelledBy) return labelledBy;
-                if (el.id) {
-                    const direct = doc.querySelector('label[for="' + CSS.escape(el.id) + '"]');
-                    if (direct) return norm(direct.innerText || direct.textContent);
-                }
-                const wrapping = el.closest && el.closest('label');
-                return wrapping ? norm(wrapping.innerText || wrapping.textContent) : '';
-            }
-
-            function textFor(el) {
-                return norm(
-                    el.getAttribute('aria-label') ||
-                    labelFor(el) ||
-                    el.getAttribute('placeholder') ||
-                    el.getAttribute('alt') ||
-                    el.getAttribute('title') ||
-                    el.innerText ||
-                    el.textContent ||
-                    el.getAttribute('value') ||
-                    el.getAttribute('name') ||
-                    ''
-                );
-            }
-
-            function scoreField(field, value, exact, includes) {
-                const text = norm(value);
-                const lower = text.toLowerCase();
-                if (!targetLower) return { score: 0, by: '' };
-                if (lower === targetLower) return { score: exact, by: field + ':exact' };
-                if (lower.includes(targetLower)) return { score: includes, by: field + ':contains' };
-                if (targetLower.includes(lower) && lower.length >= 3) return { score: Math.max(1, includes - 1), by: field + ':contained_by_target' };
-                return { score: 0, by: '' };
-            }
-
-            function scoreCandidate(item) {
-                let score = 0;
-                let matchedBy = '';
-                const fields = [
-                    ['selector', item.selector, 13, 10],
-                    ['xpath', item.xpath, 11, 8],
-                    ['name', item.name, 12, 10],
-                    ['label', item.label, 12, 10],
-                    ['placeholder', item.placeholder, 11, 9],
-                    ['text', item.text, 10, 8],
-                    ['title', item.title, 8, 6],
-                    ['value', item.value, 7, 5]
-                ];
-                for (const field of fields) {
-                    const match = scoreField(field[0], field[1], field[2], field[3]);
-                    if (match.score > score) {
-                        score = match.score;
-                        matchedBy = match.by;
-                    }
-                }
-                if (roleHint) {
-                    if (item.role === roleHint) score += 5;
-                    else if (roleHint === 'textbox' && ['input', 'textarea'].includes(item.tag)) score += 3;
-                    else score -= 3;
-                }
-                if (!targetLower && roleHint && item.role === roleHint) {
-                    matchedBy = 'role';
-                    score = Math.max(score, 5);
-                }
-                if (item.scope !== 'document') score += 1;
-                item.score = score;
-                item.matchedBy = matchedBy || (selectorHint ? 'selector' : '');
-                return item;
-            }
-
-            function collectFromRoot(root, framePath, frameOffset, shadowDepth, scope, out) {
-                let nodes = [];
-                try {
-                    if (selectorHint) {
-                        nodes = Array.from(root.querySelectorAll(selectorHint));
-                    } else {
-                        nodes = Array.from(root.querySelectorAll(interactiveSelector));
-                    }
-                } catch {
-                    nodes = [];
-                }
-
-                for (const el of nodes) {
-                    if (!visible(el)) continue;
-                    const rect = el.getBoundingClientRect();
-                    const selector = cssPath(el);
-                    const role = inferRole(el);
-                    const label = labelFor(el);
-                    const item = {
-                        ref: '',
-                        selector,
-                        xpath: xpath(el),
-                        scope,
-                        framePath: framePath.slice(),
-                        shadowDepth,
-                        tag: el.tagName.toLowerCase(),
-                        role,
-                        type: el.getAttribute('type') || '',
-                        name: norm(el.getAttribute('aria-label') || label || textFor(el) || el.getAttribute('name')),
-                        text: includeText ? norm(el.innerText || el.textContent).substring(0, 180) : '',
-                        label,
-                        placeholder: norm(el.getAttribute('placeholder')),
-                        title: norm(el.getAttribute('title')),
-                        value: norm(el.getAttribute('value')),
-                        score: 0,
-                        matchedBy: '',
-                        bounds: {
-                            x: Math.round(frameOffset.x + rect.left),
-                            y: Math.round(frameOffset.y + rect.top),
-                            width: Math.round(rect.width),
-                            height: Math.round(rect.height)
-                        }
-                    };
-                    item.ref = item.scope === 'document' && item.framePath.length === 0 && item.shadowDepth === 0
-                        ? 'css:' + item.selector
-                        : 'point:' + Math.round(item.bounds.x + item.bounds.width / 2) + ',' + Math.round(item.bounds.y + item.bounds.height / 2);
-                    out.push(scoreCandidate(item));
-                }
-
-                const all = [];
-                try {
-                    all.push(...Array.from(root.querySelectorAll('*')));
-                } catch {}
-
-                for (const el of all) {
-                    if (el.shadowRoot) {
-                        collectFromRoot(el.shadowRoot, framePath, frameOffset, shadowDepth + 1, 'shadow', out);
-                    }
-                    if (el.tagName && el.tagName.toLowerCase() === 'iframe') {
-                        try {
-                            const doc = el.contentDocument;
-                            if (!doc) continue;
-                            const rect = el.getBoundingClientRect();
-                            collectFromRoot(doc, framePath.concat([Array.from(el.ownerDocument.querySelectorAll('iframe')).indexOf(el)]), {
-                                x: frameOffset.x + rect.left,
-                                y: frameOffset.y + rect.top
-                            }, shadowDepth, 'frame', out);
-                        } catch {}
-                    }
-                }
-            }
-
-            const candidates = [];
-            collectFromRoot(document, [], { x: 0, y: 0 }, 0, 'document', candidates);
-            candidates.sort((a, b) => {
-                if (mode === 'list') return (a.bounds.y - b.bounds.y) || (a.bounds.x - b.bounds.x);
-                return b.score - a.score || a.bounds.y - b.bounds.y || a.bounds.x - b.bounds.x;
-            });
-            return { candidates: candidates.slice(0, maxCandidates) };
-        })()
-    `;
+function safeJsonParse(value) {
+    if (typeof value === "string") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return value;
 }

package/dist/logger.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Aether structured logger with correlation IDs for agent action tracing.
+ * Replaces ad-hoc console.error calls with leveled, structured output.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rootLogger = void 0;
+exports.setLogLevel = setLogLevel;
+exports.onLog = onLog;
+exports.createLogger = createLogger;
+let globalLogLevel = "info";
+const listeners = [];
+function setLogLevel(level) {
+    globalLogLevel = level;
+}
+function onLog(fn) {
+    listeners.push(fn);
+    return () => {
+        const idx = listeners.indexOf(fn);
+        if (idx >= 0)
+            listeners.splice(idx, 1);
+    };
+}
+const LEVEL_PRIO = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function shouldLog(level) {
+    return LEVEL_PRIO[level] >= LEVEL_PRIO[globalLogLevel];
+}
+function emit(entry) {
+    if (!shouldLog(entry.level))
+        return;
+    // Structured stderr output for MCP transport
+    const prefix = entry.corrId ? `[${entry.corrId}]` : "";
+    const actionTag = entry.action ? ` [${entry.action}]` : "";
+    const dataSuffix = entry.data ? ` ${JSON.stringify(entry.data)}` : "";
+    const method = entry.level === "error"
+        ? "error"
+        : entry.level === "warn"
+            ? "warn"
+            : "error"; // MCP uses stderr for all logging
+    console.error(`[Aether:${entry.level.toUpperCase()}]${prefix}${actionTag} ${entry.msg}${dataSuffix}`);
+    for (const fn of listeners) {
+        try {
+            fn(entry);
+        }
+        catch {
+            // Listener errors must not break logging
+        }
+    }
+}
+let idCounter = 0;
+function createLogger(corrId) {
+    const cid = corrId ?? `req-${++idCounter}-${Date.now().toString(36)}`;
+    const log = (level, msg, data, action) => {
+        emit({
+            ts: new Date().toISOString(),
+            level,
+            corrId: cid,
+            action,
+            msg,
+            data,
+        });
+    };
+    return {
+        corrId: cid,
+        debug(msg, data) {
+            log("debug", msg, data);
+        },
+        info(msg, data) {
+            log("info", msg, data);
+        },
+        warn(msg, data) {
+            log("warn", msg, data);
+        },
+        error(msg, data) {
+            log("error", msg, data);
+        },
+        child(action) {
+            return {
+                corrId: cid,
+                debug(msg, data) {
+                    log("debug", msg, data, action);
+                },
+                info(msg, data) {
+                    log("info", msg, data, action);
+                },
+                warn(msg, data) {
+                    log("warn", msg, data, action);
+                },
+                error(msg, data) {
+                    log("error", msg, data, action);
+                },
+                child(subAction) {
+                    return this.child(`${action}/${subAction}`);
+                },
+            };
+        },
+    };
+}
+// Default logger (no correlation ID)
+exports.rootLogger = createLogger("root");

package/dist/mcp-server.js

@@ -663,6 +663,41 @@ const Tools = [
             required: ["fields"]
         }
     },
+    {
+        name: "get_page_text",
+        description: "READ TOOL. Extract clean, readable page content as Markdown (or plain text). Token-cheap alternative to screenshots or full DOM dumps for reading/understanding a page. Scopes to a CSS selector when given, otherwise auto-detects the main content region.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                format: { type: "string", enum: ["markdown", "text"], description: "Output format. Default markdown." },
+                selector: { type: "string", description: "Optional CSS selector to scope extraction to a region." },
+                includeLinks: { type: "boolean", description: "Render anchors as [text](href) in markdown. Default true." },
+                maxLength: { type: "number", description: "Max characters returned before truncation. Default 20000." }
+            }
+        }
+    },
+    {
+        name: "save_auth_state",
+        description: "SESSION TOOL. Export the current browser session (cookies + localStorage + sessionStorage) to a JSON file so a logged-in session can be reused later with load_auth_state. Avoids repeating logins.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path to write the auth state JSON. Defaults to <cwd>/.aether/auth-state.json." },
+                origins: { type: "array", items: { type: "string" }, description: "Optional list of origins to capture storage for. Defaults to the current origin." }
+            }
+        }
+    },
+    {
+        name: "load_auth_state",
+        description: "SESSION TOOL. Restore a previously saved session (cookies + localStorage + sessionStorage) from a JSON file written by save_auth_state. Navigate to the target site first, then load, then reload.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File path to read the auth state JSON. Defaults to <cwd>/.aether/auth-state.json." },
+                reload: { type: "boolean", description: "Reload the active tab after restoring so storage takes effect. Default true." }
+            }
+        }
+    },
     {
         name: "page_snapshot",
         description: "Capture page context optimized for LLM consumption. Lightweight by default; opt into screenshots, cookies, accessibility tree, or full DOM snapshot when needed.",
@@ -1221,6 +1256,30 @@ function RegisterMcpTools(server, wsServer) {
                 }
                 return { content };
             }
+            if (name === "get_page_text") {
+                const result = await bridge.sendCommand("get_page_text", {
+                    format: a?.format,
+                    selector: a?.selector,
+                    includeLinks: a?.includeLinks,
+                    maxLength: a?.maxLength,
+                });
+                const header = `Title: ${result.title}\nURL: ${result.url}\nFormat: ${result.format} | ${result.length} chars${result.truncated ? " (truncated)" : ""}`;
+                return { content: [{ type: "text", text: `${header}\n\n${result.text}` }] };
+            }
+            if (name === "save_auth_state") {
+                const result = await bridge.sendCommand("save_auth_state", {
+                    path: a?.path,
+                    origins: a?.origins,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result) }] };
+            }
+            if (name === "load_auth_state") {
+                const result = await bridge.sendCommand("load_auth_state", {
+                    path: a?.path,
+                    reload: a?.reload,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result) }] };
+            }
             throw new Error(`Unknown tool: ${name}`);
         }
         catch (error) {

package/dist/page-snapshot-cache.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PageSnapshotCache = void 0;
-const CACHE_TTL_MS = 1000;
+const CACHE_TTL_MS = 5000; // 5s — safe because cache auto-invalidates on DOM mutations
 class PageSnapshotCache {
     client;
     locator;
     version = 0;
     cached = null;
+    lastUrl = "";
     constructor(client, locator) {
         this.client = client;
         this.locator = locator;
@@ -15,7 +16,21 @@ class PageSnapshotCache {
     invalidate(reason = "manual") {
         this.version++;
         this.cached = null;
-        console.error(`[SnapshotCache] invalidated: ${reason}`);
+    }
+    /** Returns true if the cache is fresh enough to serve. */
+    isFresh() {
+        const c = this.cached;
+        return !!(c && c.version === this.version && (Date.now() - c.createdAt) <= CACHE_TTL_MS);
+    }
+    /** Get cache metadata for debugging. */
+    getCacheInfo() {
+        const c = this.cached;
+        return {
+            version: this.version,
+            ageMs: c ? Date.now() - c.createdAt : Infinity,
+            fresh: this.isFresh(),
+            url: c?.url ?? "",
+        };
     }
     async compact(params = {}) {
         const maxElements = Math.max(0, Math.min(Number(params.maxElements ?? 30), 200));