aether-mcp-server 2.0.0

package/dist/mcp-task-memory.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpTaskMemory = void 0;
+const MAX_MEMORY = 100;
+class McpTaskMemory {
+    tasks = [];
+    sessions = [];
+    create(action, url, parentId) {
+        const node = {
+            id: `v2-${Math.random().toString(36).substring(7)}`,
+            action,
+            url,
+            timestamp: new Date().toISOString(),
+            parentId,
+            status: "pending",
+        };
+        this.tasks.push(node);
+        this.trim(this.tasks);
+        return node;
+    }
+    recordSession(item) {
+        this.sessions.unshift({ timestamp: new Date().toISOString(), ...item });
+        this.trim(this.sessions);
+    }
+    graph() {
+        return this.tasks;
+    }
+    history() {
+        return this.sessions;
+    }
+    trim(items) {
+        while (items.length > MAX_MEMORY)
+            items.shift();
+    }
+}
+exports.McpTaskMemory = McpTaskMemory;

package/dist/page-snapshot-cache.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageSnapshotCache = void 0;
+const CACHE_TTL_MS = 1000;
+class PageSnapshotCache {
+    client;
+    locator;
+    version = 0;
+    cached = null;
+    constructor(client, locator) {
+        this.client = client;
+        this.locator = locator;
+        this.installInvalidationHooks();
+    }
+    invalidate(reason = "manual") {
+        this.version++;
+        this.cached = null;
+        console.error(`[SnapshotCache] invalidated: ${reason}`);
+    }
+    async compact(params = {}) {
+        const maxElements = Math.max(0, Math.min(Number(params.maxElements ?? 30), 200));
+        const now = Date.now();
+        const cached = this.cached;
+        if (cached && cached.version === this.version && now - cached.createdAt <= CACHE_TTL_MS && (maxElements === 0 || cached.hasElements)) {
+            return {
+                title: cached.title,
+                url: cached.url,
+                readyState: cached.readyState,
+                elementCount: cached.elements.length,
+                elements: cached.elements.slice(0, maxElements),
+                cache: { hit: true, version: cached.version, ageMs: now - cached.createdAt },
+            };
+        }
+        const [facts, elements] = await Promise.all([
+            this.client.evaluate(`({
+                title: document.title || "Unknown",
+                url: window.location.href || "Unknown",
+                readyState: document.readyState || "unknown"
+            })`).catch(() => ({ title: "Unknown", url: "Unknown", readyState: "unknown" })),
+            maxElements === 0
+                ? Promise.resolve([])
+                : this.locator.list(200, params.includeText !== false, !!params.withOverlay).catch(() => []),
+        ]);
+        this.cached = {
+            version: this.version,
+            createdAt: Date.now(),
+            hasElements: maxElements > 0,
+            title: String(facts?.title ?? "Unknown"),
+            url: String(facts?.url ?? "Unknown"),
+            readyState: String(facts?.readyState ?? "unknown"),
+            elements,
+        };
+        return {
+            title: this.cached.title,
+            url: this.cached.url,
+            readyState: this.cached.readyState,
+            elementCount: elements.length,
+            elements: elements.slice(0, maxElements),
+            cache: { hit: false, version: this.cached.version, ageMs: 0 },
+        };
+    }
+    installInvalidationHooks() {
+        const events = [
+            "DOM.documentUpdated",
+            "Page.frameNavigated",
+            "Page.loadEventFired",
+            "Runtime.executionContextDestroyed",
+            "Runtime.executionContextsCleared",
+        ];
+        for (const event of events) {
+            this.client.on(event, () => this.invalidate(event));
+        }
+    }
+}
+exports.PageSnapshotCache = PageSnapshotCache;

package/dist/policy-client.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planWithLocalPolicy = planWithLocalPolicy;
+const ALLOWED_INTENTS = new Set([
+    "navigate",
+    "click",
+    "fill",
+    "select",
+    "check",
+    "wait_for",
+    "inspect",
+]);
+function extractJson(text) {
+    const trimmed = text.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch { }
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+        return JSON.parse(trimmed.slice(start, end + 1));
+    }
+    throw new Error("Policy model did not return JSON.");
+}
+function validatePlan(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("Policy plan must be an object.");
+    }
+    const intent = String(raw.intent || "").toLowerCase();
+    if (!ALLOWED_INTENTS.has(intent)) {
+        throw new Error(`Unsupported policy intent: ${raw.intent}`);
+    }
+    const plan = { intent };
+    for (const key of ["target", "value", "role", "verify", "reason"]) {
+        if (raw[key] !== undefined && raw[key] !== null)
+            plan[key] = String(raw[key]);
+    }
+    if (raw.confidence !== undefined) {
+        const confidence = Number(raw.confidence);
+        if (Number.isFinite(confidence))
+            plan.confidence = Math.max(0, Math.min(1, confidence));
+    }
+    if (["click", "fill", "select", "check"].includes(intent) && !plan.target) {
+        throw new Error(`${intent} policy plan requires target.`);
+    }
+    if (["navigate", "fill", "select", "wait_for"].includes(intent) && !plan.value) {
+        throw new Error(`${intent} policy plan requires value.`);
+    }
+    return plan;
+}
+function buildPrompt(request) {
+    return [
+        "You are a tiny browser policy model.",
+        "Convert the user instruction and compact page snapshot into exactly one JSON action.",
+        "Return only JSON. No markdown. No prose.",
+        "",
+        "Allowed schema:",
+        '{"intent":"navigate|click|fill|select|check|wait_for|inspect","target":"visible label or CSS selector","value":"text/url/option when needed","role":"button|link|textbox|checkbox|combobox when useful","verify":"optional visible text to wait for","confidence":0.0,"reason":"short"}',
+        "",
+        "Rules:",
+        "- Prefer visible text, aria labels, labels, placeholders, or stable CSS selectors from the snapshot.",
+        "- Use navigate only when the instruction contains a URL or explicit page destination.",
+        "- Use inspect when the instruction asks only to observe/read.",
+        "- Do not invent hidden fields or credentials.",
+        "",
+        `Instruction: ${request.instruction}`,
+        "",
+        `Snapshot JSON: ${JSON.stringify(request.snapshot).slice(0, 12000)}`,
+    ].join("\n");
+}
+async function planWithLocalPolicy(request) {
+    const endpoint = process.env.AETHER_POLICY_ENDPOINT || "http://127.0.0.1:11434/v1/chat/completions";
+    const model = request.model || process.env.AETHER_POLICY_MODEL || "local-browser-policy";
+    const prompt = buildPrompt(request);
+    const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model,
+            temperature: 0,
+            messages: [
+                {
+                    role: "system",
+                    content: "Return one strict JSON object for the next browser action.",
+                },
+                {
+                    role: "user",
+                    content: prompt,
+                },
+            ],
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Policy model request failed (${response.status}): ${body.slice(0, 300)}`);
+    }
+    const payload = await response.json();
+    const content = payload?.choices?.[0]?.message?.content ?? payload?.message?.content ?? payload?.response;
+    if (typeof content !== "string") {
+        throw new Error("Policy model response did not include message content.");
+    }
+    return validatePlan(extractJson(content));
+}

package/dist/stealth.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STEALTH_SCRIPT = void 0;
+/**
+ * Comprehensive stealth script to bypass bot detection.
+ * Inspired by puppeteer-extra-plugin-stealth and modern bot bypass techniques.
+ */
+exports.STEALTH_SCRIPT = `
+(function() {
+    const safely = (patch) => {
+        try {
+            patch();
+        } catch (error) {
+            // Stealth must never break the page's own boot scripts.
+            console.debug('[Aether stealth] patch skipped', error);
+        }
+    };
+
+    // Helper to make overridden functions look native
+    const makeNative = (fn, name) => {
+        Object.defineProperty(fn, 'name', { value: name, configurable: true });
+        Object.defineProperty(fn, 'toString', {
+            value: () => \`function \${name}() { [native code] }\`,
+            configurable: true,
+            writable: true
+        });
+    };
+
+    // Helper to mock getters native-style
+    const mockGetter = (obj, prop, value) => {
+        if (!obj) return;
+        const desc = Object.getOwnPropertyDescriptor(obj, prop) || {
+            configurable: true,
+            enumerable: true
+        };
+        if (desc.configurable === false) return;
+        const getter = () => value;
+        makeNative(getter, \`get \${prop}\`);
+        Object.defineProperty(obj, prop, {
+            ...desc,
+            get: getter
+        });
+    };
+
+    // 1. Remove navigator.webdriver (or set to undefined native-style)
+    safely(() => mockGetter(navigator, 'webdriver', undefined));
+
+    // 2. Mock chrome.runtime without replacing existing Chrome globals.
+    safely(() => {
+        const chromeObj = window.chrome || {};
+        chromeObj.runtime = chromeObj.runtime || {};
+        Object.assign(chromeObj.runtime, {
+            OnInstalledReason: { INSTALL: 'install', UPDATE: 'update', CHROME_UPDATE: 'chrome_update', SHARED_MODULE_UPDATE: 'shared_module_update' },
+            OnRestartRequiredReason: { APP_UPDATE: 'app_update', OS_UPDATE: 'os_update', PERIODIC: 'periodic' },
+            PlatformArch: { ARM: 'arm', ARM64: 'arm64', X86_32: 'x86-32', X86_64: 'x86-64' },
+            PlatformNaclArch: { ARM: 'arm', X86_32: 'x86-32', X86_64: 'x86-64' },
+            PlatformOs: { ANDROID: 'android', CROS: 'cros', LINUX: 'linux', MAC: 'mac', OPENBSD: 'openbsd', WIN: 'win' },
+            RequestUpdateCheckStatus: { NO_UPDATE: 'no_update', UPDATE_AVAILABLE: 'update_available', THROTTLED: 'throttled' }
+        });
+        window.chrome = chromeObj;
+    });
+
+    // 3. Spoof navigator.languages
+    safely(() => mockGetter(navigator, 'languages', ['en-US', 'en']));
+
+    // 4. Spoof navigator.plugins
+    safely(() => mockGetter(navigator, 'plugins', (() => {
+        const plugins = [
+            { name: 'PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+            { name: 'Chrome PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+            { name: 'Chromium PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+            { name: 'Microsoft Edge PDF Viewer', filename: 'internal-pdf-viewer', description: 'Portable Document Format' },
+            { name: 'WebKit built-in PDF', filename: 'internal-pdf-viewer', description: 'Portable Document Format' }
+        ];
+        const p = [...plugins];
+        p.item = (i) => plugins[i];
+        p.namedItem = (n) => plugins.find(x => x.name === n);
+        p.refresh = () => {};
+        
+        makeNative(p.item, 'item');
+        makeNative(p.namedItem, 'namedItem');
+        makeNative(p.refresh, 'refresh');
+        
+        return p;
+    })()));
+
+    // 5. Overcome WebGL fingerprinting
+    safely(() => {
+        const contexts = [window.WebGLRenderingContext, window.WebGL2RenderingContext].filter(Boolean);
+        for (const Context of contexts) {
+            const getParameter = Context.prototype.getParameter;
+            if (typeof getParameter !== 'function') continue;
+            Context.prototype.getParameter = function(parameter) {
+                // UNMASKED_VENDOR_WEBGL
+                if (parameter === 37445) return 'Intel Inc.';
+                // UNMASKED_RENDERER_WEBGL
+                if (parameter === 37446) return 'Intel(R) Iris(TM) Graphics 6100';
+                return getParameter.apply(this, arguments);
+            };
+            makeNative(Context.prototype.getParameter, 'getParameter');
+        }
+    });
+
+    // 6. Fix navigator.permissions.query
+    safely(() => {
+        const permissions = window.navigator.permissions;
+        if (!permissions || typeof permissions.query !== 'function') return;
+        const originalQuery = permissions.query.bind(permissions);
+        permissions.query = (parameters) => (
+            parameters && parameters.name === 'notifications' ?
+                Promise.resolve({ state: Notification.permission }) :
+                originalQuery(parameters)
+        );
+        makeNative(permissions.query, 'query');
+    });
+
+    // 7. Mock navigator.deviceMemory
+    safely(() => {
+        if (!navigator.deviceMemory) {
+            mockGetter(navigator, 'deviceMemory', 8);
+        }
+    });
+
+    // 8. Mock hardwareConcurrency
+    safely(() => {
+        if (!navigator.hardwareConcurrency) {
+            mockGetter(navigator, 'hardwareConcurrency', 4);
+        }
+    });
+
+    // 9. Add window.outerHeight and window.outerWidth if missing (common in headless)
+    safely(() => {
+        if (window.outerHeight === 0) window.outerHeight = window.innerHeight;
+        if (window.outerWidth === 0) window.outerWidth = window.innerWidth;
+    });
+})();
+`;

package/dist/trace-recorder.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordPolicyTrace = recordPolicyTrace;
+exports.recordPolicyFeedback = recordPolicyFeedback;
+const promises_1 = require("fs/promises");
+const path_1 = __importDefault(require("path"));
+const SECRET_KEYS = /password|passwd|secret|token|cookie|authorization|api[-_]?key|client[-_]?key/i;
+function redact(value, key = "") {
+    if (SECRET_KEYS.test(key))
+        return "[REDACTED]";
+    if (Array.isArray(value))
+        return value.map((item) => redact(item));
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [entryKey, redact(entryValue, entryKey)]));
+}
+function tracePath() {
+    return process.env.AETHER_POLICY_TRACE_PATH ||
+        path_1.default.join(process.cwd(), "data", "policy-traces.jsonl");
+}
+function feedbackPath() {
+    return process.env.AETHER_POLICY_FEEDBACK_PATH ||
+        path_1.default.join(process.cwd(), "data", "policy-feedback.jsonl");
+}
+function createTraceId() {
+    return `pol_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+async function recordPolicyTrace(trace) {
+    const id = trace.id || createTraceId();
+    if (process.env.AETHER_RECORD_POLICY_TRACES === "false")
+        return id;
+    const filePath = tracePath();
+    const safeTrace = redact({ ...trace, id });
+    await (0, promises_1.mkdir)(path_1.default.dirname(filePath), { recursive: true });
+    await (0, promises_1.appendFile)(filePath, `${JSON.stringify(safeTrace)}\n`, "utf8");
+    return id;
+}
+async function recordPolicyFeedback(feedback) {
+    const filePath = feedbackPath();
+    const safeFeedback = redact(feedback);
+    await (0, promises_1.mkdir)(path_1.default.dirname(filePath), { recursive: true });
+    await (0, promises_1.appendFile)(filePath, `${JSON.stringify(safeFeedback)}\n`, "utf8");
+}

package/dist/ws-server.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activeConnection = void 0;
+exports.ensurePortAvailable = ensurePortAvailable;
+exports.StartWebSocketServer = StartWebSocketServer;
+exports.sendCommandToExtension = sendCommandToExtension;
+const ws_1 = require("ws");
+const http_1 = __importDefault(require("http"));
+exports.activeConnection = null;
+let messageIdCounter = 0;
+const pendingRequests = new Map();
+/**
+ * Ensure port is available by killing any stale server
+ */
+async function ensurePortAvailable(port) {
+    return new Promise((resolve) => {
+        const req = http_1.default.get(`http://localhost:${port}/shutdown`, (res) => {
+            console.error(`[WS] Sent shutdown to existing server on port ${port}`);
+            setTimeout(resolve, 1500);
+        });
+        req.on("error", () => {
+            resolve();
+        });
+        req.setTimeout(2000, () => {
+            req.destroy();
+            resolve();
+        });
+    });
+}
+function StartWebSocketServer(port) {
+    let retryCount = 0;
+    const MAX_RETRIES = 3;
+    const server = http_1.default.createServer((req, res) => {
+        if (req.url === "/health") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                status: "ok",
+                connected: exports.activeConnection !== null,
+                pid: process.pid,
+            }));
+        }
+        else if (req.url === "/shutdown") {
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end("shutting down");
+            console.error("[WS] Received shutdown request. Exiting...");
+            setTimeout(() => process.exit(0), 500);
+        }
+        else {
+            res.writeHead(404);
+            res.end();
+        }
+    });
+    const wss = new ws_1.WebSocketServer({ server });
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            if (retryCount >= MAX_RETRIES) {
+                console.error(`[WS] Port ${port} in use. Max retries reached. Exiting.`);
+                process.exit(1);
+            }
+            retryCount++;
+            console.error(`[WS] Port ${port} in use. Retry ${retryCount}/${MAX_RETRIES} after 2s...`);
+            setTimeout(() => {
+                server.close();
+                StartWebSocketServer(port);
+            }, 2000);
+        }
+        else {
+            console.error("[WS] Server error:", err.message);
+        }
+    });
+    server.listen(port, () => {
+        console.error(`[WS] HTTP/WebSocket Server listening on port ${port}`);
+        retryCount = 0; // Reset on success
+    });
+    wss.on("connection", (ws) => {
+        console.error("[WS] Extension connected");
+        exports.activeConnection = ws;
+        ws.on("message", (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                if (message.id !== undefined && pendingRequests.has(message.id)) {
+                    const { resolve, reject } = pendingRequests.get(message.id);
+                    if (message.error) {
+                        reject(new Error(message.error));
+                    }
+                    else {
+                        resolve(message.result);
+                    }
+                    pendingRequests.delete(message.id);
+                }
+                else if (message.method === "ping") {
+                    // Heartbeat — ignore
+                }
+            }
+            catch (err) {
+                console.error("[WS] Parse error:", err);
+            }
+        });
+        ws.on("close", () => {
+            console.error("[WS] Extension disconnected");
+            if (exports.activeConnection === ws) {
+                exports.activeConnection = null;
+            }
+            for (const [id, { reject }] of pendingRequests) {
+                reject(new Error("Extension disconnected"));
+            }
+            pendingRequests.clear();
+        });
+        ws.on("error", (err) => {
+            console.error("[WS] Connection error:", err.message);
+        });
+    });
+    return wss;
+}
+function sendCommandToExtension(method, params) {
+    return new Promise((resolve, reject) => {
+        if (!exports.activeConnection || exports.activeConnection.readyState !== ws_1.WebSocket.OPEN) {
+            return reject(new Error("No active extension connection"));
+        }
+        const id = ++messageIdCounter;
+        const timeout = setTimeout(() => {
+            pendingRequests.delete(id);
+            reject(new Error(`Command '${method}' timed out after 30s`));
+        }, 30000);
+        pendingRequests.set(id, {
+            resolve: (val) => { clearTimeout(timeout); resolve(val); },
+            reject: (err) => { clearTimeout(timeout); reject(err); },
+        });
+        exports.activeConnection.send(JSON.stringify({ id, method, params }));
+    });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "aether-mcp-server",
+    "version": "2.0.0",
+    "description": "Aether MCP Server - AI Browser Controller",
+    "main": "dist/index.js",
+    "bin": {
+        "aether-mcp-server": "dist/index.js"
+    },
+    "files": [
+        "dist/"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "postbuild": "node -e \"const f=require('fs');const c=f.readFileSync('dist/index.js','utf8');f.writeFileSync('dist/index.js','#!/usr/bin/env node\\n'+c.replace('#!/usr/bin/env node\\n',''))\"",
+        "start": "ts-node src/index.ts",
+        "dev": "nodemon src/index.ts",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [],
+    "author": "",
+    "license": "ISC",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^0.6.0",
+        "ws": "^8.18.0",
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.5.5",
+        "@types/ws": "^8.5.12",
+        "nodemon": "^3.1.4",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.6.2"
+    }
+}