@ericmhalvorsen/aperture 0.2.1

package/dist/mcp-server.js

@@ -0,0 +1,237 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { WebSocket } from "ws";
+import { BROWSER_TOOLS } from "./tools.js";
+export function createApertureMcpServer(sessions, pendingRequests, sharedState) {
+    const server = new Server({ name: "aperture", version: "0.2.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(InitializeRequestSchema, async (request) => {
+        sharedState.mcpInitialized = true;
+        const msg = JSON.stringify({ type: "agent_connected" });
+        for (const session of sessions.values()) {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+            }
+        }
+        return {
+            protocolVersion: request.params.protocolVersion,
+            capabilities: { tools: {} },
+            serverInfo: { name: "aperture", version: "0.2.0" },
+        };
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = Object.entries(BROWSER_TOOLS).map(([name, def]) => ({
+            name,
+            description: def.description,
+            inputSchema: def.inputSchema,
+        }));
+        const addedCustomTools = new Set();
+        for (const session of sessions.values()) {
+            if (session.approved && session.customTools) {
+                for (const ct of session.customTools) {
+                    if (!addedCustomTools.has(ct.name)) {
+                        addedCustomTools.add(ct.name);
+                        tools.push(ct);
+                    }
+                }
+            }
+        }
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const params = request.params;
+        const toolName = params.name;
+        const args = (params.arguments || {});
+        if (toolName === "browser_list_sessions") {
+            const sessionList = Array.from(sessions.entries()).map(([id, s]) => ({
+                sessionId: id,
+                url: s.url,
+                title: s.title,
+                approved: s.approved,
+                lastActiveAt: s.lastActiveAt,
+                capabilities: Array.from(s.capabilities),
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ sessions: sessionList }, null, 2),
+                    },
+                ],
+            };
+        }
+        let isValid = !!BROWSER_TOOLS[toolName];
+        if (!isValid) {
+            for (const session of sessions.values()) {
+                if (session.approved &&
+                    session.customTools?.some((t) => t.name === toolName)) {
+                    isValid = true;
+                    break;
+                }
+            }
+        }
+        if (!toolName || !isValid) {
+            return {
+                content: [{ type: "text", text: `Tool not found: ${toolName}` }],
+                isError: true,
+            };
+        }
+        const sessionId = args.sessionId;
+        if (sessionId) {
+            const session = sessions.get(sessionId);
+            if (!session || session.ws.readyState !== WebSocket.OPEN) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Session not found or closed",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return forwardToolCall(sessions, pendingRequests, session, toolName, args);
+        }
+        const lastActiveSession = getLastActiveSession(sessions);
+        if (lastActiveSession) {
+            return forwardToolCall(sessions, pendingRequests, lastActiveSession, toolName, args);
+        }
+        const approvedCount = Array.from(sessions.values()).filter((s) => s.approved && s.ws.readyState === WebSocket.OPEN).length;
+        if (approvedCount > 1) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Multiple approved browser sessions are connected. Use browser_list_sessions to get sessionIds, then pass sessionId in subsequent tool calls.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const connectedSessions = Array.from(sessions.values()).filter((s) => s.ws.readyState === WebSocket.OPEN);
+        if (connectedSessions.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No browser session connected. Ask the user to enable aperture in their dev session.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const requestId = crypto.randomUUID();
+        for (const s of connectedSessions) {
+            s.ws.send(JSON.stringify({
+                type: "tool_call",
+                requestId,
+                tool: toolName,
+                args,
+            }));
+        }
+        const result = await waitForFirstBrowserResult(pendingRequests, requestId, 60000);
+        if (result) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: typeof result === "string"
+                            ? result
+                            : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Browser session did not respond in time. The user may have dismissed the approval dialog.",
+                },
+            ],
+            isError: true,
+        };
+    });
+    return server;
+}
+async function forwardToolCall(_sessions, pendingRequests, session, toolName, args) {
+    if (toolName === "browser_evaluate" &&
+        !session.capabilities.has("evaluate")) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "browser_evaluate requires explicit approval. Prompt the user to allow JS evaluation.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const requestId = crypto.randomUUID();
+    session.ws.send(JSON.stringify({
+        type: "tool_call",
+        requestId,
+        tool: toolName,
+        args,
+    }));
+    const timeout = toolName === "browser_screenshot" ? 60000 : 15000;
+    const result = await waitForBrowserResult(pendingRequests, requestId, timeout);
+    if (result) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof result === "string"
+                        ? result
+                        : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            { type: "text", text: "Browser session did not respond in time." },
+        ],
+        isError: true,
+    };
+}
+function getLastActiveSession(sessions) {
+    let best;
+    for (const session of sessions.values()) {
+        if (session.approved &&
+            session.ws.readyState === WebSocket.OPEN &&
+            (!best || session.lastActiveAt > best.lastActiveAt)) {
+            best = session;
+        }
+    }
+    return best;
+}
+function waitForBrowserResult(pendingRequests, requestId, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            resolve(null);
+        }, timeoutMs);
+        pendingRequests.set(requestId, (result) => {
+            clearTimeout(timer);
+            pendingRequests.delete(requestId);
+            resolve(result);
+        });
+    });
+}
+function waitForFirstBrowserResult(pendingRequests, requestId, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            resolve(null);
+        }, timeoutMs);
+        let settled = false;
+        pendingRequests.set(requestId, (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            pendingRequests.delete(requestId);
+            resolve(result);
+        });
+    });
+}

package/dist/react.d.ts

@@ -0,0 +1,8 @@
+import type { CustomToolDefinition } from "./client.js";
+interface ApertureProps {
+    port?: number;
+    serverUrl?: string;
+    customTools?: Record<string, CustomToolDefinition>;
+}
+export declare function Aperture({ port, serverUrl, customTools }: ApertureProps): null;
+export {};

package/dist/react.js

@@ -0,0 +1,20 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { initAperture } from "./client.js";
+export function Aperture({ port, serverUrl, customTools }) {
+    const customToolsRef = useRef(customTools);
+    customToolsRef.current = customTools;
+    useEffect(() => {
+        const client = initAperture({
+            port,
+            serverUrl,
+            customTools: customToolsRef.current,
+        });
+        return () => {
+            if (client) {
+                client.disconnect();
+            }
+        };
+    }, [port, serverUrl]);
+    return null;
+}

package/dist/register.d.ts

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

package/dist/register.js

@@ -0,0 +1,2 @@
+import { initAperture } from "./client.js";
+initAperture();

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+export declare class ApertureServer {
+    private wss;
+    private sessions;
+    private pendingRequests;
+    private sharedState;
+    private port;
+    private options;
+    private streamableSessions;
+    private sseSessions;
+    constructor(port?: number, options?: {
+        verbose?: boolean;
+        silentStartup?: boolean;
+        stdio?: boolean;
+    });
+    private handleStreamableHttp;
+    private handleStreamableHttpGet;
+    private handleStreamableHttpDelete;
+    private handleSSEConnection;
+    private handleSSEMessage;
+    private serveClientScript;
+    private setupWSS;
+    private handleBrowserConnection;
+    private handleMCPConnection;
+    private setupStdio;
+}

package/dist/server.js

@@ -0,0 +1,315 @@
+import * as fs from "node:fs/promises";
+import { createServer, } from "node:http";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { randomUUID } from "node:crypto";
+import { WebSocketServer } from "ws";
+import { createApertureMcpServer, } from "./mcp-server.js";
+import { parseJsonRpcBody, SseTransport, WebSocketTransport, writeParseError, } from "./transports.js";
+export class ApertureServer {
+    wss;
+    sessions = new Map();
+    pendingRequests = new Map();
+    sharedState = { mcpInitialized: false };
+    port;
+    options;
+    streamableSessions = new Map();
+    sseSessions = new Map();
+    constructor(port = 3456, options = {}) {
+        this.port = port;
+        this.options = options;
+        const server = createServer(async (req, res) => {
+            res.setHeader("Access-Control-Allow-Origin", "*");
+            res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id, MCP-Protocol-Version, Accept");
+            if (req.method === "OPTIONS") {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            if (req.method === "GET" && req.url === "/sse") {
+                await this.handleSSEConnection(req, res);
+                return;
+            }
+            if (req.method === "POST" && req.url?.startsWith("/messages")) {
+                await this.handleSSEMessage(req, res);
+                return;
+            }
+            if (req.url === "/mcp") {
+                if (req.method === "POST") {
+                    await this.handleStreamableHttp(req, res);
+                    return;
+                }
+                if (req.method === "GET") {
+                    await this.handleStreamableHttpGet(req, res);
+                    return;
+                }
+                if (req.method === "DELETE") {
+                    await this.handleStreamableHttpDelete(req, res);
+                    return;
+                }
+            }
+            if (req.url === "/aperture.js") {
+                await this.serveClientScript(res);
+            }
+            else {
+                res.writeHead(404, { "Content-Type": "text/plain" });
+                res.end("Not Found");
+            }
+        });
+        this.wss = new WebSocketServer({ server, path: "/mcp" });
+        this.setupWSS();
+        if (this.options.stdio) {
+            this.setupStdio();
+        }
+        server.listen(port, "127.0.0.1", () => {
+            if (!this.options.silentStartup) {
+                console.error(`[Aperture] MCP server on http://localhost:${this.port}/mcp`);
+                console.error(`[Aperture] Browser client script: http://localhost:${this.port}/aperture.js`);
+            }
+        });
+    }
+    async handleStreamableHttp(req, res) {
+        const sessionId = req.headers["mcp-session-id"];
+        if (sessionId && this.streamableSessions.has(sessionId)) {
+            const session = this.streamableSessions.get(sessionId);
+            if (session) {
+                await session.transport.handleRequest(req, res);
+                return;
+            }
+        }
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (sid) => {
+                this.streamableSessions.set(sid, { transport, server: mcpServer });
+                console.error(`[Aperture] Streamable HTTP session ${sid.slice(0, 8)} connected`);
+            },
+        });
+        const mcpServer = createApertureMcpServer(this.sessions, this.pendingRequests, this.sharedState);
+        transport.onclose = () => {
+            const sid = transport.sessionId;
+            if (sid && this.streamableSessions.has(sid)) {
+                this.streamableSessions.delete(sid);
+                console.error(`[Aperture] Streamable HTTP session ${sid.slice(0, 8)} disconnected`);
+            }
+            mcpServer.close().catch(() => { });
+        };
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res);
+    }
+    async handleStreamableHttpGet(req, res) {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !this.streamableSessions.has(sessionId)) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid or missing session ID" }));
+            return;
+        }
+        const session = this.streamableSessions.get(sessionId);
+        if (session) {
+            await session.transport.handleRequest(req, res);
+        }
+    }
+    async handleStreamableHttpDelete(req, res) {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !this.streamableSessions.has(sessionId)) {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Session not found" }));
+            return;
+        }
+        const session = this.streamableSessions.get(sessionId);
+        if (session) {
+            await session.transport.handleRequest(req, res);
+            this.streamableSessions.delete(sessionId);
+            await session.server.close();
+            console.error(`[Aperture] Streamable HTTP session ${sessionId.slice(0, 8)} terminated`);
+        }
+    }
+    async handleSSEConnection(req, res) {
+        const transport = new SseTransport(res);
+        const _host = req.headers.host || `localhost:${this.port}`;
+        const messageUrl = `/messages/${transport.sessionId}?sessionId=${transport.sessionId}`;
+        const mcpServer = createApertureMcpServer(this.sessions, this.pendingRequests, this.sharedState);
+        this.sseSessions.set(transport.sessionId, {
+            transport,
+            server: mcpServer,
+            res,
+        });
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache, no-transform",
+            Connection: "keep-alive",
+            "Mcp-Session-Id": transport.sessionId,
+        });
+        res.write(`event: endpoint\ndata: ${messageUrl}\n\n`);
+        try {
+            await mcpServer.connect(transport);
+        }
+        catch (_err) {
+            this.sseSessions.delete(transport.sessionId);
+            mcpServer.close().catch(() => { });
+            res.end();
+            return;
+        }
+        console.error(`[Aperture] SSE session ${transport.sessionId.slice(0, 8)} connected`);
+        const pingInterval = setInterval(() => {
+            res.write(": ping\n\n");
+        }, 30000);
+        res.on("close", () => {
+            clearInterval(pingInterval);
+            this.sseSessions.delete(transport.sessionId);
+            mcpServer.close().catch(() => { });
+            console.error(`[Aperture] SSE session ${transport.sessionId.slice(0, 8)} disconnected`);
+        });
+    }
+    async handleSSEMessage(req, res) {
+        const url = new URL(req.url || "/", `http://localhost:${this.port}`);
+        const headerSessionId = req.headers["mcp-session-id"];
+        const pathParts = url.pathname.split("/");
+        const pathSessionId = pathParts.length > 2 ? pathParts[2] : null;
+        const sessionId = pathSessionId ||
+            url.searchParams.get("sessionId") ||
+            (Array.isArray(headerSessionId) ? headerSessionId[0] : headerSessionId);
+        const session = sessionId ? this.sseSessions.get(sessionId) : undefined;
+        if (!session) {
+            res.writeHead(404, {
+                "Content-Type": "text/plain",
+                "Mcp-Session-Id": sessionId || "",
+            });
+            res.end("Session not found");
+            return;
+        }
+        try {
+            const message = await parseJsonRpcBody(req);
+            session.transport.receiveMessage(message);
+            res.writeHead(202, {
+                "Content-Type": "text/plain",
+                "Mcp-Session-Id": sessionId,
+            });
+            res.end("Accepted");
+        }
+        catch {
+            writeParseError(res);
+        }
+    }
+    async serveClientScript(res) {
+        try {
+            const fileUrl = new URL(import.meta.url);
+            const __dirname = path.dirname(fileURLToPath(fileUrl));
+            const possiblePaths = [
+                path.join(__dirname, "../dist-browser/client.js"),
+                path.join(__dirname, "../../dist-browser/client.js"),
+                path.join(__dirname, "dist-browser/client.js"),
+                path.join(__dirname, "client.ts"),
+                path.join(__dirname, "../src/client.ts"),
+            ];
+            let clientPath = possiblePaths[0];
+            for (const p of possiblePaths) {
+                try {
+                    await fs.access(p);
+                    clientPath = p;
+                    break;
+                }
+                catch { }
+            }
+            const content = await fs.readFile(clientPath, "utf-8");
+            res.writeHead(200, { "Content-Type": "application/javascript" });
+            res.end(content);
+        }
+        catch (err) {
+            console.error("[Aperture] Error loading client script:", err);
+            res.writeHead(500, { "Content-Type": "text/plain" });
+            res.end("Error loading aperture client script");
+        }
+    }
+    setupWSS() {
+        this.wss.on("connection", (ws, req) => {
+            const url = new URL(req.url || "/", "http://localhost");
+            const clientType = url.searchParams.get("type") || "unknown";
+            if (clientType === "browser") {
+                this.handleBrowserConnection(ws, req);
+            }
+            else {
+                this.handleMCPConnection(ws);
+            }
+        });
+    }
+    handleBrowserConnection(ws, _req) {
+        const sessionId = crypto.randomUUID();
+        const session = {
+            ws,
+            url: "",
+            title: "",
+            approved: false,
+            lastActiveAt: Date.now(),
+            capabilities: new Set(),
+            customTools: [],
+        };
+        this.sessions.set(sessionId, session);
+        ws.on("message", (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                if (msg.type === "register") {
+                    session.url = msg.url;
+                    session.title = msg.title;
+                    session.customTools = msg.customTools || [];
+                    console.error(`[Aperture] Session ${sessionId.slice(0, 8)} registered: ${msg.title}`);
+                    ws.send(JSON.stringify({ type: "registered", sessionId }));
+                    if (this.sharedState.mcpInitialized) {
+                        ws.send(JSON.stringify({ type: "agent_connected" }));
+                    }
+                }
+                if (msg.type === "approval") {
+                    session.approved = msg.approved;
+                    session.capabilities = new Set(msg.capabilities || []);
+                    console.error(`[Aperture] Session ${sessionId.slice(0, 8)} ${msg.approved ? "approved" : "denied"}`);
+                }
+                if (msg.type === "focus") {
+                    if (msg.focused) {
+                        session.lastActiveAt = Date.now();
+                    }
+                }
+                if (msg.type === "result") {
+                    const resolvePending = this.pendingRequests.get(msg.requestId);
+                    if (resolvePending) {
+                        resolvePending(msg.result);
+                    }
+                }
+            }
+            catch { }
+        });
+        ws.on("close", () => {
+            this.sessions.delete(sessionId);
+        });
+    }
+    handleMCPConnection(ws) {
+        const transport = new WebSocketTransport(ws);
+        const mcpServer = createApertureMcpServer(this.sessions, this.pendingRequests, this.sharedState);
+        mcpServer.connect(transport).catch((err) => {
+            console.error("[Aperture] MCP connection error:", err.message);
+        });
+        ws.on("close", () => {
+            mcpServer.close().catch(() => { });
+        });
+    }
+    setupStdio() {
+        const transport = new StdioServerTransport();
+        const mcpServer = createApertureMcpServer(this.sessions, this.pendingRequests, this.sharedState);
+        mcpServer.connect(transport).catch((err) => {
+            console.error("[Aperture] Stdio connection error:", err.message);
+        });
+        process.on("SIGINT", () => {
+            mcpServer.close().catch(() => { });
+            process.exit(0);
+        });
+        process.on("SIGTERM", () => {
+            mcpServer.close().catch(() => { });
+            process.exit(0);
+        });
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const port = Number(process.env.APERTURE_PORT) || 3456;
+    new ApertureServer(port);
+}