@harness-fe/mcp-server 3.0.1 → 3.1.0

package/src/daemon.ts

@@ -47,8 +47,19 @@ export interface DaemonOptions {
      * 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.
+     *
+     * Mutually exclusive with `token`. If both are provided, `authorize`
+     * wins and `token` is ignored.
      */
     authorize?: (req: IncomingMessage) => boolean;
+    /**
+     * Static token; auth requires `Authorization: Bearer <token>`, the
+     * `harness_fe_token` cookie, `?token=<token>`, or the matching WS
+     * subprotocol. Use this when you want the daemon's built-in auth and
+     * have no reason to plug in custom logic — the CLI's `--token` flag
+     * flows through here. Mutually exclusive with `authorize`.
+     */
+    token?: string;
     /**
      * IStore implementation. Omit for the default JSONL store at `dataDir`.
      * Pass `null` to disable session/event persistence entirely.
@@ -80,6 +91,14 @@ export interface DaemonOptions {
      * Claude Code, Cursor, and the MCP spec default expect).
      */
     mcpStateful?: boolean;
+    /**
+     * Whether to mount the MCP HTTP Streamable transport at `mcpPath`.
+     * Default `true`. Set to `false` if the host only needs the WS bridge
+     * (and wires up MCP over stdio externally — that's how the CLI's
+     * stdio mode boots the daemon through this factory without also
+     * exposing an HTTP MCP endpoint).
+     */
+    mcpHttp?: boolean;
 }
 
 export interface DaemonHandle {
@@ -103,6 +122,16 @@ export interface DaemonHandle {
 
 export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
     const mcpPath = opts.mcpPath ?? '/mcp';
+    const mountMcpHttp = opts.mcpHttp ?? true;
+
+    // Resolve auth: authorize wins if both are set. `undefined` here means
+    // no auth at all (loopback dev default). One pipeline — Bridge sees
+    // exactly one of `{ authorize }`, `{ token }`, or nothing.
+    const auth = opts.authorize
+        ? { authorize: opts.authorize }
+        : opts.token
+            ? { token: opts.token }
+            : undefined;
 
     const bridge = new Bridge({
         port: opts.port,
@@ -113,7 +142,7 @@ export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
         memoryStore: opts.memoryStore,
         dataDir: opts.dataDir,
         label: opts.label,
-        auth: opts.authorize ? { authorize: opts.authorize } : undefined,
+        auth,
     });
 
     let mcpHandle: Awaited<ReturnType<typeof startMcpHttpServer>> | undefined;
@@ -128,13 +157,15 @@ export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
             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,
-            });
+            if (mountMcpHttp) {
+                // 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() {

package/src/mcp.ts

@@ -28,6 +28,7 @@ import type { IBridge } from './bridge.js';
 import type { Bridge } from './bridge.js';
 import { RemoteBridge } from './remoteBridge.js';
 import type { IStore, IMemoryStore } from './store/index.js';
+import { buildVisitorTimeline } from './visitorTimeline.js';
 import { createReplayExport } from './replayCreate.js';
 import { openBrowser } from './openBrowser.js';
 import { buildDashboardUrl } from './dashboardUrl.js';
@@ -308,17 +309,27 @@ function registerTools(server: McpServer, bridge: IBridge): void {
         },
     );
 
+    const filterParam = z.string().optional().describe('Substring or regex (see `match`). Filters entries by their serialized payload before return.');
+    const matchParam = z.enum(['contains', 'regex']).optional().describe('How to interpret `filter`. Default: contains (case-insensitive). regex is case-insensitive too.');
+
     server.registerTool(
         COMMAND.CONSOLE_TAIL,
         {
-            description: 'Return the last N console entries from the page.',
+            description: 'Return the last N console entries from the page. Pass `filter` for substring/regex match against {level, args}; `level` for an exact match. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["log"]) for cross-navigate history.',
             inputSchema: {
                 n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                level: z.enum(['log', 'info', 'warn', 'error', 'debug']).optional(),
                 tabId: tabIdParam,
             },
         },
-        async ({ n, tabId }) => {
-            const out = await bridge.sendCommand(COMMAND.CONSOLE_TAIL, { n: n ?? 20 }, { tabId });
+        async ({ n, filter, match, level, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.CONSOLE_TAIL,
+                { n: n ?? 20, filter, match, level },
+                { tabId },
+            );
             return ok(out);
         },
     );
@@ -326,17 +337,22 @@ function registerTools(server: McpServer, bridge: IBridge): void {
     server.registerTool(
         COMMAND.NETWORK_TAIL,
         {
-            description: 'Return the last N network requests captured by the runtime client.',
+            description: 'Return the last N network requests captured by the runtime client. Each entry has phase=req|res keyed by `id`, and (for requests) an `initiator.stack` so you can see which code issued the call. Pass `filter` (against {url, method, body}), or narrow via `urlContains` / `method` / `statusCode`. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["req","res"]) for cross-navigate history.',
             inputSchema: {
                 n: z.number().int().positive().default(20).optional(),
                 includeBody: z.boolean().optional(),
+                filter: filterParam,
+                match: matchParam,
+                urlContains: z.string().optional().describe('Substring filter on url (case-sensitive).'),
+                method: z.string().optional().describe('Exact HTTP method match (e.g. "POST"). Case-insensitive.'),
+                statusCode: z.number().int().optional().describe('Exact status code match (response entries only).'),
                 tabId: tabIdParam,
             },
         },
-        async ({ n, includeBody, tabId }) => {
+        async ({ n, includeBody, filter, match, urlContains, method, statusCode, tabId }) => {
             const out = await bridge.sendCommand(
                 COMMAND.NETWORK_TAIL,
-                { n: n ?? 20, includeBody: includeBody ?? false },
+                { n: n ?? 20, includeBody: includeBody ?? false, filter, match, urlContains, method, statusCode },
                 { tabId },
             );
             return ok(out);
@@ -346,14 +362,145 @@ function registerTools(server: McpServer, bridge: IBridge): void {
     server.registerTool(
         COMMAND.ERRORS_TAIL,
         {
-            description: 'Return the last N JavaScript errors captured by the runtime client.',
+            description: 'Return the last N JavaScript errors captured by the runtime client. Pass `filter` for substring/regex match against {message, stack, source}. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["err"]) for cross-navigate history.',
             inputSchema: {
                 n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.ERRORS_TAIL,
+                { n: n ?? 20, filter, match },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.WS_TAIL,
+        {
+            description:
+                'Return the last N WebSocket frames captured by the runtime client. Each entry has phase=open|send|recv|close, a stable id per connection, payload (text/JSON when possible, [binary Nb] for buffers), and initiator.stack on open/send so you can see which code opened the connection or sent the frame. Pass `filter` for substring/regex match against {url, payload, reason}; `phase` for an exact match. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["ws"]) for cross-navigate history.',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                phase: z.enum(['open', 'send', 'recv', 'close']).optional(),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, phase, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.WS_TAIL,
+                { n: n ?? 20, filter, match, phase },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NETWORK_WAIT_FOR,
+        {
+            description:
+                'Resolve when a network request matching the predicate happens (or rejects on timeout). Considers requests issued AFTER this call — pre-existing matches in the buffer do not satisfy the wait.',
+            inputSchema: {
+                urlContains: z.string().optional(),
+                urlRegex: z.string().optional().describe('Case-insensitive regex against url.'),
+                method: z.string().optional(),
+                statusCode: z.number().int().optional(),
+                timeoutMs: z.number().int().positive().default(10000).optional(),
                 tabId: tabIdParam,
             },
         },
-        async ({ n, tabId }) => {
-            const out = await bridge.sendCommand(COMMAND.ERRORS_TAIL, { n: n ?? 20 }, { tabId });
+        async ({ urlContains, urlRegex, method, statusCode, timeoutMs, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.NETWORK_WAIT_FOR,
+                { urlContains, urlRegex, method, statusCode, timeoutMs },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NETWORK_WAIT_FOR_IDLE,
+        {
+            description:
+                'Resolve when no new network entries arrived for `idleMs` (default 500ms) — analogous to Playwright `waitForLoadState("networkidle")`. Useful for sequencing actions after a navigation or interaction.',
+            inputSchema: {
+                idleMs: z.number().int().positive().default(500).optional(),
+                timeoutMs: z.number().int().positive().default(10000).optional(),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ idleMs, timeoutMs, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.NETWORK_WAIT_FOR_IDLE,
+                { idleMs, timeoutMs },
+                { tabId },
+            );
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.NETWORK_GET,
+        {
+            description:
+                'Return all entries (req + res) for a single network request id. Use after `network.tail` when you need the full request/response body without the truncation pressure that comes from a multi-entry response.',
+            inputSchema: {
+                reqId: z.string().describe('id field from a `network.tail` entry'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ reqId, tabId }) => {
+            const out = await bridge.sendCommand(COMMAND.NETWORK_GET, { reqId }, { tabId });
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.WS_GET,
+        {
+            description:
+                'Return all frames (open / send / recv / close) for a single WebSocket id. Use after `ws.tail` when you need the full session of a particular connection.',
+            inputSchema: {
+                wsId: z.string().describe('id field from a `ws.tail` entry'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ wsId, tabId }) => {
+            const out = await bridge.sendCommand(COMMAND.WS_GET, { wsId }, { tabId });
+            return ok(out);
+        },
+    );
+
+    server.registerTool(
+        COMMAND.STORAGE_TAIL,
+        {
+            description:
+                'Return the last N localStorage / sessionStorage / cookie mutations. Each entry has op=set|remove|clear, which=local|session|cookie, key/value, an `initiator.stack` showing who issued the write, and crossTab=true when the mutation arrived via the native storage event from another tab. Filter via `filter` (against {op, which, key, value}), or narrow with `which` / `op` / `key`. Buffer is in-memory and cleared on navigate — use `session.tail` (type=["storage"]) for cross-navigate history.',
+            inputSchema: {
+                n: z.number().int().positive().default(20).optional(),
+                filter: filterParam,
+                match: matchParam,
+                which: z.enum(['local', 'session', 'cookie']).optional(),
+                op: z.enum(['set', 'remove', 'clear']).optional(),
+                key: z.string().optional().describe('Exact key match (case-sensitive).'),
+                tabId: tabIdParam,
+            },
+        },
+        async ({ n, filter, match, which, op, key, tabId }) => {
+            const out = await bridge.sendCommand(
+                COMMAND.STORAGE_TAIL,
+                { n: n ?? 20, filter, match, which, op, key },
+                { tabId },
+            );
             return ok(out);
         },
     );
@@ -602,7 +749,7 @@ function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemo
     server.registerTool(
         'session.tail',
         {
-            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId.',
+            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId. For cross-tab debugging within one visitor, use `visitor.timeline` to merge multiple sessions.',
             inputSchema: {
                 sessionId: z.string(),
                 n: z.number().int().positive().default(50).optional(),
@@ -840,6 +987,34 @@ function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemo
         },
     );
 
+    server.registerTool(
+        'visitor.timeline',
+        {
+            description:
+                'Merged event timeline across all sessions for one visitor, ascending by ts. Use this for cross-tab debugging (e.g. a ws frame in tab A causing a storage write in tab B). Each event carries `sessionId` and `tab` so the source tab is visible. Pass `sessionIds` to skip auto-discovery and merge a known set.',
+            inputSchema: {
+                visitorId: z.string(),
+                since: z.number().optional().describe('Only events after this Unix ts (ms)'),
+                until: z.number().optional().describe('Only events before this Unix ts (ms)'),
+                types: z.union([z.string(), z.array(z.string())]).optional()
+                    .describe('Filter by event type(s): log, err, req, res, ws, storage, cmd, resp, ...'),
+                tabIds: z.array(z.string()).optional()
+                    .describe('Narrow merge to specific tabIds. Default: all tabs known to this visitor.'),
+                sessionIds: z.array(z.string()).optional()
+                    .describe('Explicit session list to merge. When set, skips visitor → session discovery.'),
+                limit: z.number().int().positive().optional()
+                    .describe('Max events returned (newest). Default 200.'),
+            },
+        },
+        async ({ visitorId, since, until, types, tabIds, sessionIds, limit }) => {
+            const result = buildVisitorTimeline(store, visitorId, {
+                since, until, types, tabIds, sessionIds, limit,
+            });
+            if ('error' in result) return err(result.error);
+            return ok(result);
+        },
+    );
+
     server.registerTool(
         'session.recordings.list',
         {
@@ -1087,7 +1262,7 @@ function registerRemoteStoreTools(server: McpServer, bridge: RemoteBridge): void
     server.registerTool(
         'session.tail',
         {
-            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId.',
+            description: 'Read the last N events from a session timeline. Optionally filter by event type or projectId. For cross-tab debugging within one visitor, use `visitor.timeline` to merge multiple sessions.',
             inputSchema: {
                 sessionId: z.string(),
                 n: z.number().int().positive().default(50).optional(),

package/src/mcpHttp.test.ts

@@ -98,4 +98,106 @@ describe('mcpHttp', () => {
         // bodyless GET) means we made it past the auth layer.
         expect(withAuth.status).not.toBe(401);
     });
+
+    // SSE Last-Event-ID resumption — end-to-end wiring proof.
+    //
+    // What this asserts:
+    //   1. A real MCP HTTP session goes through the wire protocol cleanly.
+    //   2. The configured `EventStore` actually sees `storeEvent` calls
+    //      (the SDK is wired to persist outgoing messages through the
+    //      transport — not just sitting unused).
+    //   3. When a new GET arrives with `Last-Event-ID`, the SDK invokes
+    //      `replayEventsAfter` on the same store with that id (the resume
+    //      path is taken; replay isn't a no-op).
+    //
+    // The actual "no dupes / no gaps" invariant is covered comprehensively
+    // by MemoryEventStore.test.ts — here we prove the transport drives it.
+    it('drives the EventStore on stream and replays after Last-Event-ID', async () => {
+        const bridge = await startBridge();
+
+        // Spy that mirrors MemoryEventStore's contract while recording calls.
+        const storeCalls: Array<{ streamId: string; eventId: string }> = [];
+        const replayCalls: Array<{ lastEventId: string }> = [];
+        const eventsByStream = new Map<
+            string,
+            Array<{ eventId: string; message: JSONRPCMessage }>
+        >();
+        let seq = 0;
+        const spy: EventStore = {
+            async storeEvent(streamId, message) {
+                seq += 1;
+                const eventId = `${streamId}_${seq}`;
+                storeCalls.push({ streamId, eventId });
+                const arr = eventsByStream.get(streamId) ?? [];
+                arr.push({ eventId, message });
+                eventsByStream.set(streamId, arr);
+                return eventId;
+            },
+            async replayEventsAfter(lastEventId, { send }) {
+                replayCalls.push({ lastEventId });
+                // Recover streamId from event id and replay everything past it.
+                const streamId = lastEventId.split('_')[0];
+                const arr = eventsByStream.get(streamId) ?? [];
+                let resuming = false;
+                for (const { eventId, message } of arr) {
+                    if (resuming) await send(eventId, message);
+                    if (eventId === lastEventId) resuming = true;
+                }
+                return streamId;
+            },
+        };
+
+        const handle = await startMcpHttpServer(bridge, {
+            path: '/mcp',
+            eventStore: spy,
+        });
+        cleanups.push(() => handle.close());
+        const port = bridge.getBoundPort()!;
+        const url = `http://127.0.0.1:${port}/mcp`;
+
+        // 1. Initialize MCP session. The response goes back over the
+        //    Streamable HTTP response stream, so the SDK persists each
+        //    outgoing message through our spy store.
+        const init = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream',
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: { name: 'mcpHttp.test', version: '0.0.0' },
+                },
+            }),
+        });
+        const sessionId = init.headers.get('mcp-session-id');
+        expect(sessionId).toBeTruthy();
+        // Drain the response body so the connection can be reused.
+        await init.text();
+
+        // 2. The SDK should have persisted at least one message to the
+        //    EventStore by now — the initialize response.
+        expect(storeCalls.length).toBeGreaterThan(0);
+        const firstEventId = storeCalls[0]!.eventId;
+
+        // 3. Reopen the stream with Last-Event-ID set. This is what a
+        //    real client would do after a transient disconnect.
+        const resumed = await fetch(url, {
+            headers: {
+                accept: 'text/event-stream',
+                'mcp-session-id': sessionId!,
+                'last-event-id': firstEventId,
+            },
+        });
+        // Status varies (200 SSE) but the salient assertion is the spy
+        // saw the replay path get hit with the same id we passed.
+        expect(replayCalls).toEqual([{ lastEventId: firstEventId }]);
+        // Drop the long-lived stream we just opened — it has no consumer.
+        await resumed.body?.cancel();
+    });
 });