@harness-fe/mcp-server 3.0.1

package/src/mcpHttp.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+import { Bridge } from './bridge.js';
+import { startMcpHttpServer } from './mcpHttp.js';
+import { MemoryEventStore } from './store/MemoryEventStore.js';
+import type { EventStore } from './store/types.js';
+
+const cleanups: Array<() => Promise<void> | void> = [];
+
+afterEach(async () => {
+    while (cleanups.length) {
+        const fn = cleanups.shift();
+        if (fn) await fn();
+    }
+});
+
+async function startBridge(opts: Parameters<typeof Bridge.prototype.constructor>[0] = {}) {
+    const bridge = new Bridge({
+        port: 0,
+        host: '127.0.0.1',
+        store: null,
+        taskStore: null,
+        autoPurge: { enabled: false },
+        ...opts,
+    });
+    await bridge.start();
+    cleanups.push(() => bridge.stop());
+    return bridge;
+}
+
+describe('mcpHttp', () => {
+    it('mounts on the configured path and 404s other paths', async () => {
+        const bridge = await startBridge();
+        const handle = await startMcpHttpServer(bridge, { path: '/mcp' });
+        cleanups.push(() => handle.close());
+
+        const port = bridge.getBoundPort()!;
+        // GET on /mcp without a session id should still be routed to the
+        // transport (which decides what to do); /something-else should fall
+        // through to the bridge default handler (404).
+        const elsewhere = await fetch(`http://127.0.0.1:${port}/elsewhere`);
+        expect(elsewhere.status).toBe(404);
+
+        const mcpRes = await fetch(`http://127.0.0.1:${port}/mcp`);
+        // Transport responds (status varies — what we assert is that the
+        // request reached the transport, i.e. it's NOT the bridge 404 body).
+        const body = await mcpRes.text();
+        expect(body).not.toBe('Not Found');
+    });
+
+    it('accepts a custom EventStore and disables resumability when passed null', async () => {
+        const bridge = await startBridge();
+
+        // Spy store records which events the SDK hands it.
+        const stored: Array<{ streamId: string; message: JSONRPCMessage }> = [];
+        const spy: EventStore = {
+            async storeEvent(streamId, message) {
+                stored.push({ streamId, message });
+                return `${streamId}::${stored.length}`;
+            },
+            async replayEventsAfter() {
+                return '';
+            },
+        };
+
+        const h1 = await startMcpHttpServer(bridge, { path: '/mcp1', eventStore: spy });
+        cleanups.push(() => h1.close());
+        expect(h1.path).toBe('/mcp1');
+
+        // Disabling resumability is a supported configuration.
+        const h2 = await startMcpHttpServer(bridge, { path: '/mcp2', eventStore: null });
+        cleanups.push(() => h2.close());
+        expect(h2.path).toBe('/mcp2');
+
+        // And the default path keeps the built-in MemoryEventStore.
+        const h3 = await startMcpHttpServer(bridge, {
+            path: '/mcp3',
+            eventStore: new MemoryEventStore({ maxEventsPerStream: 10 }),
+        });
+        cleanups.push(() => h3.close());
+        expect(h3.path).toBe('/mcp3');
+    });
+
+    it('requires token when bridge has auth enabled', async () => {
+        const bridge = await startBridge({ auth: { token: 's3cret' } });
+        const handle = await startMcpHttpServer(bridge, { path: '/mcp' });
+        cleanups.push(() => handle.close());
+        const port = bridge.getBoundPort()!;
+
+        const noAuth = await fetch(`http://127.0.0.1:${port}/mcp`);
+        expect(noAuth.status).toBe(401);
+
+        const withAuth = await fetch(`http://127.0.0.1:${port}/mcp`, {
+            headers: { authorization: 'Bearer s3cret' },
+        });
+        // 401 specifically would mean auth still blocked us. Anything else
+        // (200 / 405 / 406 / 400 — depending on what the SDK does for a
+        // bodyless GET) means we made it past the auth layer.
+        expect(withAuth.status).not.toBe(401);
+    });
+});

package/src/mcpHttp.ts

@@ -0,0 +1,88 @@
+/**
+ * MCP over HTTP transport mounted onto the bridge's existing HTTP server.
+ *
+ * Reuses the bridge's auth wrapper, so the same `--token` that protects
+ * the dashboard also protects MCP tool calls. Remote agents talk to
+ * `http://<host>:<port>/mcp` and authenticate via `Authorization: Bearer
+ * <token>` like any other client.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Bridge, IBridge } from './bridge.js';
+import { createMcpServer } from './mcp.js';
+import { MemoryEventStore } from './store/MemoryEventStore.js';
+import type { EventStore } from './store/types.js';
+
+export interface McpHttpOptions {
+    /** URL path the transport listens on. Default `/mcp`. */
+    path?: string;
+    /**
+     * Whether to use stateful sessions (sessionId in headers) or stateless
+     * one-shot requests. Stateful is the spec default and matches what
+     * Claude Code expects.
+     */
+    stateful?: boolean;
+    /**
+     * EventStore for SSE resumability via `Last-Event-ID`. If a client
+     * reconnects after a transient disconnect, the transport replays the
+     * events it missed. Defaults to a `MemoryEventStore` with conservative
+     * caps (1000 events / 5 minutes / 50 MiB total). Pass `null` to
+     * disable resumability entirely.
+     */
+    eventStore?: EventStore | null;
+}
+
+export interface McpHttpHandle {
+    /** Close the MCP server and detach the transport. */
+    close(): Promise<void>;
+    path: string;
+}
+
+/**
+ * Mount the MCP HTTP transport on the bridge's HTTP server. Bridge must
+ * already have been started; calls `prependHttpHandler` so it runs before
+ * the dashboard/replay/events handler chain.
+ */
+export async function startMcpHttpServer(
+    bridge: IBridge,
+    opts: McpHttpOptions = {},
+): Promise<McpHttpHandle> {
+    const path = opts.path ?? '/mcp';
+    const stateful = opts.stateful !== false;
+    const eventStore =
+        opts.eventStore === null
+            ? undefined
+            : opts.eventStore ?? new MemoryEventStore();
+
+    const server = createMcpServer(bridge);
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: stateful ? () => randomUUID() : undefined,
+        eventStore,
+    });
+    await server.connect(transport);
+
+    const b = bridge as Bridge;
+    if (typeof b.prependHttpHandler !== 'function') {
+        throw new Error(
+            'mcpHttp: bridge does not support prependHttpHandler (need a Bridge instance with HTTP server)',
+        );
+    }
+
+    b.prependHttpHandler(async (req: IncomingMessage, res: ServerResponse) => {
+        const url = req.url ?? '';
+        const qi = url.indexOf('?');
+        const reqPath = qi < 0 ? url : url.slice(0, qi);
+        if (reqPath !== path) return false;
+        await transport.handleRequest(req, res);
+        return true;
+    });
+
+    return {
+        path,
+        async close() {
+            await server.close();
+        },
+    };
+}

package/src/openBrowser.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from 'vitest';
+import { openBrowser } from './openBrowser.js';
+
+/**
+ * Unit tests for the cross-platform browser launcher. We mock both
+ * `spawn` and the platform/env probes so the test runs deterministically
+ * on any host — no actual browser windows pop open in CI.
+ */
+describe('openBrowser', () => {
+    function spy() {
+        return vi.fn(() => ({
+            unref: vi.fn(),
+        }) as any);
+    }
+
+    it('uses `open` on darwin', () => {
+        const spawnFn = spy();
+        const out = openBrowser('https://example.test', {
+            platformOverride: 'darwin',
+            envOverride: {},
+            spawnOverride: spawnFn,
+        });
+        expect(out.opened).toBe(true);
+        expect(spawnFn).toHaveBeenCalledWith('open', ['https://example.test'], expect.any(Object));
+    });
+
+    it('uses `xdg-open` on linux', () => {
+        const spawnFn = spy();
+        const out = openBrowser('https://example.test', {
+            platformOverride: 'linux',
+            envOverride: {},
+            spawnOverride: spawnFn,
+        });
+        expect(out.opened).toBe(true);
+        expect(spawnFn).toHaveBeenCalledWith('xdg-open', ['https://example.test'], expect.any(Object));
+    });
+
+    it('uses `cmd /c start "" <url>` on win32 (empty title is required)', () => {
+        const spawnFn = spy();
+        const out = openBrowser('https://example.test', {
+            platformOverride: 'win32',
+            envOverride: {},
+            spawnOverride: spawnFn,
+        });
+        expect(out.opened).toBe(true);
+        expect(spawnFn).toHaveBeenCalledWith(
+            'cmd',
+            ['/c', 'start', '', 'https://example.test'],
+            expect.any(Object),
+        );
+    });
+
+    it('short-circuits when HARNESS_FE_HEADLESS=1 is set', () => {
+        const spawnFn = spy();
+        const out = openBrowser('https://example.test', {
+            platformOverride: 'darwin',
+            envOverride: { HARNESS_FE_HEADLESS: '1' },
+            spawnOverride: spawnFn,
+        });
+        expect(out.opened).toBe(false);
+        expect(out.reason).toMatch(/HEADLESS/);
+        expect(spawnFn).not.toHaveBeenCalled();
+    });
+
+    it('returns opened=false on unsupported platforms with a reason', () => {
+        const spawnFn = spy();
+        const out = openBrowser('https://example.test', {
+            platformOverride: 'freebsd' as NodeJS.Platform,
+            envOverride: {},
+            spawnOverride: spawnFn,
+        });
+        expect(out.opened).toBe(false);
+        expect(out.reason).toMatch(/unsupported platform/);
+        expect(spawnFn).not.toHaveBeenCalled();
+    });
+
+    it('catches spawn errors and returns opened=false', () => {
+        const spawnFn = vi.fn(() => {
+            throw new Error('ENOENT: no such file');
+        }) as unknown as typeof openBrowser['arguments'][1]['spawnOverride'];
+        const out = openBrowser('https://example.test', {
+            platformOverride: 'darwin',
+            envOverride: {},
+            spawnOverride: spawnFn as any,
+        });
+        expect(out.opened).toBe(false);
+        expect(out.reason).toMatch(/ENOENT/);
+    });
+
+    it('detaches and unrefs the child so it survives the parent exit', () => {
+        const unref = vi.fn();
+        const spawnFn = vi.fn(() => ({ unref })) as any;
+        openBrowser('https://example.test', {
+            platformOverride: 'darwin',
+            envOverride: {},
+            spawnOverride: spawnFn,
+        });
+        const opts = (spawnFn.mock.calls[0]?.[2] ?? {}) as { detached?: boolean; stdio?: string };
+        expect(opts.detached).toBe(true);
+        expect(opts.stdio).toBe('ignore');
+        expect(unref).toHaveBeenCalledOnce();
+    });
+});

package/src/openBrowser.ts

@@ -0,0 +1,81 @@
+/**
+ * Cross-platform "open this URL in the user's default browser" — a tiny
+ * wrapper around the OS-native command.
+ *
+ * Detection rules:
+ *   - darwin → `open <url>`
+ *   - linux  → `xdg-open <url>`
+ *   - win32  → `cmd /c start "" <url>` (the empty title is required, otherwise `start` treats the URL as a title)
+ *
+ * Escape hatches:
+ *   - `HARNESS_FE_HEADLESS=1` short-circuits and returns `false` without
+ *     spawning anything — useful when the daemon runs in Docker / CI /
+ *     remote host where there's no GUI to open
+ *   - any other platform returns `false`
+ *
+ * The spawned process is detached and stdio'd to ignore so we don't
+ * accidentally tie its lifetime to ours.
+ */
+
+import { spawn } from 'node:child_process';
+
+export interface OpenBrowserOptions {
+    /** Inject an alternate `process.platform` value, for tests. */
+    platformOverride?: NodeJS.Platform;
+    /** Inject the env lookup, for tests. */
+    envOverride?: Record<string, string | undefined>;
+    /** Inject the spawn function, for tests. */
+    spawnOverride?: typeof spawn;
+}
+
+export interface OpenBrowserResult {
+    opened: boolean;
+    /** Set when `opened` is false to explain why. */
+    reason?: string;
+}
+
+export function openBrowser(url: string, opts: OpenBrowserOptions = {}): OpenBrowserResult {
+    const env = opts.envOverride ?? process.env;
+    if (env.HARNESS_FE_HEADLESS === '1') {
+        return { opened: false, reason: 'HARNESS_FE_HEADLESS=1' };
+    }
+    const platform = opts.platformOverride ?? process.platform;
+    const spawnFn = opts.spawnOverride ?? spawn;
+
+    let cmd: string;
+    let args: string[];
+    switch (platform) {
+        case 'darwin':
+            cmd = 'open';
+            args = [url];
+            break;
+        case 'linux':
+            cmd = 'xdg-open';
+            args = [url];
+            break;
+        case 'win32':
+            // `start` is a cmd builtin, not a standalone exe. The first
+            // empty-string arg is the window title — required, because
+            // otherwise `start "https://…"` treats the URL as the title
+            // and never opens anything.
+            cmd = 'cmd';
+            args = ['/c', 'start', '', url];
+            break;
+        default:
+            return { opened: false, reason: `unsupported platform: ${platform}` };
+    }
+
+    try {
+        const child = spawnFn(cmd, args, {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return { opened: true };
+    } catch (err) {
+        return {
+            opened: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/src/remoteBridge.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { Bridge } from './bridge.js';
+import { RemoteBridge } from './remoteBridge.js';
+import type { Frame, HelloAckFrame, ResponseFrame } from '@harness-fe/protocol';
+
+async function spawnLeader(): Promise<Bridge> {
+    const bridge = new Bridge({ port: 0, host: '127.0.0.1', tasksFile: '', store: null });
+    await bridge.start();
+    return bridge;
+}
+
+function getPort(bridge: Bridge): number {
+    const port = bridge.getBoundPort();
+    if (!port) throw new Error('no address');
+    return port;
+}
+
+async function fakeRuntimeClient(
+    port: number,
+    tabId: string,
+): Promise<WebSocket> {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve, reject) => {
+        ws.once('open', () => resolve());
+        ws.once('error', reject);
+    });
+    ws.send(
+        JSON.stringify({
+            type: 'hello',
+            id: 'h-rc',
+            role: 'runtime-client',
+            projectId: 'demo',
+            tabId,
+            sessionId: 'sess-1',
+            page: { url: 'http://localhost:5173/', title: 'Demo' },
+        }),
+    );
+    await new Promise<HelloAckFrame>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('hello.ack timeout')), 1000);
+        ws.once('message', (raw) => {
+            clearTimeout(timer);
+            resolve(JSON.parse(raw.toString()) as HelloAckFrame);
+        });
+    });
+    return ws;
+}
+
+describe('RemoteBridge (follower → leader)', () => {
+    it('listTabs reflects tabs registered on the leader', async () => {
+        const leader = await spawnLeader();
+        try {
+            const port = getPort(leader);
+            const rc = await fakeRuntimeClient(port, 't-remote-1');
+
+            const follower = new RemoteBridge({ port, host: '127.0.0.1' });
+            await follower.connect();
+            try {
+                const tabs = await follower.listTabs();
+                expect(tabs).toHaveLength(1);
+                expect(tabs[0].tabId).toBe('t-remote-1');
+            } finally {
+                await follower.stop();
+                rc.close();
+            }
+        } finally {
+            await leader.stop();
+        }
+    });
+
+    it('sendCommand forwards through leader to runtime-client and returns the result', async () => {
+        const leader = await spawnLeader();
+        try {
+            const port = getPort(leader);
+            const rc = await fakeRuntimeClient(port, 't-remote-2');
+            // Echo: respond ok with { echoed: args }
+            rc.on('message', (raw) => {
+                const frame = JSON.parse(raw.toString()) as Frame;
+                if (frame.type !== 'command') return;
+                const reply: ResponseFrame = {
+                    type: 'response',
+                    id: frame.id,
+                    ok: true,
+                    result: { echoed: frame.args },
+                };
+                rc.send(JSON.stringify(reply));
+            });
+
+            const follower = new RemoteBridge({ port, host: '127.0.0.1' });
+            await follower.connect();
+            try {
+                const out = (await follower.sendCommand(
+                    'page.evaluate',
+                    { expr: '1+1' },
+                    { tabId: 't-remote-2' },
+                )) as { echoed: { expr: string } };
+                expect(out.echoed.expr).toBe('1+1');
+            } finally {
+                await follower.stop();
+                rc.close();
+            }
+        } finally {
+            await leader.stop();
+        }
+    });
+
+    it('rejects pending calls when leader disappears', async () => {
+        const leader = await spawnLeader();
+        const port = getPort(leader);
+        const follower = new RemoteBridge({ port, host: '127.0.0.1' });
+        await follower.connect();
+        // Issue a call with no runtime-client connected → leader will throw; we just
+        // need to confirm follower receives the propagated error frame cleanly.
+        const callPromise = follower.sendCommand('page.click', { selector: { css: '#x' } });
+        await expect(callPromise).rejects.toThrow(/no runtime-client|connection|closed/i);
+        await follower.stop();
+        await leader.stop();
+    });
+});