aether-mcp-server 2.1.0 → 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

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocatorEngine = void 0;
-const element_collector_1 = require("./element-collector");
 const DEFAULT_TIMEOUT = 7000;
 class LocatorEngine {
     client;
@@ -10,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 }));
         }
@@ -35,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)) {
@@ -82,173 +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(', ');
-
-            ${element_collector_1.SHARED_DOM_HELPERS}
-
-            // Thin aliases so the rest of this resolver reads naturally while the
-            // implementations stay shared with every other collector.
-            const norm = aetherNorm;
-            const visible = aetherVisible;
-            const cssPath = aetherStableSelector;
-            const inferRole = aetherImplicitRole;
-            const labelFor = aetherLabelFor;
-            const textFor = aetherAccessibleName;
-
-            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 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/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));