@harness-fe/mcp-server 3.0.1

package/src/cli.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * CLI entry — boots WS bridge + MCP server (stdio or HTTP).
+ *
+ * Usage:
+ *   npx @harness-fe/mcp-server                # 127.0.0.1, stdio MCP
+ *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto
+ *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto --mcp-transport http
+ *
+ * Leader / follower:
+ *   - first process bound to the WS port = leader (in-process Bridge)
+ *   - subsequent processes (EADDRINUSE) become followers that attach to
+ *     the leader via the `mcp.call` control channel using `RemoteBridge`.
+ *
+ * This lets multiple Claude Code windows share a single dev-bridge daemon
+ * (and thus the same browser / vite-plugin connections).
+ */
+
+import { randomBytes } from 'node:crypto';
+import {
+    DEFAULT_HOST,
+    DEFAULT_WS_PORT,
+    buildHttpUrl,
+    isLoopbackHost,
+    parseWsUrl,
+} from '@harness-fe/protocol';
+import { Bridge, defaultDataDir, type IBridge } from './bridge.js';
+import { RemoteBridge } from './remoteBridge.js';
+import { startMcpStdioServer } from './mcp.js';
+import { startMcpHttpServer } from './mcpHttp.js';
+
+type McpTransport = 'stdio' | 'http';
+
+interface CliConfig {
+    host: string;
+    port: number;
+    token: string | undefined;
+    mcpTransport: McpTransport;
+    mcpPath: string;
+    publicHost: string | undefined;
+    /** Friendly daemon name; surfaces in banner / dashboard. Cosmetic only. */
+    label: string | undefined;
+    /** Resolved data directory. Defaults to defaultDataDir(port). */
+    dataDir: string;
+}
+
+function printHelpAndExit(): never {
+    const help = `harness-fe — frontend harness MCP daemon
+
+Usage:
+  harness-fe [options]
+
+Options:
+  --host <addr>          Bind address. Default 127.0.0.1.
+                         Use 0.0.0.0 to accept LAN connections (requires --token).
+  --port <number>        TCP port. Default ${DEFAULT_WS_PORT}.
+  --token <value|auto>   Token required for HTTP/WS auth. Pass "auto" to generate one.
+                         Required when --host is not loopback.
+  --mcp-transport <kind> stdio (default) or http. http mounts /mcp on the bridge.
+  --mcp-path <path>      URL path for the MCP HTTP endpoint. Default /mcp.
+  --public-host <addr>   Override the host printed in outbound URLs. Useful when
+                         binding 0.0.0.0 and the auto-detected LAN IP is wrong.
+  -h, --help             Show this help.
+
+Environment:
+  HARNESS_FE_HOST           Same as --host
+  HARNESS_FE_TOKEN          Same as --token (use "auto" to generate)
+  HARNESS_FE_MCP_TRANSPORT  Same as --mcp-transport
+  HARNESS_FE_MCP_PATH       Same as --mcp-path
+  HARNESS_FE_URL            Full ws:// URL (legacy; --host/--port override it)
+`;
+    process.stderr.write(help);
+    process.exit(0);
+}
+
+function parseArgs(argv: string[]): CliConfig {
+    const args = argv.slice(2);
+
+    let host: string | undefined;
+    let port: number | undefined;
+    let token: string | undefined;
+    let mcpTransport: McpTransport | undefined;
+    let mcpPath: string | undefined;
+    let publicHost: string | undefined;
+
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const next = () => {
+            const v = args[++i];
+            if (v == null) {
+                process.stderr.write(`harness-fe: missing value for ${a}\n`);
+                process.exit(2);
+            }
+            return v;
+        };
+        switch (a) {
+            case '-h':
+            case '--help':
+                printHelpAndExit();
+                break;
+            case '--host':
+                host = next();
+                break;
+            case '--port':
+                port = Number(next());
+                if (!Number.isFinite(port) || port <= 0) {
+                    process.stderr.write(`harness-fe: invalid --port\n`);
+                    process.exit(2);
+                }
+                break;
+            case '--token':
+                token = next();
+                break;
+            case '--mcp-transport': {
+                const v = next();
+                if (v !== 'stdio' && v !== 'http') {
+                    process.stderr.write(`harness-fe: invalid --mcp-transport (stdio|http)\n`);
+                    process.exit(2);
+                }
+                mcpTransport = v;
+                break;
+            }
+            case '--mcp-path':
+                mcpPath = next();
+                break;
+            case '--public-host':
+                publicHost = next();
+                break;
+            default:
+                process.stderr.write(`harness-fe: unknown argument ${a}\n`);
+                process.exit(2);
+        }
+    }
+
+    // Apply env fallbacks, then URL fallback for host/port.
+    const envUrl = process.env.HARNESS_FE_URL;
+    let envHost: string | undefined;
+    let envPort: number | undefined;
+    if (envUrl) {
+        try {
+            const parsed = parseWsUrl(envUrl);
+            envHost = parsed.host;
+            envPort = parsed.port;
+        } catch {
+            // ignore — fall back to defaults below
+        }
+    }
+
+    const finalHost = host ?? process.env.HARNESS_FE_HOST ?? envHost ?? DEFAULT_HOST;
+    const finalPort = port ?? envPort ?? DEFAULT_WS_PORT;
+
+    let finalToken = token ?? process.env.HARNESS_FE_TOKEN;
+    if (finalToken === 'auto') {
+        finalToken = randomBytes(24).toString('base64url');
+    }
+    if (finalToken === '') finalToken = undefined;
+
+    const finalTransport: McpTransport =
+        (mcpTransport ?? (process.env.HARNESS_FE_MCP_TRANSPORT as McpTransport | undefined)) ??
+        'stdio';
+    if (finalTransport !== 'stdio' && finalTransport !== 'http') {
+        process.stderr.write(`harness-fe: invalid mcp transport "${finalTransport}"\n`);
+        process.exit(2);
+    }
+    const finalMcpPath = mcpPath ?? process.env.HARNESS_FE_MCP_PATH ?? '/mcp';
+
+    // Data dir defaults to port-keyed path. Explicit env override wins.
+    const finalDataDir = process.env.HARNESS_FE_DATA_DIR ?? defaultDataDir(finalPort);
+
+    const finalLabel = process.env.HARNESS_FE_LABEL || undefined;
+
+    return {
+        host: finalHost,
+        port: finalPort,
+        token: finalToken,
+        mcpTransport: finalTransport,
+        mcpPath: finalMcpPath,
+        publicHost,
+        label: finalLabel,
+        dataDir: finalDataDir,
+    };
+}
+
+function validate(_cfg: CliConfig): void {
+    // Token requirement is left entirely to the operator. We don't refuse
+    // a non-loopback bind without a token — that's their call, not ours.
+    // Warnings are emitted from the banner so the operator sees them; CI /
+    // automation that pipes stderr can suppress as needed.
+}
+
+function printBanner(cfg: CliConfig, role: 'leader' | 'follower', viewerUrl: string | undefined): void {
+    const lines: string[] = [];
+    const labelSuffix = cfg.label ? `  (${cfg.label})` : '';
+    lines.push(`[harness-fe] ${role}: WS bridge listening on ws://${cfg.host}:${cfg.port}${labelSuffix}`);
+    if (role === 'leader') {
+        // Surface the data dir so the user can see exactly where this
+        // daemon's sessions / recordings / projects are landing.
+        lines.push(`[harness-fe] data:   ${cfg.dataDir}`);
+    }
+    const isLan = !isLoopbackHost(cfg.host);
+    if (isLan) {
+        lines.push(`[harness-fe] WARNING: bound to non-loopback host ${cfg.host}.`);
+        if (cfg.token) {
+            lines.push(`[harness-fe]   anyone reaching this host:port with the token can read console / network / recordings.`);
+        } else {
+            lines.push(`[harness-fe]   no token set — anyone on this network can read console / network / recordings.`);
+            lines.push(`[harness-fe]   add --token auto (or HARNESS_FE_TOKEN=…) to enable auth.`);
+        }
+    }
+    // Always print the dashboard URL. The token (when present) is folded
+    // into the query so the first hit hands it off to a cookie; without a
+    // token, auth is disabled and the URL works on its own.
+    const host = cfg.publicHost ?? viewerHost(viewerUrl) ?? cfg.host;
+    const dashboard = buildHttpUrl({ host, port: cfg.port, token: cfg.token });
+    lines.push(`[harness-fe] dashboard: ${dashboard}`);
+    if (cfg.mcpTransport === 'http') {
+        const mcp = buildHttpUrl({ host, port: cfg.port, token: cfg.token, path: cfg.mcpPath });
+        lines.push(`[harness-fe] mcp http:  ${mcp}`);
+        if (cfg.token) {
+            const mcpNoTok = buildHttpUrl({ host, port: cfg.port, path: cfg.mcpPath });
+            lines.push(
+                `[harness-fe]   agent config: { "url": "${mcpNoTok}", "headers": { "Authorization": "Bearer ${cfg.token}" } }`,
+            );
+        } else {
+            lines.push(`[harness-fe]   agent config: { "url": "${mcp}" }   (no auth — token unset)`);
+        }
+    }
+    if (cfg.token) {
+        lines.push(`[harness-fe] token:     ${cfg.token}`);
+    }
+    process.stderr.write(lines.join('\n') + '\n');
+}
+
+function viewerHost(viewerUrl: string | undefined): string | undefined {
+    if (!viewerUrl) return undefined;
+    try {
+        return new URL(viewerUrl).hostname;
+    } catch {
+        return undefined;
+    }
+}
+
+async function main() {
+    const cfg = parseArgs(process.argv);
+    validate(cfg);
+
+    const { active, shutdown, role } = await startBridgeOrAttach(cfg);
+    printBanner(cfg, role, active.getViewerBaseUrl());
+
+    let mcpShutdown: (() => Promise<void>) | undefined;
+    if (cfg.mcpTransport === 'stdio') {
+        await startMcpStdioServer(active);
+        process.stderr.write('[harness-fe] MCP stdio server connected\n');
+    } else {
+        if (role === 'follower') {
+            process.stderr.write(
+                '[harness-fe] --mcp-transport=http is only supported on the leader. ' +
+                    'Another daemon already holds the port; stop it first.\n',
+            );
+            await shutdown();
+            process.exit(2);
+        }
+        const handle = await startMcpHttpServer(active, { path: cfg.mcpPath });
+        process.stderr.write(`[harness-fe] MCP http server mounted at ${handle.path}\n`);
+        mcpShutdown = () => handle.close();
+    }
+
+    const onSignal = async () => {
+        process.stderr.write('[harness-fe] shutting down\n');
+        if (mcpShutdown) {
+            try { await mcpShutdown(); } catch { /* swallow */ }
+        }
+        await shutdown();
+        process.exit(0);
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+}
+
+async function startBridgeOrAttach(
+    cfg: CliConfig,
+): Promise<{ active: IBridge; shutdown: () => Promise<void>; role: 'leader' | 'follower' }> {
+    const bridge = new Bridge({
+        port: cfg.port,
+        host: cfg.host,
+        dataDir: cfg.dataDir,
+        label: cfg.label,
+        auth: cfg.token ? { token: cfg.token } : undefined,
+        publicHost: cfg.publicHost,
+    });
+    try {
+        await bridge.start();
+        return {
+            active: bridge,
+            shutdown: () => bridge.stop(),
+            role: 'leader',
+        };
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException)?.code !== 'EADDRINUSE') throw err;
+    }
+
+    // Port already taken — attach as follower.
+    const remote = new RemoteBridge({ port: cfg.port, host: cfg.host, token: cfg.token });
+    await remote.connect();
+    return {
+        active: remote,
+        shutdown: () => remote.stop(),
+        role: 'follower',
+    };
+}
+
+main().catch((err) => {
+    process.stderr.write(`[harness-fe] fatal: ${err?.stack ?? err}\n`);
+    process.exit(1);
+});

package/src/daemon.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { IncomingMessage } from 'node:http';
+import { createDaemon } from './daemon.js';
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+    while (cleanups.length) {
+        const fn = cleanups.shift();
+        if (fn) await fn();
+    }
+});
+
+function freshDataDir(): string {
+    const dir = mkdtempSync(join(tmpdir(), 'harness-daemon-test-'));
+    cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+    return dir;
+}
+
+describe('createDaemon', () => {
+    it('boots a bridge on an ephemeral port and serves /mcp', async () => {
+        const daemon = createDaemon({
+            port: 0,
+            host: '127.0.0.1',
+            dataDir: freshDataDir(),
+        });
+        cleanups.push(() => daemon.stop());
+
+        await daemon.start();
+        const port = daemon.getBoundPort();
+        expect(port).toBeGreaterThan(0);
+        expect(daemon.mcpPath).toBe('/mcp');
+
+        // Anything not /mcp falls through to the bridge's 404.
+        const res = await fetch(`http://127.0.0.1:${port}/nothing-here`);
+        expect(res.status).toBe(404);
+
+        // /mcp is mounted (returns something other than the bridge 404 body).
+        const mcp = await fetch(`http://127.0.0.1:${port}/mcp`);
+        const body = await mcp.text();
+        expect(body).not.toBe('Not Found');
+    });
+
+    it('start is idempotent and stop is idempotent', async () => {
+        const daemon = createDaemon({
+            port: 0,
+            host: '127.0.0.1',
+            dataDir: freshDataDir(),
+        });
+        cleanups.push(() => daemon.stop());
+
+        await daemon.start();
+        await daemon.start(); // second call no-ops
+        const port = daemon.getBoundPort();
+        expect(port).toBeGreaterThan(0);
+
+        await daemon.stop();
+        await daemon.stop(); // second call no-ops
+    });
+
+    it('invokes a custom authorize on every request and rejects on false', async () => {
+        const authorize = vi.fn<(req: IncomingMessage) => boolean>(
+            (req) => req.headers.authorization === 'Bearer good',
+        );
+
+        const daemon = createDaemon({
+            port: 0,
+            host: '127.0.0.1',
+            dataDir: freshDataDir(),
+            authorize,
+        });
+        cleanups.push(() => daemon.stop());
+        await daemon.start();
+
+        const port = daemon.getBoundPort()!;
+        const denied = await fetch(`http://127.0.0.1:${port}/mcp`);
+        expect(denied.status).toBe(401);
+
+        const allowed = await fetch(`http://127.0.0.1:${port}/mcp`, {
+            headers: { authorization: 'Bearer good' },
+        });
+        expect(allowed.status).not.toBe(401);
+
+        // Auth was consulted at least twice (denied + allowed). Other internal
+        // routes may also have hit it during startup; we don't assert an
+        // exact count — only that the predicate is on the hot path.
+        expect(authorize.mock.calls.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('exposes the underlying Bridge as a tested escape hatch', async () => {
+        const daemon = createDaemon({
+            port: 0,
+            host: '127.0.0.1',
+            dataDir: freshDataDir(),
+        });
+        cleanups.push(() => daemon.stop());
+        await daemon.start();
+
+        expect(daemon.bridge).toBeDefined();
+        expect(daemon.bridge.getBoundPort()).toBe(daemon.getBoundPort());
+    });
+
+    it('honours a custom mcpPath', async () => {
+        const daemon = createDaemon({
+            port: 0,
+            host: '127.0.0.1',
+            dataDir: freshDataDir(),
+            mcpPath: '/custom-mcp',
+        });
+        cleanups.push(() => daemon.stop());
+        await daemon.start();
+        expect(daemon.mcpPath).toBe('/custom-mcp');
+
+        const port = daemon.getBoundPort()!;
+        const res = await fetch(`http://127.0.0.1:${port}/custom-mcp`);
+        // 404 would mean the path wasn't mounted (bridge default). Anything
+        // else means the MCP transport responded.
+        expect(await res.text()).not.toBe('Not Found');
+    });
+});

package/src/daemon.ts

@@ -0,0 +1,161 @@
+/**
+ * `createDaemon` — programmatic entry point for embedding the harness-fe
+ * daemon inside another Node.js process. Wraps `Bridge` construction +
+ * `startMcpHttpServer` so a host application can boot the daemon with
+ * `import { createDaemon } from '@harness-fe/mcp-server'` instead of
+ * spawning the CLI as a sidecar.
+ *
+ * Scope (v1):
+ *   - Factory mode only — the daemon owns its own HTTP listener on a
+ *     caller-chosen port. Attaching to a host's existing `http.Server`
+ *     (middleware / handle modes) is a follow-up that requires Bridge
+ *     surgery; tracked separately.
+ *   - Resumable SSE — pass through `eventStore` (defaults to
+ *     `MemoryEventStore`; `null` disables resumability).
+ *   - Custom auth — pass `authorize: (req) => boolean` to replace the
+ *     built-in token check. The CLI translates `--token` into one of
+ *     these so the daemon itself has exactly one auth pipeline.
+ *
+ * Standalone CLI use is unchanged: `cli.ts` is a thin caller of this
+ * factory. Anything the CLI does that's specific to a developer's
+ * machine (port-keyed `defaultDataDir`, `HARNESS_FE_*` env, leader /
+ * follower attachment, banner, signal handlers) stays in `cli.ts` —
+ * not pushed into the factory.
+ */
+
+import type { IncomingMessage } from 'node:http';
+
+import { Bridge } from './bridge.js';
+import { startMcpHttpServer } from './mcpHttp.js';
+import type { EventStore, IStore } from './store/types.js';
+import type { ITaskStore, IMemoryStore } from './store/types.js';
+
+export interface DaemonOptions {
+    /** TCP port to listen on. Default `DEFAULT_WS_PORT` (see protocol). */
+    port?: number;
+    /** Bind address. Default `127.0.0.1` (loopback only). */
+    host?: string;
+    /**
+     * Override the host used when building outbound URLs (dashboard, replay
+     * viewer). Useful when binding `0.0.0.0` and the auto-detected LAN IP is
+     * wrong, or when the host application sits behind a reverse proxy.
+     */
+    publicHost?: string;
+    /**
+     * Custom request authorizer applied to every HTTP request and WS upgrade.
+     * Return `false` to reject. When supplied, the built-in token check is
+     * skipped — there is exactly one auth pipeline. Synchronous because the
+     * WS upgrade handshake completes inline; async auth should be cached in
+     * a cookie by the host's own middleware and read back here.
+     */
+    authorize?: (req: IncomingMessage) => boolean;
+    /**
+     * IStore implementation. Omit for the default JSONL store at `dataDir`.
+     * Pass `null` to disable session/event persistence entirely.
+     */
+    store?: IStore | null;
+    /** Task store. Omit for default JsonTaskStore. `null` disables. */
+    taskStore?: ITaskStore | null;
+    /** Memory store. Omit for default JsonMemoryStore. `null` disables. */
+    memoryStore?: IMemoryStore | null;
+    /**
+     * EventStore backing resumable SSE streams. Omit for the in-memory
+     * default (1000 events / 5 minutes / 50 MiB). `null` disables
+     * resumability — reconnects after a drop start at the live tail.
+     */
+    eventStore?: EventStore | null;
+    /**
+     * Root data directory for the default stores. Omit to let `Bridge`
+     * compute a port-keyed default; pass explicitly when the host wants
+     * everything at a known location.
+     */
+    dataDir?: string;
+    /** Cosmetic friendly name; surfaces in the dashboard banner. */
+    label?: string;
+    /** URL path the MCP HTTP transport mounts on. Default `/mcp`. */
+    mcpPath?: string;
+    /**
+     * Whether to use stateful MCP sessions (sessionId in headers) or
+     * stateless one-shot requests. Default `true` (stateful — matches what
+     * Claude Code, Cursor, and the MCP spec default expect).
+     */
+    mcpStateful?: boolean;
+}
+
+export interface DaemonHandle {
+    /**
+     * Start the bridge and mount the MCP HTTP transport. Throws if the port
+     * is already in use — in embedded mode there's no leader/follower
+     * fallback; the host decides how to handle the conflict.
+     */
+    start(): Promise<void>;
+    /** Stop the MCP transport and bridge. Safe to call multiple times. */
+    stop(): Promise<void>;
+    /** Bound TCP port (only meaningful after `start`). */
+    getBoundPort(): number | undefined;
+    /** Outbound base URL for dashboard / replay viewer links. */
+    getViewerBaseUrl(): string | undefined;
+    /** Path the MCP HTTP transport is mounted on. */
+    readonly mcpPath: string;
+    /** Underlying bridge — escape hatch for tests and advanced wiring. */
+    readonly bridge: Bridge;
+}
+
+export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
+    const mcpPath = opts.mcpPath ?? '/mcp';
+
+    const bridge = new Bridge({
+        port: opts.port,
+        host: opts.host,
+        publicHost: opts.publicHost,
+        store: opts.store,
+        taskStore: opts.taskStore,
+        memoryStore: opts.memoryStore,
+        dataDir: opts.dataDir,
+        label: opts.label,
+        auth: opts.authorize ? { authorize: opts.authorize } : undefined,
+    });
+
+    let mcpHandle: Awaited<ReturnType<typeof startMcpHttpServer>> | undefined;
+    let started = false;
+    let stopped = false;
+
+    return {
+        mcpPath,
+        bridge,
+
+        async start() {
+            if (started) return;
+            started = true;
+            await bridge.start();
+            // Forward eventStore as-is so `null` opts out of resumability and
+            // `undefined` falls through to the default MemoryEventStore.
+            mcpHandle = await startMcpHttpServer(bridge, {
+                path: mcpPath,
+                stateful: opts.mcpStateful,
+                eventStore: opts.eventStore,
+            });
+        },
+
+        async stop() {
+            if (stopped) return;
+            stopped = true;
+            if (mcpHandle) {
+                try {
+                    await mcpHandle.close();
+                } catch {
+                    /* swallow — bridge.stop will be called anyway */
+                }
+            }
+            await bridge.stop();
+        },
+
+        getBoundPort() {
+            return bridge.getBoundPort();
+        },
+
+        getViewerBaseUrl() {
+            return bridge.getViewerBaseUrl();
+        },
+    };
+}