cdp-mcp 0.2.1 → 0.4.0

package/dist/index.js

@@ -1,402 +0,0 @@
-#!/usr/bin/env node
-import { createServer } from "node:http";
-import { realpathSync } from "node:fs";
-import { pathToFileURL } from "node:url";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { buildServer } from "./server.js";
-import { getSession, sessionState } from "./session/state.js";
-import { log } from "./util/log.js";
-const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
-function isLoopbackHost(host) {
-    return LOOPBACK_HOSTS.has(host);
-}
-function parseArgs(args) {
-    let port;
-    let host = "127.0.0.1";
-    let allowRemote = process.env.CDP_MCP_ALLOW_REMOTE === "1";
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (!arg) {
-            continue;
-        }
-        if (arg === "--help" || arg === "-h") {
-            process.stderr.write([
-                "Usage:",
-                "  cdp-mcp                                  # stdio MCP transport",
-                "  cdp-mcp --port 9719                      # SSE MCP transport on 127.0.0.1:9719",
-                "  cdp-mcp --host 0.0.0.0 --port 9719 --allow-remote",
-                "",
-                "SSE mode caveats:",
-                "  - Single-client only: concurrent /sse connections race on a",
-                "    shared browser session (sessionState is process-global).",
-                "  - Non-loopback bind requires --allow-remote (or",
-                "    CDP_MCP_ALLOW_REMOTE=1). MCP tools include in-page eval and",
-                "    server-filesystem writes; exposing them remotely without",
-                "    further auth is a deliberate operator decision.",
-                "  - Host / Origin headers are validated against the loopback",
-                "    aliases (127.0.0.1, localhost, [::1]) to block",
-                "    DNS-rebinding. On non-loopback binds the operator has",
-                "    accepted exposure via --allow-remote, and we cannot",
-                "    enumerate every reachable hostname/IP, so the checks",
-                "    are skipped — front the server with a reverse proxy if",
-                "    you need per-Host policy.",
-                "",
-            ].join("\n"));
-            process.exit(0);
-        }
-        if (arg === "--port") {
-            const value = args[index + 1];
-            if (!value)
-                throw new Error("--port requires a value");
-            port = parsePort(value);
-            index += 1;
-            continue;
-        }
-        if (arg.startsWith("--port=")) {
-            port = parsePort(arg.slice("--port=".length));
-            continue;
-        }
-        if (arg === "--host") {
-            const value = args[index + 1];
-            if (!value)
-                throw new Error("--host requires a value");
-            host = value;
-            index += 1;
-            continue;
-        }
-        if (arg.startsWith("--host=")) {
-            host = arg.slice("--host=".length);
-            continue;
-        }
-        if (arg === "--allow-remote") {
-            allowRemote = true;
-            continue;
-        }
-        throw new Error(`Unknown argument: ${arg}`);
-    }
-    if (port === undefined) {
-        return { transport: "stdio" };
-    }
-    if (!isLoopbackHost(host) && !allowRemote) {
-        throw new Error(`Refusing to bind SSE transport on non-loopback host '${host}' without --allow-remote (or CDP_MCP_ALLOW_REMOTE=1). MCP tools include in-page eval and server-filesystem writes; remote exposure is opt-in.`);
-    }
-    return {
-        transport: "sse",
-        host,
-        port,
-        allowRemote,
-    };
-}
-function parsePort(raw) {
-    const port = Number(raw);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error(`Invalid --port value: ${raw}`);
-    }
-    return port;
-}
-const DEFAULT_SSE_KEEPALIVE_MS = 25_000;
-// SSE streams sit idle between tool calls, and HTTP clients enforce a
-// body-idle timeout (e.g. undici inside GitHub Copilot CLI tears the stream
-// down after ~12 min with "Body Timeout Error"). A periodic SSE comment frame
-// (`: ...\n\n`) is a no-op per the spec but resets that idle timer. Tunable via
-// CDP_MCP_SSE_KEEPALIVE_MS (non-negative integer ms; 0 disables). See issue #1.
-function getKeepaliveMs() {
-    const raw = process.env.CDP_MCP_SSE_KEEPALIVE_MS;
-    if (raw === undefined || raw === "")
-        return DEFAULT_SSE_KEEPALIVE_MS;
-    const value = Number(raw);
-    if (!Number.isInteger(value) || value < 0) {
-        log.warn("invalid CDP_MCP_SSE_KEEPALIVE_MS; using default", { value: raw, default: DEFAULT_SSE_KEEPALIVE_MS });
-        return DEFAULT_SSE_KEEPALIVE_MS;
-    }
-    return value;
-}
-async function main() {
-    const mode = parseArgs(process.argv.slice(2));
-    if (mode.transport === "sse") {
-        await runSseServer(mode);
-        return;
-    }
-    await runStdioServer();
-}
-async function runStdioServer() {
-    const server = buildServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    log.info("cdp-mcp server started", { pid: process.pid });
-    const shutdown = async (signal) => {
-        log.info(`shutdown signal: ${signal}`);
-        try {
-            const session = getSession();
-            if (session)
-                await sessionState.close();
-        }
-        catch (e) {
-            log.warn("error during shutdown", { error: String(e) });
-        }
-        try {
-            await server.close();
-        }
-        catch (e) {
-            log.warn("error closing server", { error: String(e) });
-        }
-        process.exit(0);
-    };
-    process.on("SIGINT", () => void shutdown("SIGINT"));
-    process.on("SIGTERM", () => void shutdown("SIGTERM"));
-    installProcessErrorHandlers();
-}
-async function runSseServer(mode) {
-    const clients = new Map();
-    // Host/Origin validation is a DNS-rebinding defense — it bites only
-    // on loopback binds, where an attacker page can be tricked into
-    // reaching 127.0.0.1 via a rebound DNS name. On non-loopback binds
-    // the operator has explicitly accepted exposure via --allow-remote,
-    // and we cannot statically enumerate every hostname/IP the host
-    // might be reached by (LAN IP, hostname, mDNS, VPN, …) — so we skip
-    // both checks and treat --allow-remote as the gate.
-    const validateHostOrigin = isLoopbackHost(mode.host);
-    const allowedHosts = validateHostOrigin ? buildAllowedHosts(mode.host, mode.port) : new Set();
-    const allowedOrigins = validateHostOrigin ? buildAllowedOrigins(mode.host, mode.port) : new Set();
-    const httpServer = createServer((req, res) => {
-        void handleSseRequest({
-            req,
-            res,
-            clients,
-            host: mode.host,
-            port: mode.port,
-            validateHostOrigin,
-            allowedHosts,
-            allowedOrigins,
-        });
-    });
-    await listen(httpServer, mode);
-    log.info("cdp-mcp SSE server started", {
-        pid: process.pid,
-        url: `http://${mode.host}:${mode.port}/sse`,
-        allowRemote: mode.allowRemote,
-    });
-    if (!isLoopbackHost(mode.host)) {
-        log.warn("SSE bound to non-loopback host — exposing in-page eval + filesystem-write tools without auth (operator opted in via --allow-remote)", { host: mode.host, port: mode.port });
-    }
-    // Close SSE transports BEFORE the HTTP server: Node's server.close()
-    // waits for in-flight requests to drain, and /sse connections are
-    // long-lived by design — closing the HTTP server first would hang
-    // SIGINT / SIGTERM indefinitely.
-    const shutdown = async (signal) => {
-        log.info(`shutdown signal: ${signal}`);
-        await closeSseClients(clients);
-        await closeHttpServer(httpServer);
-        try {
-            const session = getSession();
-            if (session)
-                await sessionState.close();
-        }
-        catch (e) {
-            log.warn("error during shutdown", { error: String(e) });
-        }
-        process.exit(0);
-    };
-    process.on("SIGINT", () => void shutdown("SIGINT"));
-    process.on("SIGTERM", () => void shutdown("SIGTERM"));
-    installProcessErrorHandlers();
-}
-function installProcessErrorHandlers() {
-    process.on("uncaughtException", (err) => {
-        log.error("uncaughtException", { error: String(err), stack: err.stack });
-    });
-    process.on("unhandledRejection", (reason) => {
-        log.error("unhandledRejection", { reason: String(reason) });
-    });
-}
-export async function handleSseRequest({ req, res, clients, host, port, validateHostOrigin, allowedHosts, allowedOrigins, }) {
-    try {
-        // DNS-rebinding defense for loopback binds: validate Host (and
-        // Origin if present) before the SDK touches the request. The MCP
-        // SDK's SSEServerTransport does not gate either header by default.
-        // Skipped on non-loopback binds — see runSseServer for rationale.
-        if (validateHostOrigin) {
-            const headerHost = req.headers.host;
-            if (!headerHost || !allowedHosts.has(headerHost)) {
-                log.warn("rejecting SSE request with disallowed Host header", {
-                    host: headerHost,
-                    bindHost: host,
-                });
-                respondText(res, 403, "forbidden\n");
-                return;
-            }
-            // Origin is only sent by browsers (and is `null` for sandboxed
-            // iframes / file://). Checking it when present is the
-            // cross-origin defense layer; the Host check above is what
-            // catches non-browser callers and Origin-omitting browsers.
-            const originHeader = req.headers.origin;
-            if (originHeader && !allowedOrigins.has(originHeader)) {
-                log.warn("rejecting SSE request with disallowed Origin header", { origin: originHeader });
-                respondText(res, 403, "forbidden\n");
-                return;
-            }
-        }
-        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? `${host}:${port}`}`);
-        if (req.method === "GET" && url.pathname === "/sse") {
-            await startSseConnection({ res, clients });
-            return;
-        }
-        if (req.method === "POST" && url.pathname === "/messages") {
-            await handleSseMessage({ req, res, clients, sessionId: url.searchParams.get("sessionId") });
-            return;
-        }
-        respondText(res, 404, "not found\n");
-    }
-    catch (e) {
-        log.error("SSE request failed", { error: String(e) });
-        if (!res.headersSent) {
-            respondText(res, 500, "internal server error\n");
-        }
-        else {
-            res.end();
-        }
-    }
-}
-// Called only on loopback binds (see runSseServer). The set covers the
-// three loopback aliases a browser or CLI might use to reach a 127.0.0.1
-// / localhost / ::1 server; anything else implies DNS-rebinding.
-function buildAllowedHosts(bindHost, port) {
-    const hosts = new Set([
-        `${bindHost}:${port}`,
-        `127.0.0.1:${port}`,
-        `localhost:${port}`,
-        `[::1]:${port}`,
-    ]);
-    return hosts;
-}
-function buildAllowedOrigins(bindHost, port) {
-    const origins = new Set();
-    for (const hostPort of buildAllowedHosts(bindHost, port)) {
-        origins.add(`http://${hostPort}`);
-        origins.add(`https://${hostPort}`);
-    }
-    return origins;
-}
-async function startSseConnection({ res, clients, }) {
-    const transport = new SSEServerTransport("/messages", res);
-    const server = buildServer();
-    // Assigned after connect() (below) so the keepalive never writes before the
-    // SDK has sent the SSE response headers; cleared here on disconnect.
-    let keepalive;
-    transport.onclose = () => {
-        if (keepalive)
-            clearInterval(keepalive);
-        const client = clients.get(transport.sessionId);
-        clients.delete(transport.sessionId);
-        void client?.server.close().catch((e) => {
-            log.warn("error closing MCP server for SSE client", { sessionId: transport.sessionId, error: String(e) });
-        });
-    };
-    transport.onerror = (e) => {
-        log.warn("SSE transport error", { sessionId: transport.sessionId, error: String(e) });
-    };
-    clients.set(transport.sessionId, { server, transport });
-    await server.connect(transport);
-    // connect() has now written the SSE headers + endpoint event, so it's safe
-    // to interleave keepalive comment frames on the stream.
-    const keepaliveMs = getKeepaliveMs();
-    if (keepaliveMs > 0) {
-        keepalive = setInterval(() => {
-            if (res.writableEnded)
-                return;
-            try {
-                res.write(": keepalive\n\n");
-            }
-            catch (e) {
-                log.warn("SSE keepalive write failed", { sessionId: transport.sessionId, error: String(e) });
-            }
-        }, keepaliveMs);
-        // Don't let the keepalive timer alone keep the process alive.
-        keepalive.unref();
-    }
-    log.info("SSE client connected", { sessionId: transport.sessionId });
-}
-async function handleSseMessage({ req, res, clients, sessionId, }) {
-    if (!sessionId) {
-        respondText(res, 400, "missing sessionId\n");
-        return;
-    }
-    const client = clients.get(sessionId);
-    if (!client) {
-        respondText(res, 404, "unknown sessionId\n");
-        return;
-    }
-    await client.transport.handlePostMessage(req, res);
-}
-async function listen(server, mode) {
-    await new Promise((resolve, reject) => {
-        const onError = (e) => {
-            server.off("listening", onListening);
-            reject(e);
-        };
-        const onListening = () => {
-            server.off("error", onError);
-            resolve();
-        };
-        server.once("error", onError);
-        server.once("listening", onListening);
-        server.listen(mode.port, mode.host);
-    });
-}
-async function closeHttpServer(server) {
-    await new Promise((resolve, reject) => {
-        server.close((e) => {
-            if (e) {
-                reject(e);
-                return;
-            }
-            resolve();
-        });
-    }).catch((e) => {
-        log.warn("error closing HTTP server", { error: String(e) });
-    });
-}
-async function closeSseClients(clients) {
-    const entries = [...clients.entries()];
-    clients.clear();
-    await Promise.all(entries.map(async ([sessionId, client]) => {
-        try {
-            await client.transport.close();
-        }
-        catch (e) {
-            log.warn("error closing SSE transport", { sessionId, error: String(e) });
-        }
-        try {
-            await client.server.close();
-        }
-        catch (e) {
-            log.warn("error closing MCP server", { sessionId, error: String(e) });
-        }
-    }));
-}
-function respondText(res, statusCode, body) {
-    res.writeHead(statusCode, { "Content-Type": "text/plain; charset=utf-8" });
-    res.end(body);
-}
-// Only run the server when executed as the CLI entry point — not when this
-// module is imported (e.g. by the SSE transport tests). `realpathSync`
-// resolves the npm bin symlink so the comparison holds for global installs.
-function isRunAsMain() {
-    const entry = process.argv[1];
-    if (!entry)
-        return false;
-    try {
-        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
-    }
-    catch {
-        return false;
-    }
-}
-if (isRunAsMain()) {
-    main().catch((err) => {
-        log.error("fatal", { error: String(err), stack: err?.stack });
-        process.exit(1);
-    });
-}
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/locator.d.ts

@@ -1,108 +0,0 @@
-/**
- * Canonical `LocatorSpec` contract for cdp-mcp.
- *
- * This module is the single source of truth for the structured element-locator
- * shape that `locate`, `wait_for`, and the form-driving tools accept. It is
- * deliberately **side-effect free** and depends only on `zod`, so external
- * consumers can import it (via `cdp-mcp/contract`) to produce and validate specs
- * without pulling in the CLI/server. Tool code re-imports these symbols rather
- * than redefining them, so the published contract can never silently drift from
- * what the tools actually accept.
- */
-import { z } from "zod";
-/**
- * Error thrown by {@link normalizeLocator} / {@link parseLocator} for an invalid
- * spec. `code` mirrors the cdp-mcp tool error codes so tool handlers can re-wrap it
- * structurally: `"missing_arg"` when a spec is under-specified for its strategy,
- * `"invalid_locator"` for an unsupported strategy.
- */
-export declare class LocatorError extends Error {
-    readonly code: string;
-    constructor(message: string, code?: string);
-}
-/** The locator strategies cdp-mcp understands. `css` is the default when a selector is given. */
-export declare const locatorBySchema: z.ZodEnum<["css", "text", "role", "test_id", "testId", "label", "placeholder", "name"]>;
-/**
- * The raw Zod shape for a LocatorSpec. Spread into tool input schemas
- * (`{ ...locatorShape, ... }`) so the field docs stay identical everywhere.
- */
-export declare const locatorShape: {
-    by: z.ZodOptional<z.ZodEnum<["css", "text", "role", "test_id", "testId", "label", "placeholder", "name"]>>;
-    selector: z.ZodOptional<z.ZodString>;
-    css: z.ZodOptional<z.ZodString>;
-    text: z.ZodOptional<z.ZodString>;
-    role: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString>;
-    test_id: z.ZodOptional<z.ZodString>;
-    testId: z.ZodOptional<z.ZodString>;
-    label: z.ZodOptional<z.ZodString>;
-    placeholder: z.ZodOptional<z.ZodString>;
-    exact: z.ZodOptional<z.ZodBoolean>;
-};
-/** A standalone `ZodObject` for a LocatorSpec — external consumers can `.parse()`/`.safeParse()`. */
-export declare const locatorSchema: z.ZodObject<{
-    by: z.ZodOptional<z.ZodEnum<["css", "text", "role", "test_id", "testId", "label", "placeholder", "name"]>>;
-    selector: z.ZodOptional<z.ZodString>;
-    css: z.ZodOptional<z.ZodString>;
-    text: z.ZodOptional<z.ZodString>;
-    role: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString>;
-    test_id: z.ZodOptional<z.ZodString>;
-    testId: z.ZodOptional<z.ZodString>;
-    label: z.ZodOptional<z.ZodString>;
-    placeholder: z.ZodOptional<z.ZodString>;
-    exact: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    css?: string | undefined;
-    text?: string | undefined;
-    role?: string | undefined;
-    test_id?: string | undefined;
-    testId?: string | undefined;
-    label?: string | undefined;
-    placeholder?: string | undefined;
-    name?: string | undefined;
-    exact?: boolean | undefined;
-    by?: "css" | "text" | "role" | "test_id" | "testId" | "label" | "placeholder" | "name" | undefined;
-    selector?: string | undefined;
-}, {
-    css?: string | undefined;
-    text?: string | undefined;
-    role?: string | undefined;
-    test_id?: string | undefined;
-    testId?: string | undefined;
-    label?: string | undefined;
-    placeholder?: string | undefined;
-    name?: string | undefined;
-    exact?: boolean | undefined;
-    by?: "css" | "text" | "role" | "test_id" | "testId" | "label" | "placeholder" | "name" | undefined;
-    selector?: string | undefined;
-}>;
-export type LocatorBy = z.infer<typeof locatorBySchema>;
-export interface LocatorSpec {
-    by?: LocatorBy;
-    selector?: string;
-    css?: string;
-    text?: string;
-    role?: string;
-    name?: string;
-    test_id?: string;
-    testId?: string;
-    label?: string;
-    placeholder?: string;
-    exact?: boolean;
-}
-/**
- * Validate and canonicalize a spec: infer `by` from selector/css, enforce the
- * required field for the chosen strategy, and fold the `name` fallback into the
- * strategy-specific field. Throws {@link LocatorError} on an under-specified spec.
- */
-export declare function normalizeLocator(input: LocatorSpec): LocatorSpec;
-/** Validate an unknown value as a LocatorSpec (shape + strategy requirements). */
-export declare function parseLocator(input: unknown): LocatorSpec;
-/**
- * Serialize a LocatorSpec to a stable, normalized JSON string. Equivalent specs
- * serialize identically regardless of which alias the caller used — e.g.
- * `{ css: ".x" }` and `{ selector: ".x" }` both yield `{"by":"css","selector":".x"}`
- * — so the output is safe to use as a cache key or for equality checks.
- */
-export declare function serializeLocator(spec: LocatorSpec): string;