@harness-fe/mcp-server 3.0.1

package/dist/mcpHttp.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { IBridge } from './bridge.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 declare function startMcpHttpServer(bridge: IBridge, opts?: McpHttpOptions): Promise<McpHttpHandle>;

package/dist/mcpHttp.js

@@ -0,0 +1,49 @@
+/**
+ * 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 { createMcpServer } from './mcp.js';
+import { MemoryEventStore } from './store/MemoryEventStore.js';
+/**
+ * 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, opts = {}) {
+    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;
+    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, res) => {
+        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/dist/openBrowser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare function openBrowser(url: string, opts?: OpenBrowserOptions): OpenBrowserResult;

package/dist/openBrowser.js

@@ -0,0 +1,63 @@
+/**
+ * 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 function openBrowser(url, opts = {}) {
+    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;
+    let args;
+    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/dist/remoteBridge.d.ts

@@ -0,0 +1,61 @@
+/**
+ * RemoteBridge — IBridge implementation backed by a WS connection to an
+ * already-running daemon (leader).
+ *
+ * Used when this process starts as a follower: another cli.js is already
+ * listening on :47729, so we attach as a ws client and proxy every MCP tool
+ * call through the new `mcp.call` / `mcp.return` control frames.
+ */
+import { type McpCallFrame, type TabInfo, type Task, type TaskStatus } from '@harness-fe/protocol';
+import type { IBridge, SendCommandOptions } from './bridge.js';
+import type { IMemoryStore, IStore } from './store/index.js';
+export interface RemoteBridgeOptions {
+    port: number;
+    host?: string;
+    /** Per-call timeout. Must be ≥ daemon's command timeout to surface upstream errors first. */
+    callTimeoutMs?: number;
+    /** Token used to authenticate against the leader, if it requires one. */
+    token?: string;
+}
+export declare class RemoteBridge implements IBridge {
+    private ws?;
+    private pending;
+    private closed;
+    private readonly url;
+    private readonly callTimeoutMs;
+    private readonly host;
+    private readonly port;
+    private readonly token;
+    constructor(opts: RemoteBridgeOptions);
+    connect(): Promise<void>;
+    stop(): Promise<void>;
+    sendCommand(command: string, args: unknown, opts?: SendCommandOptions): Promise<unknown>;
+    listTabs(): Promise<TabInfo[]>;
+    listTasks(filter?: {
+        status?: TaskStatus | 'all';
+        limit?: number;
+    }): Promise<Task[]>;
+    claimTask(id: string): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    /**
+     * Returns a RemoteMemoryStore that proxies all memory operations to the
+     * leader via the mcp.call channel. This allows follower instances to use
+     * the same project.memory.* tools as the leader.
+     */
+    getMemoryStore(): IMemoryStore;
+    getViewerBaseUrl(): string | undefined;
+    getAuthToken(): string | undefined;
+    getTaskAttachmentData(_taskId: string, _attachmentId: string): Promise<string | null>;
+    /**
+     * Returns a RemoteStore that proxies all store read/query operations to
+     * the leader via the mcp.call channel. Write operations (openSession,
+     * append, etc.) are not proxied — followers are read-only.
+     */
+    getStore(): IStore;
+    /** @internal — used by RemoteMemoryStore and RemoteStore */
+    invokeRemote(method: McpCallFrame['method'], args: unknown): Promise<unknown>;
+    private invoke;
+    private attachHandlers;
+    private handleReturn;
+    private handleClose;
+}

package/dist/remoteBridge.js

@@ -0,0 +1,307 @@
+/**
+ * RemoteBridge — IBridge implementation backed by a WS connection to an
+ * already-running daemon (leader).
+ *
+ * Used when this process starts as a follower: another cli.js is already
+ * listening on :47729, so we attach as a ws client and proxy every MCP tool
+ * call through the new `mcp.call` / `mcp.return` control frames.
+ */
+import { WebSocket } from 'ws';
+import { randomUUID } from 'node:crypto';
+import { frameSchema, } from '@harness-fe/protocol';
+const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+export class RemoteBridge {
+    ws;
+    pending = new Map();
+    closed = false;
+    url;
+    callTimeoutMs;
+    host;
+    port;
+    token;
+    constructor(opts) {
+        const host = opts.host ?? '127.0.0.1';
+        this.host = host;
+        this.port = opts.port;
+        this.token = opts.token;
+        const tokenQs = opts.token ? `?token=${encodeURIComponent(opts.token)}` : '';
+        this.url = `ws://${host}:${opts.port}${tokenQs}`;
+        this.callTimeoutMs = opts.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const headers = {};
+            if (this.token)
+                headers.authorization = `Bearer ${this.token}`;
+            const ws = new WebSocket(this.url, { headers });
+            this.ws = ws;
+            const onOpen = () => {
+                ws.off('error', onErr);
+                this.attachHandlers(ws);
+                resolve();
+            };
+            const onErr = (err) => {
+                ws.off('open', onOpen);
+                reject(err);
+            };
+            ws.once('open', onOpen);
+            ws.once('error', onErr);
+        });
+    }
+    async stop() {
+        this.closed = true;
+        const ws = this.ws;
+        if (!ws)
+            return;
+        try {
+            ws.close();
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    sendCommand(command, args, opts) {
+        return this.invoke('sendCommand', { command, args, opts });
+    }
+    listTabs() {
+        return this.invoke('listTabs', {});
+    }
+    listTasks(filter = {}) {
+        return this.invoke('listTasks', filter);
+    }
+    claimTask(id) {
+        return this.invoke('claimTask', { id });
+    }
+    resolveTask(id, note) {
+        return this.invoke('resolveTask', { id, note });
+    }
+    /**
+     * Returns a RemoteMemoryStore that proxies all memory operations to the
+     * leader via the mcp.call channel. This allows follower instances to use
+     * the same project.memory.* tools as the leader.
+     */
+    getMemoryStore() {
+        return new RemoteMemoryStore(this);
+    }
+    getViewerBaseUrl() {
+        // Followers share the same WS/HTTP port as the leader.
+        return `http://${this.host}:${this.port}`;
+    }
+    getAuthToken() {
+        // Followers connect to the leader using their own configured token
+        // (passed in via RemoteBridge constructor). Surface it so dashboard
+        // links the follower hands out are pre-authenticated.
+        return this.token;
+    }
+    async getTaskAttachmentData(_taskId, _attachmentId) {
+        // Follower mode: attachment reads are not proxied in v0.6; direct leader access needed.
+        return null;
+    }
+    /**
+     * Returns a RemoteStore that proxies all store read/query operations to
+     * the leader via the mcp.call channel. Write operations (openSession,
+     * append, etc.) are not proxied — followers are read-only.
+     */
+    getStore() {
+        return new RemoteStore(this);
+    }
+    /** @internal — used by RemoteMemoryStore and RemoteStore */
+    invokeRemote(method, args) {
+        return this.invoke(method, args);
+    }
+    invoke(method, args) {
+        const ws = this.ws;
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            return Promise.reject(new Error('remote-bridge: not connected'));
+        }
+        const id = randomUUID();
+        const frame = { type: 'mcp.call', id, method, args };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`remote-bridge: "${method}" timed out after ${this.callTimeoutMs}ms`));
+            }, this.callTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                ws.send(JSON.stringify(frame));
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(err);
+            }
+        });
+    }
+    attachHandlers(ws) {
+        ws.on('message', (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            const frame = frameSchema.safeParse(parsed);
+            if (!frame.success)
+                return;
+            if (frame.data.type !== 'mcp.return')
+                return;
+            this.handleReturn(frame.data);
+        });
+        ws.on('close', () => this.handleClose());
+        ws.on('error', () => {
+            /* close will follow */
+        });
+    }
+    handleReturn(frame) {
+        const p = this.pending.get(frame.id);
+        if (!p)
+            return;
+        clearTimeout(p.timer);
+        this.pending.delete(frame.id);
+        if (frame.ok) {
+            p.resolve(frame.result);
+        }
+        else {
+            p.reject(new Error(frame.error?.message ?? 'remote-bridge: unknown error'));
+        }
+    }
+    handleClose() {
+        const err = new Error(this.closed
+            ? 'remote-bridge: connection closed'
+            : 'remote-bridge: lost connection to daemon');
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
+}
+// ─── RemoteMemoryStore ────────────────────────────────────────────────────────
+//
+// Proxies IMemoryStore operations to the leader via mcp.call frames.
+// Used by follower instances so project.memory.* tools work in all windows.
+class RemoteMemoryStore {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    get(projectId, key) {
+        // Synchronous interface — not directly awaitable. The MCP tool layer
+        // wraps calls in async handlers, so we return a thenable-compatible
+        // object. In practice mcp.ts awaits the result via the async handler.
+        // We throw here to signal that callers must use the async path.
+        throw new Error('RemoteMemoryStore.get() must be called via the async MCP tool handler. ' +
+            'Use remoteMemoryStore.getAsync() instead.');
+    }
+    /** Async variant used by the MCP tool handlers in mcp.ts. */
+    async getAsync(projectId, key) {
+        return this.bridge.invokeRemote('memoryGet', { projectId, key });
+    }
+    set(projectId, key, value) {
+        throw new Error('RemoteMemoryStore.set() must be called via setAsync().');
+    }
+    async setAsync(projectId, key, value) {
+        return this.bridge.invokeRemote('memorySet', { projectId, key, value });
+    }
+    delete(projectId, key) {
+        throw new Error('RemoteMemoryStore.delete() must be called via deleteAsync().');
+    }
+    async deleteAsync(projectId, key) {
+        return this.bridge.invokeRemote('memoryDelete', { projectId, key });
+    }
+    list(projectId) {
+        throw new Error('RemoteMemoryStore.list() must be called via listAsync().');
+    }
+    async listAsync(projectId) {
+        return this.bridge.invokeRemote('memoryList', { projectId });
+    }
+}
+// ─── RemoteStore ──────────────────────────────────────────────────────────────
+//
+// Proxies IStore read operations to the leader via mcp.call frames.
+// Write operations throw — followers are read-only for the store.
+class RemoteStore {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    // ── Read operations (proxied) ──────────────────────────────────────────
+    async listProjectsAsync() {
+        return this.bridge.invokeRemote('storeListProjects', {});
+    }
+    async listSessionsAsync(opts) {
+        return this.bridge.invokeRemote('storeListSessions', opts ?? {});
+    }
+    async summaryAsync(sessionId) {
+        return this.bridge.invokeRemote('storeSummary', { sessionId });
+    }
+    async tailAsync(sessionId, opts) {
+        return this.bridge.invokeRemote('storeTail', { sessionId, opts });
+    }
+    async searchAsync(sessionId, query, opts) {
+        return this.bridge.invokeRemote('storeSearch', { sessionId, query, opts });
+    }
+    async listRecordingsAsync(sessionId) {
+        return this.bridge.invokeRemote('storeRecordingsList', { sessionId });
+    }
+    async sliceRecordingsAsync(sessionId, since, until) {
+        return this.bridge.invokeRemote('storeRecordingsSlice', { sessionId, since, until });
+    }
+    async replayCreateAsync(args) {
+        return this.bridge.invokeRemote('storeReplayCreate', args);
+    }
+    async purgeAsync(policy) {
+        return this.bridge.invokeRemote('storePurge', policy ?? {});
+    }
+    // ── Synchronous IStore interface stubs (not used by follower) ─────────
+    // These satisfy the interface but throw — the MCP tool handlers in mcp.ts
+    // use the async variants above when running in follower mode.
+    // Build lifecycle
+    openBuild(_p, _patch) { throw notSupported('openBuild'); }
+    closeBuild(_b, _c) { throw notSupported('closeBuild'); }
+    // Tab lifecycle
+    upsertTab(_t, _patch) { throw notSupported('upsertTab'); }
+    getTab(_t) { throw notSupported('getTab'); }
+    closeTab(_t, _d) { throw notSupported('closeTab'); }
+    // Session lifecycle
+    upsertSession(_s, _m) { throw notSupported('upsertSession'); }
+    closeSession(_s, _e) { throw notSupported('closeSession'); }
+    getSession(_id) { throw notSupported('getSession'); }
+    listSessions(_opts) { throw notSupported('listSessions'); }
+    // Write
+    appendEvent(_s, _e) { throw notSupported('appendEvent'); }
+    appendEventBatch(_s, _e) { throw notSupported('appendEventBatch'); }
+    appendRecording(_s, _c) { throw notSupported('appendRecording'); }
+    writeNote(_p, _k, _v) { throw notSupported('writeNote'); }
+    // Project metadata
+    listProjects() { throw notSupported('listProjects'); }
+    upsertProject(_p, _patch) { throw notSupported('upsertProject'); }
+    getProject(_p) { throw notSupported('getProject'); }
+    getProjectTree(_r) { throw notSupported('getProjectTree'); }
+    // Build metadata
+    upsertBuild(_p, _b, _patch) { throw notSupported('upsertBuild'); }
+    getBuild(_p, _b) { throw notSupported('getBuild'); }
+    listBuilds(_p, _l) { throw notSupported('listBuilds'); }
+    // Visitor metadata (0.5+) — followers don't proxy yet; leader-only for now.
+    upsertVisitor(_v, _patch) { throw notSupported('upsertVisitor'); }
+    getVisitor(_v) { throw notSupported('getVisitor'); }
+    listVisitors(_opts) { throw notSupported('listVisitors'); }
+    // Read
+    tail(_s, _o) { throw notSupported('tail'); }
+    search(_s, _q, _o) { throw notSupported('search'); }
+    listRecordings(_s) { throw notSupported('listRecordings'); }
+    sliceRecordings(_s, _since, _until) { throw notSupported('sliceRecordings'); }
+    writeExport(_i) { throw notSupported('writeExport'); }
+    getExport(_id) { throw notSupported('getExport'); }
+    readExportEvents(_id) { throw notSupported('readExportEvents'); }
+    listExports(_p, _l) { throw notSupported('listExports'); }
+    summary(_s) { throw notSupported('summary'); }
+    listNotes(_p) { throw notSupported('listNotes'); }
+    // Maintenance
+    purge(_p) { throw notSupported('purge'); }
+    close() { }
+}
+function notSupported(method) {
+    return new Error(`remote-bridge: IStore.${method}() is not available in follower mode`);
+}

package/dist/replayCreate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared replay-export logic used by both the leader's MCP tool handler and
+ * the leader's mcp.call dispatcher (for follower proxy calls).
+ *
+ * Takes a time window (or a center timestamp), pulls the overlapping rrweb
+ * chunks for a single tab, concatenates the events, persists them as an
+ * export, and returns the metadata + viewerUrl.
+ */
+import type { IStore } from './store/index.js';
+export interface ReplayCreateArgs {
+    sessionId: string;
+    tabId?: string;
+    ts?: number;
+    windowMs?: number;
+    since?: number;
+    until?: number;
+    label?: string;
+}
+export interface ReplayCreateResult {
+    exportId?: string;
+    viewerUrl?: string;
+    sessionId: string;
+    tabId?: string;
+    since: number;
+    until: number;
+    startTs?: number;
+    endTs?: number;
+    durationMs?: number;
+    eventCount?: number;
+    chunkCount?: number;
+    bytes?: number;
+    createdAt?: number;
+    label?: string;
+    error?: string;
+}
+export declare function createReplayExport(store: IStore, baseUrl: string | undefined, input: ReplayCreateArgs): ReplayCreateResult;