yoke-mcp 0.1.0

package/dist/native-host.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// The native messaging host: a relay, and nothing more.
+//
+// Chrome owns this process. It spawns it when the extension calls
+// connectNative, talks to it over stdin and stdout using a 4-byte
+// little-endian length prefix per JSON message, and kills it when the extension
+// disconnects. So a client cannot be the one to start it, and needs a second hop
+// to reach the extension at all.
+//
+// That hop is a unix socket in a 0700 directory the user owns, rather than a TCP
+// port. Whoever reaches this endpoint can read every tab in a logged-in browser,
+// so "any local process can connect" is not an acceptable posture; file
+// permissions are the cheapest correct answer. Windows gets a named pipe, where
+// the path namespace plays the same role.
+import { chmodSync, mkdirSync, statSync, unlinkSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { dirname } from 'node:path';
+import { PROTOCOL, isResponse } from './protocol.js';
+import { endpointPath } from './socket-path.js';
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** 0700, and verified after creation rather than assumed. */
+function prepareDirectory(socketPath) {
+    const dir = dirname(socketPath);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform === 'win32') {
+        return;
+    }
+    chmodSync(dir, 0o700);
+    const mode = statSync(dir).mode & 0o777;
+    if (mode !== 0o700) {
+        throw new Error(`${dir} is mode ${mode.toString(8)}, refusing to listen where others can reach the socket`);
+    }
+}
+/** Chrome's framing: one 4-byte little-endian length, then that many JSON bytes. */
+function writeToChrome(message) {
+    const body = Buffer.from(JSON.stringify(message), 'utf8');
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(body.length, 0);
+    process.stdout.write(Buffer.concat([header, body]));
+}
+function readFromChrome(onMessage) {
+    let buffer = Buffer.alloc(0);
+    process.stdin.on('data', (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        for (;;) {
+            if (buffer.length < 4) {
+                return;
+            }
+            const length = buffer.readUInt32LE(0);
+            if (buffer.length < 4 + length) {
+                return;
+            }
+            const body = buffer.subarray(4, 4 + length);
+            buffer = buffer.subarray(4 + length);
+            try {
+                onMessage(JSON.parse(body.toString('utf8')));
+            }
+            catch { /* not ours to fix */ }
+        }
+    });
+}
+export function main() {
+    const socketPath = endpointPath();
+    const waiting = new Map();
+    let nextId = 1;
+    let server;
+    const cleanup = () => {
+        try {
+            server?.close();
+        }
+        catch { /* never listened */ }
+        if (process.platform !== 'win32') {
+            try {
+                unlinkSync(socketPath);
+            }
+            catch { /* already gone */ }
+        }
+    };
+    readFromChrome((message) => {
+        if (!isResponse(message)) {
+            return;
+        }
+        const settle = waiting.get(message.id);
+        if (!settle) {
+            return;
+        }
+        waiting.delete(message.id);
+        settle(message.ok
+            ? { ok: true, data: message.data, protocol: PROTOCOL }
+            : { ok: false, error: message.error, protocol: PROTOCOL });
+    });
+    // Chrome closing stdin means the extension went away, so the socket must go
+    // too rather than linger and accept callers it can no longer serve.
+    process.stdin.on('end', () => { cleanup(); process.exit(0); });
+    server = createServer((connection) => {
+        let text = '';
+        connection.on('data', (chunk) => {
+            text += chunk.toString('utf8');
+            for (;;) {
+                const cut = text.indexOf('\n');
+                if (cut === -1) {
+                    return;
+                }
+                const line = text.slice(0, cut);
+                text = text.slice(cut + 1);
+                if (!line.trim()) {
+                    continue;
+                }
+                let request;
+                try {
+                    request = JSON.parse(line);
+                }
+                catch {
+                    const reply = { ok: false, error: 'each line must be one JSON object' };
+                    connection.write(`${JSON.stringify(reply)}\n`);
+                    continue;
+                }
+                const id = nextId++;
+                // A silent extension must not hang the caller, and a caller that hangs
+                // up must not leave the relay waiting forever.
+                const timer = setTimeout(() => {
+                    if (!waiting.delete(id)) {
+                        return;
+                    }
+                    const reply = { ok: false, error: 'the extension did not answer' };
+                    try {
+                        connection.write(`${JSON.stringify(reply)}\n`);
+                    }
+                    catch { /* gone */ }
+                }, request.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+                waiting.set(id, (reply) => {
+                    clearTimeout(timer);
+                    try {
+                        connection.write(`${JSON.stringify(reply)}\n`);
+                    }
+                    catch { /* caller hung up */ }
+                });
+                writeToChrome({ id, op: request.op, args: request.args });
+            }
+        });
+        connection.on('error', () => { });
+    });
+    prepareDirectory(socketPath);
+    // A stale socket from a host Chrome killed would otherwise block the bind.
+    if (process.platform !== 'win32') {
+        try {
+            unlinkSync(socketPath);
+        }
+        catch { /* nothing there */ }
+    }
+    server.listen(socketPath, () => {
+        if (process.platform !== 'win32') {
+            chmodSync(socketPath, 0o600);
+        }
+    });
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(signal, () => { cleanup(); process.exit(0); });
+    }
+}
+// Runs unconditionally, because this file exists only to be executed.
+//
+// It used to be guarded by comparing process.argv[1] to this module's path,
+// which can never match: Chrome invokes a native messaging host with the calling
+// extension's origin as argv[1], not the script path. So the guard was always
+// false, main() never ran, the process exited instantly, and Chrome reported
+// "Native host has exited" with nothing else to go on. An entry point that the
+// runner invokes with unpredictable arguments cannot detect itself from argv, so
+// it should not try.
+main();
+//# sourceMappingURL=native-host.js.map

package/dist/native-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-host.js","sourceRoot":"","sources":["../src/native-host.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,339 @@
+/** Bumped when a message shape changes in a way an older peer cannot read. */
+export declare const PROTOCOL = 1;
+export interface TabInfo {
+    id: number;
+    windowId: number;
+    /** `-1` when the tab is in no group. */
+    groupId: number;
+    title: string;
+    url: string;
+}
+export interface GroupInfo {
+    id: number;
+    title: string;
+    color: string;
+    windowId: number;
+    collapsed: boolean;
+}
+/** Every operation the extension implements, and what each one answers with. */
+export interface Operations {
+    ping: {
+        args: Record<string, never>;
+        result: {
+            extension: string;
+        };
+    };
+    listTabs: {
+        args: Record<string, never>;
+        result: {
+            tabs: TabInfo[];
+        };
+    };
+    listGroups: {
+        args: Record<string, never>;
+        result: {
+            groups: GroupInfo[];
+        };
+    };
+    /**
+     * Navigate one tab, by id, and wait for the load to settle.
+     *
+     * `tabId` is never implied. There is no acting on the active tab because none
+     * was named: that is how a script ends up driving whatever the user happened
+     * to be looking at.
+     */
+    navigate: {
+        args: {
+            tabId: number;
+            url: string;
+            timeoutMs?: number;
+        };
+        result: {
+            tabId: number;
+            url: string;
+            title: string;
+            status: 'complete' | 'timeout';
+        };
+    };
+    /**
+     * Open a new tab, optionally at a URL, optionally in the background.
+     *
+     * A tab opened here always joins a named group, created if absent and reused
+     * if present in that window, so the tab strip shows plainly which tabs an
+     * automation is working in. Tabs the user already had are never moved into it,
+     * and neither is this one moved between windows: marking what we created is
+     * honest, rearranging someone's browser is not.
+     *
+     * `groupId` is `-1` when grouping did not happen, and `groupTitle` is then the
+     * title that was asked for rather than one any group carries.
+     */
+    openTab: {
+        args: {
+            url?: string;
+            active?: boolean;
+            windowId?: number;
+            groupTitle?: string;
+        };
+        result: {
+            tab: TabInfo;
+            groupId: number;
+            groupTitle: string;
+        };
+    };
+    closeTab: {
+        args: {
+            tabId: number;
+        };
+        result: {
+            closed: number;
+        };
+    };
+    /** The visible text of a page, by tab id. */
+    getPageText: {
+        args: {
+            tabId: number;
+            maxChars?: number;
+        };
+        result: {
+            tabId: number;
+            url: string;
+            title: string;
+            text: string;
+            truncated: boolean;
+        };
+    };
+    /**
+     * The interactive elements of a page, each with a reference to act on.
+     *
+     * Coordinates are deliberately not the interface. A model that clicks at
+     * (412, 233) is guessing, and a page that reflows makes the guess wrong; a
+     * reference resolves to the element that was described.
+     */
+    readPage: {
+        args: {
+            tabId: number;
+            maxElements?: number;
+        };
+        result: {
+            tabId: number;
+            url: string;
+            title: string;
+            elements: ElementRef[];
+            truncated: boolean;
+        };
+    };
+    /** Run JavaScript in the page and return its value. */
+    evaluate: {
+        args: {
+            tabId: number;
+            expression: string;
+            timeoutMs?: number;
+        };
+        result: {
+            tabId: number;
+            value: string;
+            type: string;
+            threw: boolean;
+        };
+    };
+    /** A screenshot, which works on a background tab because it goes through CDP. */
+    screenshot: {
+        args: {
+            tabId: number;
+            format?: 'png' | 'jpeg';
+            quality?: number;
+        };
+        result: {
+            tabId: number;
+            format: string;
+            base64: string;
+            bytes: number;
+        };
+    };
+    /**
+     * Click, by element reference rather than by coordinate.
+     *
+     * `hit` is the only part of this a caller can trust as a statement about the
+     * page. CDP reports that an input event was dispatched and nothing about what
+     * received it, so the element under the point is read at the moment of
+     * dispatch: `self` or `nested` mean the click reaches the named element, and
+     * `covered` means something else was on top and probably took it instead.
+     */
+    click: {
+        args: {
+            tabId: number;
+            ref: string;
+            button?: 'left' | 'right' | 'middle';
+            clickCount?: number;
+        };
+        result: {
+            tabId: number;
+            ref: string;
+            dispatched: true;
+            hit: 'self' | 'nested' | 'covered' | 'nothing';
+            topmost?: string;
+        };
+    };
+    /** Type into whatever holds focus, optionally focusing a reference first. */
+    typeText: {
+        args: {
+            tabId: number;
+            text: string;
+            ref?: string;
+            pressEnter?: boolean;
+        };
+        result: {
+            tabId: number;
+            typed: number;
+        };
+    };
+    pressKey: {
+        args: {
+            tabId: number;
+            key: string;
+            ref?: string;
+        };
+        result: {
+            tabId: number;
+            key: string;
+        };
+    };
+    scroll: {
+        args: {
+            tabId: number;
+            dx?: number;
+            dy?: number;
+            ref?: string;
+        };
+        result: {
+            tabId: number;
+            dx: number;
+            dy: number;
+        };
+    };
+    /** Console messages seen since this tab was first attached to. */
+    consoleMessages: {
+        args: {
+            tabId: number;
+            limit?: number;
+        };
+        result: {
+            tabId: number;
+            messages: ConsoleMessage[];
+            attachedNow: boolean;
+        };
+    };
+    /** Network requests seen since this tab was first attached to. */
+    networkRequests: {
+        args: {
+            tabId: number;
+            limit?: number;
+        };
+        result: {
+            tabId: number;
+            requests: NetworkRequest[];
+            attachedNow: boolean;
+        };
+    };
+    /**
+     * Put tabs in a group, creating or reusing one by title within their window.
+     *
+     * Refused when the named tabs span windows, because a group holds tabs from
+     * one window and honouring it would mean moving the rest.
+     *
+     * Cosmetic only, and that is the point. Nothing here addresses a tab through
+     * its group, so a group can be added, renamed or removed at any time without
+     * anything losing track of anything. The bridge this replaces made the group
+     * load-bearing, which is why losing one stranded every tab inside it.
+     */
+    groupTabs: {
+        args: {
+            tabIds: number[];
+            title?: string;
+            color?: string;
+        };
+        result: {
+            groupId: number;
+            title: string;
+            tabIds: number[];
+        };
+    };
+    /** Take tabs out of whatever group they are in. Leaves the tabs open. */
+    ungroupTabs: {
+        args: {
+            tabIds: number[];
+        };
+        result: {
+            tabIds: number[];
+        };
+    };
+    /** Stop driving a tab: detaches the debugger and drops its buffers. */
+    release: {
+        args: {
+            tabId: number;
+        };
+        result: {
+            tabId: number;
+            released: boolean;
+        };
+    };
+}
+export interface ElementRef {
+    /** Opaque and stable for the life of the snapshot. */
+    ref: string;
+    role: string;
+    name: string;
+    tag: string;
+    value?: string;
+    disabled?: boolean;
+}
+export interface ConsoleMessage {
+    level: string;
+    text: string;
+    url?: string;
+    line?: number;
+    at: number;
+}
+export interface NetworkRequest {
+    method: string;
+    url: string;
+    status?: number;
+    type?: string;
+    at: number;
+}
+export type OperationName = keyof Operations;
+export type ArgsOf<K extends OperationName> = Operations[K]['args'];
+export type ResultOf<K extends OperationName> = Operations[K]['result'];
+/** Host to extension. `id` is the host's, and comes back untouched. */
+export interface Request<K extends OperationName = OperationName> {
+    id: number;
+    op: K;
+    args?: ArgsOf<K>;
+}
+/** Extension to host. */
+export type Response = {
+    id: number;
+    ok: true;
+    data: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/** Host to a socket client. */
+export type SocketReply = {
+    ok: true;
+    data: unknown;
+    protocol: number;
+} | {
+    ok: false;
+    error: string;
+    protocol?: number;
+};
+/** A socket client to the host. One JSON object per line. */
+export interface SocketRequest {
+    op: OperationName;
+    args?: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export declare const isResponse: (value: unknown) => value is Response;

package/dist/protocol.js

@@ -0,0 +1,9 @@
+// The shapes the three processes agree on.
+//
+// One file so the extension, the host and the server cannot drift: a request the
+// server can send is exactly a request the extension knows how to answer, and
+// the compiler is what enforces that rather than a comment asking nicely.
+/** Bumped when a message shape changes in a way an older peer cannot read. */
+export const PROTOCOL = 1;
+export const isResponse = (value) => typeof value === 'object' && value !== null && 'id' in value && 'ok' in value;
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,iFAAiF;AACjF,8EAA8E;AAC9E,0EAA0E;AAE1E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC;AA+N1B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAqB,EAAE,CAC9D,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC"}

package/dist/socket-client.d.ts

@@ -0,0 +1,16 @@
+import { type ArgsOf, type OperationName, type ResultOf } from './protocol.js';
+/** The extension cannot be reached. Never a bug on its own. */
+export declare class ExtensionUnavailable extends Error {
+    readonly name = "ExtensionUnavailable";
+}
+/**
+ * One request over the socket, one reply.
+ *
+ * The host owns request matching, so this only has to write a line and read the
+ * first one back.
+ */
+export declare function ask<K extends OperationName>(op: K, args?: ArgsOf<K>, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<ResultOf<K>>;
+/** Whether the extension answers at all. Used by `status`, never to gate a call. */
+export declare function available(): Promise<boolean>;

package/dist/socket-client.js

@@ -0,0 +1,89 @@
+// Talking to the extension through the host's socket.
+//
+// Every call here is allowed to fail with a reason. The extension is optional
+// infrastructure: it may not be installed, or Chrome may not have started the
+// host yet, and a caller has to be able to tell that apart from a real error.
+import { existsSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { endpointPath } from './socket-path.js';
+import { PROTOCOL, } from './protocol.js';
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** The extension cannot be reached. Never a bug on its own. */
+export class ExtensionUnavailable extends Error {
+    name = 'ExtensionUnavailable';
+}
+const isSocketReply = (value) => typeof value === 'object' && value !== null && 'ok' in value;
+/**
+ * One request over the socket, one reply.
+ *
+ * The host owns request matching, so this only has to write a line and read the
+ * first one back.
+ */
+export function ask(op, args = {}, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    const socketPath = endpointPath();
+    return new Promise((resolve, reject) => {
+        if (process.platform !== 'win32' && !existsSync(socketPath)) {
+            reject(new ExtensionUnavailable('the extension is not connected. Run `yoke install`, then load it in Chrome.'));
+            return;
+        }
+        const socket = createConnection(socketPath);
+        let text = '';
+        let settled = false;
+        const finish = (action) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            socket.destroy();
+            action();
+        };
+        const timer = setTimeout(() => finish(() => reject(new ExtensionUnavailable('the extension did not answer in time'))), timeoutMs + 2_000);
+        socket.on('connect', () => {
+            socket.write(`${JSON.stringify({ op, args, timeoutMs })}\n`);
+        });
+        socket.on('data', (chunk) => {
+            text += chunk.toString('utf8');
+            const cut = text.indexOf('\n');
+            if (cut === -1) {
+                return;
+            }
+            clearTimeout(timer);
+            let reply;
+            try {
+                reply = JSON.parse(text.slice(0, cut));
+            }
+            catch {
+                finish(() => reject(new ExtensionUnavailable('the host sent something unreadable')));
+                return;
+            }
+            if (!isSocketReply(reply)) {
+                finish(() => reject(new ExtensionUnavailable('the host sent an unrecognised reply')));
+                return;
+            }
+            if (reply.protocol !== undefined && reply.protocol !== PROTOCOL) {
+                finish(() => reject(new ExtensionUnavailable(`the host speaks protocol ${reply.protocol} and this build speaks ${PROTOCOL}; update whichever is older`)));
+                return;
+            }
+            if (!reply.ok) {
+                finish(() => reject(new Error(reply.error)));
+                return;
+            }
+            finish(() => resolve(reply.data));
+        });
+        socket.on('error', (failure) => {
+            clearTimeout(timer);
+            finish(() => reject(new ExtensionUnavailable(`the extension is not reachable: ${failure.message}`)));
+        });
+    });
+}
+/** Whether the extension answers at all. Used by `status`, never to gate a call. */
+export async function available() {
+    try {
+        await ask('ping', {}, { timeoutMs: 2_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=socket-client.js.map

package/dist/socket-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-client.js","sourceRoot":"","sources":["../src/socket-client.ts"],"names":[],"mappings":"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"}

package/dist/socket-path.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Kept out of /tmp so another user cannot pre-create it, and out of the
+ * project so it survives a rebuild.
+ */
+export declare function endpointPath(): string;

package/dist/socket-path.js

@@ -0,0 +1,19 @@
+// Where the host listens, in a module with no side effects.
+//
+// Separate from the host itself because the host is an entry point: Chrome
+// executes it and it must always run. Anything that needs only the path should
+// not have to import a file whose job is to start a server.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Kept out of /tmp so another user cannot pre-create it, and out of the
+ * project so it survives a rebuild.
+ */
+export function endpointPath() {
+    if (process.platform === 'win32') {
+        return `\\\\.\\pipe\\yoke-${process.env['USERNAME'] ?? 'user'}`;
+    }
+    const base = process.env['XDG_RUNTIME_DIR'] ?? join(homedir(), '.cache');
+    return join(base, 'yoke', 'extension.sock');
+}
+//# sourceMappingURL=socket-path.js.map

package/dist/socket-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-path.js","sourceRoot":"","sources":["../src/socket-path.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,2EAA2E;AAC3E,+EAA+E;AAC/E,4DAA4D;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,qBAAqB,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,MAAM,EAAE,CAAC;IAClE,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzE,OAAO,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAC9C,CAAC"}