@webmcp-bridge/local-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 holon-run
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bridge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * This module composes runtime startup with the stdio MCP server into one lifecycle handle.
+ * It depends on site-source resolution, runtime, and server modules so CLI and tests can start a complete local-mcp bridge in one call.
+ */
+import type { Readable, Writable } from "node:stream";
+import { type BrowserEngine } from "./runtime.js";
+import { type BuiltinSite } from "./sites.js";
+export type StartLocalMcpBridgeOptions = {
+    site?: BuiltinSite;
+    adapterModule?: string;
+    moduleBaseDir?: string;
+    url?: string;
+    browser?: BrowserEngine;
+    headless?: boolean;
+    userDataDir?: string;
+    preferNative?: boolean;
+    serviceVersion: string;
+    autoLoginFallback?: boolean;
+    input?: Readable;
+    output?: Writable;
+    onError?: (error: unknown) => void;
+};
+export type LocalMcpBridgeHandle = {
+    site: string;
+    targetUrl: string;
+    mode: "native" | "polyfill" | "adapter-shim";
+    headless: boolean;
+    close: () => Promise<void>;
+};
+export declare function startLocalMcpBridge(options: StartLocalMcpBridgeOptions): Promise<LocalMcpBridgeHandle>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAMtD,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,cAAc,CAAC;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AA+FF,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAyC5G"}

package/dist/bridge.js

@@ -0,0 +1,120 @@
+/**
+ * This module composes runtime startup with the stdio MCP server into one lifecycle handle.
+ * It depends on site-source resolution, runtime, and server modules so CLI and tests can start a complete local-mcp bridge in one call.
+ */
+import { createLocalMcpStdioServer, } from "./server.js";
+import { startLocalMcpRuntime, } from "./runtime.js";
+import { createNativeSiteDefinition, resolveSiteSource, } from "./sites.js";
+function readAuthState(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const state = value.state;
+    if (state === "authenticated" || state === "auth_required" || state === "challenge_required") {
+        return state;
+    }
+    return undefined;
+}
+async function startRuntime(options, siteDefinition, headless) {
+    const runtimeOptions = {
+        siteDefinition,
+        headless,
+    };
+    if (options.url !== undefined) {
+        runtimeOptions.url = options.url;
+    }
+    if (options.browser !== undefined) {
+        runtimeOptions.browser = options.browser;
+    }
+    if (options.userDataDir !== undefined) {
+        runtimeOptions.userDataDir = options.userDataDir;
+    }
+    if (options.preferNative !== undefined) {
+        runtimeOptions.preferNative = options.preferNative;
+    }
+    return await startLocalMcpRuntime(runtimeOptions);
+}
+async function resolveRuntime(options) {
+    const hasAdapterSource = Boolean(options.site || options.adapterModule);
+    let siteDefinition;
+    if (hasAdapterSource) {
+        const sourceOptions = {};
+        if (options.site !== undefined) {
+            sourceOptions.site = options.site;
+        }
+        if (options.adapterModule !== undefined) {
+            sourceOptions.adapterModule = options.adapterModule;
+        }
+        if (options.moduleBaseDir !== undefined) {
+            sourceOptions.moduleBaseDir = options.moduleBaseDir;
+        }
+        siteDefinition = await resolveSiteSource(sourceOptions);
+    }
+    else if (options.url) {
+        siteDefinition = createNativeSiteDefinition(options.url);
+    }
+    else {
+        throw new Error("CONFIG_ERROR: provide --url or one of --site/--adapter-module");
+    }
+    const requestedHeadless = options.headless ?? false;
+    const primary = await startRuntime(options, siteDefinition, requestedHeadless);
+    const autoLoginFallback = options.autoLoginFallback ?? true;
+    const authProbeTool = siteDefinition.manifest.authProbeTool;
+    if (!autoLoginFallback || !requestedHeadless || !authProbeTool) {
+        return primary;
+    }
+    try {
+        const authResult = await primary.gateway.callTool(authProbeTool, {});
+        const state = readAuthState(authResult);
+        if (state !== "auth_required" && state !== "challenge_required") {
+            return primary;
+        }
+    }
+    catch {
+        // Ignore auth probing failures and keep current runtime.
+        return primary;
+    }
+    await primary.close();
+    return await startRuntime(options, siteDefinition, false);
+}
+export async function startLocalMcpBridge(options) {
+    const runtime = await resolveRuntime(options);
+    let server;
+    try {
+        const serverOptions = {
+            gateway: runtime.gateway,
+            serviceVersion: options.serviceVersion,
+        };
+        if (options.input !== undefined) {
+            serverOptions.input = options.input;
+        }
+        if (options.output !== undefined) {
+            serverOptions.output = options.output;
+        }
+        if (options.onError !== undefined) {
+            serverOptions.onError = options.onError;
+        }
+        server = createLocalMcpStdioServer(serverOptions);
+        await server.start();
+    }
+    catch (error) {
+        await runtime.close();
+        throw error;
+    }
+    let closed = false;
+    return {
+        site: runtime.site,
+        targetUrl: runtime.targetUrl,
+        mode: runtime.mode,
+        headless: runtime.headless,
+        close: async () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            await server?.close();
+            await runtime.close();
+        },
+    };
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * This module implements the local-mcp CLI entrypoint for one-site stdio MCP proxy sessions.
+ * It depends on bridge startup APIs so command-line usage reuses the same runtime/server lifecycle.
+ */
+import { type BuiltinSite } from "./sites.js";
+import type { BrowserEngine } from "./runtime.js";
+export type LocalMcpCliOptions = {
+    site?: BuiltinSite;
+    adapterModule?: string;
+    url?: string;
+    browser: BrowserEngine;
+    headless: boolean;
+    autoLoginFallback: boolean;
+    userDataDir?: string;
+    serviceVersion: string;
+};
+export declare function parseCliArgs(args: string[]): LocalMcpCliOptions;
+export declare function runCli(args?: string[]): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG;AAIH,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAsBlD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAUF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,kBAAkB,CA0G/D;AAUD,wBAAsB,MAAM,CAAC,IAAI,WAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmD1E"}

package/dist/cli.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * This module implements the local-mcp CLI entrypoint for one-site stdio MCP proxy sessions.
+ * It depends on bridge startup APIs so command-line usage reuses the same runtime/server lifecycle.
+ */
+import { pathToFileURL } from "node:url";
+import { startLocalMcpBridge } from "./bridge.js";
+import { resolveSiteDefinition } from "./sites.js";
+const USAGE = `Usage:
+  webmcp-local-mcp [--site <site> | --adapter-module <specifier>] [options]
+
+Source:
+  --site <site>                Built-in site id (currently: x, fixture)
+  --adapter-module <specifier> External adapter module (npm package, file path, or file:// URL)
+  If neither source is provided, --url runs in native/polyfill mode without adapter fallback.
+
+Optional:
+  --url <url>                  Target URL (required when no source is set; otherwise overrides adapter default URL)
+  --browser <name>             chromium | firefox | webkit (default: chromium)
+  --headless                   Run browser in headless mode (default: false)
+  --no-headless                Force headed mode
+  --auto-login-fallback        Auto-switch to headed mode when auth is required in headless mode (default: true)
+  --no-auto-login-fallback     Disable auto-switch login fallback
+  --user-data-dir <path>       Playwright persistent profile directory
+  --service-version <value>    MCP server version string (default: 0.1.0)
+  --help                       Show this help message
+`;
+function parseFlagValue(args, index, flag) {
+    const value = args[index + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error(`missing value for ${flag}`);
+    }
+    return value;
+}
+export function parseCliArgs(args) {
+    let site;
+    let adapterModule;
+    let url;
+    let browser = "chromium";
+    let headless = false;
+    let autoLoginFallback = true;
+    let userDataDir;
+    let serviceVersion = "0.1.0";
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--site") {
+            const value = parseFlagValue(args, i, "--site");
+            site = resolveSiteDefinition(value).id;
+            i += 1;
+            continue;
+        }
+        if (arg === "--adapter-module") {
+            adapterModule = parseFlagValue(args, i, "--adapter-module");
+            i += 1;
+            continue;
+        }
+        if (arg === "--url") {
+            url = parseFlagValue(args, i, "--url");
+            i += 1;
+            continue;
+        }
+        if (arg === "--browser") {
+            const value = parseFlagValue(args, i, "--browser");
+            if (value !== "chromium" && value !== "firefox" && value !== "webkit") {
+                throw new Error(`unsupported browser: ${value}`);
+            }
+            browser = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--headless") {
+            headless = true;
+            continue;
+        }
+        if (arg === "--no-headless") {
+            headless = false;
+            continue;
+        }
+        if (arg === "--user-data-dir") {
+            userDataDir = parseFlagValue(args, i, "--user-data-dir");
+            i += 1;
+            continue;
+        }
+        if (arg === "--auto-login-fallback") {
+            autoLoginFallback = true;
+            continue;
+        }
+        if (arg === "--no-auto-login-fallback") {
+            autoLoginFallback = false;
+            continue;
+        }
+        if (arg === "--service-version") {
+            serviceVersion = parseFlagValue(args, i, "--service-version");
+            i += 1;
+            continue;
+        }
+        throw new Error(`unknown argument: ${arg}`);
+    }
+    if (site && adapterModule) {
+        throw new Error("use either --site or --adapter-module, not both");
+    }
+    if (!site && !adapterModule && !url) {
+        throw new Error("missing required --url or one of --site/--adapter-module");
+    }
+    const options = {
+        browser,
+        headless,
+        autoLoginFallback,
+        serviceVersion,
+    };
+    if (site !== undefined) {
+        options.site = site;
+    }
+    if (adapterModule !== undefined) {
+        options.adapterModule = adapterModule;
+    }
+    if (url !== undefined) {
+        options.url = url;
+    }
+    if (userDataDir !== undefined) {
+        options.userDataDir = userDataDir;
+    }
+    return options;
+}
+function isMainModule(metaUrl) {
+    const mainPath = process.argv[1];
+    if (!mainPath) {
+        return false;
+    }
+    return pathToFileURL(mainPath).href === metaUrl;
+}
+export async function runCli(args = process.argv.slice(2)) {
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    let options;
+    try {
+        options = parseCliArgs(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n\n${USAGE}`);
+        return 1;
+    }
+    const handle = await startLocalMcpBridge({
+        ...options,
+        moduleBaseDir: process.cwd(),
+        onError: (error) => {
+            const message = error instanceof Error ? error.stack ?? error.message : String(error);
+            process.stderr.write(`${message}\n`);
+        },
+    });
+    process.stderr.write(`[local-mcp] site=${handle.site} mode=${handle.mode} headless=${String(handle.headless)} url=${handle.targetUrl} transport=stdio\n`);
+    let closing = false;
+    const shutdown = async () => {
+        if (closing) {
+            return;
+        }
+        closing = true;
+        await handle.close();
+    };
+    const signalHandler = (signal) => {
+        void shutdown()
+            .catch((error) => {
+            const message = error instanceof Error ? error.stack ?? error.message : String(error);
+            process.stderr.write(`${message}\n`);
+        })
+            .finally(() => {
+            process.exit(signal === "SIGTERM" ? 0 : 130);
+        });
+    };
+    process.once("SIGINT", signalHandler);
+    process.once("SIGTERM", signalHandler);
+    return 0;
+}
+if (isMainModule(import.meta.url)) {
+    void runCli().then((code) => {
+        if (code !== 0) {
+            process.exit(code);
+        }
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * This module implements a Unix-socket MCP JSON-RPC and SSE client for local MCP servers.
+ * It is depended on by connectors and examples so they can call tools and consume event streams uniformly.
+ */
+import type { JsonValue } from "@webmcp-bridge/core";
+import type { McpJsonRpcRequest, McpJsonRpcResponse, McpSseErrorPayload, McpSseEvent, McpSseMessagePayload, McpToolDefinition } from "./mcp-types.js";
+export declare class LocalMcpHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(options: {
+        status: number;
+        message: string;
+        code?: string;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    });
+}
+export type LocalMcpClientOptions = {
+    socketPath: string;
+};
+export declare class LocalMcpClient {
+    private readonly socketPath;
+    constructor(options: LocalMcpClientOptions);
+    listTools(): Promise<McpToolDefinition[]>;
+    callTool<T extends JsonValue>(name: string, args: Record<string, unknown>): Promise<T>;
+    requestJsonRpc(request: McpJsonRpcRequest): Promise<McpJsonRpcResponse>;
+    consumeEventStream(options: {
+        lastEventId?: string;
+        heartbeatTimeoutMs: number;
+        onEvent: (event: McpSseEvent) => Promise<void> | void;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    parseSseMessagePayload(raw: string): McpSseMessagePayload;
+    parseSseErrorPayload(raw: string): McpSseErrorPayload;
+    private toError;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAEV,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAE1C,OAAO,EAAE;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;CAQF;AAED,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,qBAAqB;IAIpC,SAAS,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAmBzC,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAwBtF,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiDvE,kBAAkB,CAAC,OAAO,EAAE;QAChC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACtD,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmHjB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB;IAIzD,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB;IAIrD,OAAO,CAAC,OAAO;CAmBhB"}