@ericmhalvorsen/aperture 0.2.1

package/dist/tools.d.ts

@@ -0,0 +1,165 @@
+export declare const BROWSER_TOOLS: {
+    readonly browser_dom_query: {
+        readonly description: "Query the DOM using a CSS selector. Returns matched elements with their tag, text content, attributes, and visibility. Always prefer targeted selectors (e.g. '#app h1', '.nav-links a') over broad ones like 'body' or 'html'.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly selector: {
+                    readonly type: "string";
+                    readonly description: "CSS selector (e.g., '#app h1', '.error')";
+                };
+                readonly includeHtml: {
+                    readonly type: "boolean";
+                    readonly default: false;
+                    readonly description: "Include outer HTML for each matched element";
+                };
+            };
+            readonly required: readonly ["selector"];
+        };
+    };
+    readonly browser_network_requests: {
+        readonly description: "Return recent network requests (fetch/XHR) captured by the bridge. Returns an array of request objects with method, URL, status, and timing. Only captures fetch() calls — XHR is not intercepted.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly limit: {
+                    readonly type: "integer";
+                    readonly default: 20;
+                    readonly description: "Max number of requests to return";
+                };
+            };
+        };
+    };
+    readonly browser_page_info: {
+        readonly description: "Get the current state of the page: URL, title, viewport dimensions, scroll position, user agent, and recent console logs. Use this to orient yourself before querying specific elements.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly logLimit: {
+                    readonly type: "integer";
+                    readonly default: 20;
+                    readonly description: "Max number of console log entries to include";
+                };
+                readonly logLevel: {
+                    readonly type: "string";
+                    readonly enum: readonly ["all", "log", "warn", "error", "info"];
+                    readonly default: "all";
+                    readonly description: "Filter console logs by level";
+                };
+            };
+        };
+    };
+    readonly browser_storage_get: {
+        readonly description: "Read values from browser storage. Use type='localStorage' to read localStorage entries (by exact key, prefix, or all). Use type='cookie' to read document cookies (by exact name or all).";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["localStorage", "cookie"];
+                    readonly description: "Storage type to read from";
+                };
+                readonly key: {
+                    readonly type: "string";
+                    readonly description: "Exact key to read from localStorage (localStorage only)";
+                };
+                readonly prefix: {
+                    readonly type: "string";
+                    readonly description: "Key prefix to match in localStorage — returns all keys starting with this string (localStorage only)";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Exact cookie name to retrieve (cookie only). If omitted, returns all cookies.";
+                };
+            };
+            readonly required: readonly ["type"];
+        };
+    };
+    readonly browser_screenshot: {
+        readonly description: "Capture a screenshot of the current viewport as base64 PNG. NOTE: If the user has not yet granted screenshot access for this browser session, an approval modal will appear in the page. Ask the user to click 'Allow' in the dialog before proceeding.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly selector: {
+                    readonly type: "string";
+                    readonly description: "Optional: screenshot a specific element instead of full viewport";
+                };
+            };
+        };
+    };
+    readonly browser_evaluate: {
+        readonly description: "Evaluate JavaScript in the page context and return the result as a string. Objects are JSON-serialized. NOTE: This requires explicit user approval. If not yet approved, a dialog will appear in the page — ask the user to click 'Allow' before proceeding.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly expression: {
+                    readonly type: "string";
+                    readonly description: "JavaScript expression to evaluate";
+                };
+            };
+            readonly required: readonly ["expression"];
+        };
+    };
+    readonly browser_click: {
+        readonly description: "Click an element on the page using a CSS selector. Dispatches the full pointer/mouse event sequence (pointerdown, mousedown, pointerup, mouseup, click) for maximum compatibility with frameworks. Returns success or an error if the element is not found.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly selector: {
+                    readonly type: "string";
+                    readonly description: "CSS selector of the element to click";
+                };
+            };
+            readonly required: readonly ["selector"];
+        };
+    };
+    readonly browser_type: {
+        readonly description: "Type text into an input, textarea, or contenteditable element. Uses native value setters to trigger framework change handlers. Dispatches 'input' and 'change' events after setting the value.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly selector: {
+                    readonly type: "string";
+                    readonly description: "CSS selector of the input element";
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly description: "Text to type";
+                };
+            };
+            readonly required: readonly ["selector", "text"];
+        };
+    };
+    readonly browser_scroll: {
+        readonly description: "Scroll the page or a specific element to a position, or scroll an element into view. Without coordinates, scrolls to the specified x/y offset. With scrollIntoView=true, smoothly scrolls the element into the viewport center.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {
+                readonly selector: {
+                    readonly type: "string";
+                    readonly description: "Optional CSS selector of the element to scroll. If omitted, scrolls the window.";
+                };
+                readonly x: {
+                    readonly type: "integer";
+                    readonly description: "Horizontal scroll position in pixels";
+                };
+                readonly y: {
+                    readonly type: "integer";
+                    readonly description: "Vertical scroll position in pixels";
+                };
+                readonly scrollIntoView: {
+                    readonly type: "boolean";
+                    readonly description: "If true, scrolls the target element into view (requires selector).";
+                };
+            };
+        };
+    };
+    readonly browser_list_sessions: {
+        readonly description: "List all connected browser sessions with metadata (URL, title, approval status). Use this to choose which session to interact with when multiple tabs are connected.";
+        readonly inputSchema: {
+            readonly type: "object";
+            readonly properties: {};
+        };
+    };
+};
+export type BrowserToolName = keyof typeof BROWSER_TOOLS;

package/dist/tools.js

@@ -0,0 +1,161 @@
+export const BROWSER_TOOLS = {
+    browser_dom_query: {
+        description: "Query the DOM using a CSS selector. Returns matched elements with their tag, text content, attributes, and visibility. Always prefer targeted selectors (e.g. '#app h1', '.nav-links a') over broad ones like 'body' or 'html'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                selector: {
+                    type: "string",
+                    description: "CSS selector (e.g., '#app h1', '.error')",
+                },
+                includeHtml: {
+                    type: "boolean",
+                    default: false,
+                    description: "Include outer HTML for each matched element",
+                },
+            },
+            required: ["selector"],
+        },
+    },
+    browser_network_requests: {
+        description: "Return recent network requests (fetch/XHR) captured by the bridge. Returns an array of request objects with method, URL, status, and timing. Only captures fetch() calls — XHR is not intercepted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "integer",
+                    default: 20,
+                    description: "Max number of requests to return",
+                },
+            },
+        },
+    },
+    browser_page_info: {
+        description: "Get the current state of the page: URL, title, viewport dimensions, scroll position, user agent, and recent console logs. Use this to orient yourself before querying specific elements.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                logLimit: {
+                    type: "integer",
+                    default: 20,
+                    description: "Max number of console log entries to include",
+                },
+                logLevel: {
+                    type: "string",
+                    enum: ["all", "log", "warn", "error", "info"],
+                    default: "all",
+                    description: "Filter console logs by level",
+                },
+            },
+        },
+    },
+    browser_storage_get: {
+        description: "Read values from browser storage. Use type='localStorage' to read localStorage entries (by exact key, prefix, or all). Use type='cookie' to read document cookies (by exact name or all).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: ["localStorage", "cookie"],
+                    description: "Storage type to read from",
+                },
+                key: {
+                    type: "string",
+                    description: "Exact key to read from localStorage (localStorage only)",
+                },
+                prefix: {
+                    type: "string",
+                    description: "Key prefix to match in localStorage — returns all keys starting with this string (localStorage only)",
+                },
+                name: {
+                    type: "string",
+                    description: "Exact cookie name to retrieve (cookie only). If omitted, returns all cookies.",
+                },
+            },
+            required: ["type"],
+        },
+    },
+    browser_screenshot: {
+        description: "Capture a screenshot of the current viewport as base64 PNG. NOTE: If the user has not yet granted screenshot access for this browser session, an approval modal will appear in the page. Ask the user to click 'Allow' in the dialog before proceeding.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                selector: {
+                    type: "string",
+                    description: "Optional: screenshot a specific element instead of full viewport",
+                },
+            },
+        },
+    },
+    browser_evaluate: {
+        description: "Evaluate JavaScript in the page context and return the result as a string. Objects are JSON-serialized. NOTE: This requires explicit user approval. If not yet approved, a dialog will appear in the page — ask the user to click 'Allow' before proceeding.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                expression: {
+                    type: "string",
+                    description: "JavaScript expression to evaluate",
+                },
+            },
+            required: ["expression"],
+        },
+    },
+    browser_click: {
+        description: "Click an element on the page using a CSS selector. Dispatches the full pointer/mouse event sequence (pointerdown, mousedown, pointerup, mouseup, click) for maximum compatibility with frameworks. Returns success or an error if the element is not found.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                selector: {
+                    type: "string",
+                    description: "CSS selector of the element to click",
+                },
+            },
+            required: ["selector"],
+        },
+    },
+    browser_type: {
+        description: "Type text into an input, textarea, or contenteditable element. Uses native value setters to trigger framework change handlers. Dispatches 'input' and 'change' events after setting the value.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                selector: {
+                    type: "string",
+                    description: "CSS selector of the input element",
+                },
+                text: { type: "string", description: "Text to type" },
+            },
+            required: ["selector", "text"],
+        },
+    },
+    browser_scroll: {
+        description: "Scroll the page or a specific element to a position, or scroll an element into view. Without coordinates, scrolls to the specified x/y offset. With scrollIntoView=true, smoothly scrolls the element into the viewport center.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                selector: {
+                    type: "string",
+                    description: "Optional CSS selector of the element to scroll. If omitted, scrolls the window.",
+                },
+                x: {
+                    type: "integer",
+                    description: "Horizontal scroll position in pixels",
+                },
+                y: {
+                    type: "integer",
+                    description: "Vertical scroll position in pixels",
+                },
+                scrollIntoView: {
+                    type: "boolean",
+                    description: "If true, scrolls the target element into view (requires selector).",
+                },
+            },
+        },
+    },
+    browser_list_sessions: {
+        description: "List all connected browser sessions with metadata (URL, title, approval status). Use this to choose which session to interact with when multiple tabs are connected.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+};

package/dist/transports.d.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import { WebSocket } from "ws";
+export declare class WebSocketTransport implements Transport {
+    private ws;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    sessionId: string;
+    constructor(ws: WebSocket);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+}
+export declare class SseTransport implements Transport {
+    private res;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    sessionId: string;
+    constructor(res: ServerResponse);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+    receiveMessage(message: JSONRPCMessage): void;
+}
+export declare function parseJsonRpcBody(req: IncomingMessage): Promise<JSONRPCMessage>;
+export declare function writeParseError(res: ServerResponse): void;

package/dist/transports.js

@@ -0,0 +1,86 @@
+import { WebSocket } from "ws";
+export class WebSocketTransport {
+    ws;
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    constructor(ws) {
+        this.ws = ws;
+        this.sessionId = crypto.randomUUID();
+        ws.on("message", (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                this.onmessage?.(msg);
+            }
+            catch (err) {
+                this.onerror?.(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        ws.on("close", () => {
+            this.onclose?.();
+        });
+        ws.on("error", (err) => {
+            this.onerror?.(err);
+        });
+    }
+    async start() { }
+    async send(message) {
+        if (this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(message));
+        }
+    }
+    async close() {
+        this.ws.close();
+    }
+}
+export class SseTransport {
+    res;
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    constructor(res) {
+        this.res = res;
+        this.sessionId = crypto.randomUUID();
+        res.on("close", () => {
+            this.onclose?.();
+        });
+    }
+    async start() { }
+    async send(message) {
+        const data = JSON.stringify(message);
+        this.res.write(`event: message\ndata: ${data}\n\n`);
+    }
+    async close() {
+        this.res.end();
+    }
+    receiveMessage(message) {
+        this.onmessage?.(message);
+    }
+}
+export async function parseJsonRpcBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk;
+        });
+        req.on("end", () => {
+            try {
+                resolve(JSON.parse(body));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        req.on("error", (err) => reject(err));
+    });
+}
+export function writeParseError(res) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error" },
+    }));
+}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export interface ToolMetadata {
+    name: string;
+    description: string;
+    inputSchema: object;
+}
+interface WSRegisterMessage {
+    type: "register";
+    url: string;
+    title: string;
+    customTools?: ToolMetadata[];
+}
+interface WSRegisteredMessage {
+    type: "registered";
+    sessionId: string;
+}
+interface WSAgentConnectedMessage {
+    type: "agent_connected";
+}
+interface WSApprovalMessage {
+    type: "approval";
+    approved: boolean;
+    capabilities?: string[];
+}
+export interface WSToolCallMessage {
+    type: "tool_call";
+    requestId: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+interface WSFocusMessage {
+    type: "focus";
+    focused: boolean;
+}
+interface WSResultMessage {
+    type: "result";
+    requestId: string;
+    result: unknown;
+}
+export type ClientToServerMessage = WSRegisterMessage | WSApprovalMessage | WSFocusMessage | WSResultMessage;
+export type ServerToClientMessage = WSRegisteredMessage | WSAgentConnectedMessage | WSToolCallMessage;
+export interface BrowserSession {
+    ws: import("ws").WebSocket;
+    url: string;
+    title: string;
+    approved: boolean;
+    lastActiveAt: number;
+    capabilities: Set<string>;
+    customTools?: ToolMetadata[];
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};