@harness-fe/mcp-server 3.0.1

package/dist/store/types.d.ts

@@ -0,0 +1,416 @@
+/**
+ * Store types — the public interface for the JSONL-based persistence layer.
+ *
+ * v0.4.0 layout (new, flat):
+ *   {dataDir}/projects/{projectId}/meta.json
+ *   {dataDir}/projects/{projectId}/tasks.json
+ *   {dataDir}/projects/{projectId}/memory.json
+ *   {dataDir}/projects/{projectId}/notes.jsonl
+ *   {dataDir}/projects/{projectId}/builds/{buildId}/meta.json
+ *   {dataDir}/tabs/{tabId}/meta.json
+ *   {dataDir}/sessions/{sessionId}/meta.json       ← one per pageload
+ *   {dataDir}/sessions/{sessionId}/timeline.jsonl  ← mixed parent+child events
+ *   {dataDir}/sessions/{sessionId}/recording.jsonl ← rrweb chunks
+ *   {dataDir}/visitors/{visitorId}/meta.json       ← per-browser identity (0.5+)
+ *
+ * Legacy layout (v0.3.x, read-only fallback — daemon warns on startup):
+ *   {dataDir}/{projectId}/sessions/{buildId}/tabs/{tabId}/...
+ */
+import type { Task, VisitorEnv } from '@harness-fe/protocol';
+export type { EventId, EventStore, StreamId, } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+/** Short type codes used in JSONL lines to keep files compact. */
+export type EventType = 'log' | 'err' | 'req' | 'res' | 'cmd' | 'resp' | 'hmr' | 'task' | 'task:claim' | 'task:resolve' | 'rrweb' | 'node:log' | 'node:err' | 'note' | 'load' | 'storage' | 'server-log' | 'server-err' | 'server-action' | 'app-log' | string;
+/** A single event line in a JSONL file. Carries row-level projectId/buildId tags. */
+export interface StoreEvent {
+    /**
+     * Server-assigned monotonic integer per session (assigned at enqueue time).
+     * Optional on input — the store layer assigns this.
+     * Always present on events returned by `tail` and `search`.
+     */
+    seq?: number;
+    /** Unix timestamp in milliseconds. */
+    ts: number;
+    /** Short event type code. */
+    t: EventType;
+    /** Tab ID — present for tab-scoped events. */
+    tab?: string;
+    /**
+     * Load/session ID on tab-scoped events. Kept for backward compat with
+     * v0.3.x event lines and bridge code that still stamps event.load.
+     */
+    load?: string;
+    /**
+     * Row-level project ID. Stamped by the bridge before calling appendEvent().
+     */
+    projectId?: string;
+    /**
+     * Row-level build ID. Stamped by the bridge.
+     */
+    buildId?: string;
+    /**
+     * Row-level visitor ID. Stamped by the bridge from the registered peer
+     * or the frame's own `visitorId`. Lets agents filter timeline by
+     * "everything from this user" without join lookups.
+     */
+    visitorId?: string;
+    /** Event payload — structure depends on `t`. */
+    d?: unknown;
+}
+export interface ProjectMeta {
+    id: string;
+    createdAt: number;
+    lastActiveAt: number;
+    parentProjectId?: string;
+    displayName?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Per-build metadata. Lives at projects/{projectId}/builds/{buildId}/meta.json.
+ */
+export interface BuildMeta {
+    id: string;
+    projectId: string;
+    builtAt: number;
+    gitSha?: string;
+    gitDirty?: boolean;
+    sourceDigest?: string;
+    nodeVersion?: string;
+    /** 'vite' | 'webpack' | 'esbuild' | 'rspack' | … */
+    bundler?: string;
+    bundlerVersion?: string;
+    /** Timestamp when this build's dev server was closed. */
+    endedAt?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Node in a project tree returned by `getProjectTree`.
+ */
+export interface ProjectTreeNode {
+    id: string;
+    displayName?: string;
+    tags?: string[];
+    children: ProjectTreeNode[];
+}
+/**
+ * Per-tab metadata. Lives at tabs/{tabId}/meta.json.
+ * A tab spans multiple sessions and may host multiple projects.
+ */
+export interface TabMeta {
+    id: string;
+    userAgent?: string;
+    connectedAt: number;
+    disconnectedAt?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Per-session (pageload) metadata. Lives at sessions/{sessionId}/meta.json.
+ * A session = one pageload. Multiple projects/iframes may participate
+ * (they share sessionId via tryInheritFromParent).
+ */
+export interface SessionMeta {
+    /** sessionId generated by the runtime (shared across same-origin iframes). */
+    id: string;
+    tabId: string;
+    startedAt: number;
+    endedAt?: number;
+    url?: string;
+    title?: string;
+    referrer?: string;
+    userAgent?: string;
+    /**
+     * Every (projectId, buildId) pair that participated in this pageload.
+     * Merge semantics: new participants are appended on each upsertSession call.
+     */
+    participants: Array<{
+        projectId: string;
+        buildId?: string;
+        joinedAt: number;
+    }>;
+    initial?: {
+        viewport?: {
+            w: number;
+            h: number;
+            dpr: number;
+        };
+        storageKeys?: {
+            local?: number;
+            session?: number;
+            cookie?: number;
+        };
+        storageTruncated?: boolean;
+    };
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Per-visitor identity. Lives at visitors/{visitorId}/meta.json. Stitches a
+ * user's activity across pageloads / refreshes / tabs.
+ */
+export interface VisitorMeta {
+    /** visitorId — anonymous UUID persisted in browser localStorage. */
+    id: string;
+    /** App-supplied identifier (latest non-empty value wins). */
+    userId?: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    /** Distinct sessions (pageloads) attributed to this visitor. */
+    sessionCount: number;
+    /** LRU-capped list of distinct tabIds seen (max 50). */
+    tabIds: string[];
+    /** Distinct projects this visitor has touched (max 50). */
+    projectIds: string[];
+    /** Last-seen environment snapshot. */
+    lastEnv?: VisitorEnv;
+}
+export interface TailOptions {
+    /** Number of lines to return from the end. Default 50. */
+    n?: number;
+    /** Filter by event type(s). */
+    type?: EventType | EventType[];
+    /** Only return events after this timestamp. */
+    since?: number;
+    /** Only return events before this timestamp. */
+    until?: number;
+    /** Filter by projectId (useful for multi-project session timelines). */
+    projectId?: string;
+}
+export interface SearchOptions {
+    /** Filter by event type(s). */
+    type?: EventType | EventType[];
+    /** Max results. Default 50. */
+    limit?: number;
+}
+export interface RecordingChunkSummary {
+    chunkId: string;
+    tabId: string;
+    startTs: number;
+    endTs: number;
+    eventCount: number;
+}
+export interface RecordingChunk extends RecordingChunkSummary {
+    events: unknown[];
+}
+/**
+ * Metadata for a saved replay export.
+ */
+export interface ReplayExportMeta {
+    exportId: string;
+    projectId: string;
+    sessionId: string;
+    tabId?: string;
+    label?: string;
+    since: number;
+    until: number;
+    startTs: number;
+    endTs: number;
+    chunkCount: number;
+    eventCount: number;
+    bytes: number;
+    createdAt: number;
+}
+export interface SessionSummary {
+    session: SessionMeta;
+    counts: Partial<Record<EventType, number>>;
+    lastError?: StoreEvent;
+    lastActivity?: number;
+    tabs: string[];
+}
+export interface RetentionPolicy {
+    /** Delete sessions older than this many days. Default 7. */
+    maxAgeDays?: number;
+    /** Keep at most this many sessions globally. Default 200. */
+    maxSessions?: number;
+    /** Delete recording.jsonl files older than this many days. Default 3. */
+    recordingRetentionDays?: number;
+    /** Keep at most this many recording chunks per session. */
+    maxRecordingChunksPerSession?: number;
+    /** Keep at most this many bytes of recording data per session. */
+    maxRecordingBytesPerSession?: number;
+    /** Prefer keeping chunks that overlap rrweb markers when trimming. */
+    preserveMarkedChunks?: boolean;
+    /** Keep at most this many replay exports per project. Default 50. */
+    maxExportsPerProject?: number;
+    /** Keep at most this many bytes of replay exports per project. Default 200MB. */
+    maxExportBytesPerProject?: number;
+    /** Keep at most this many BuildMeta records per project. Default 100. */
+    maxBuildsPerProject?: number;
+    /** @deprecated Use maxSessions. */
+    maxSessionsPerProject?: number;
+    /** @deprecated Use maxRecordingChunksPerSession. */
+    maxRecordingChunksPerTab?: number;
+    /** @deprecated Use maxRecordingBytesPerSession. */
+    maxRecordingBytesPerTab?: number;
+}
+export interface PurgeResult {
+    sessionsDeleted: number;
+    recordingsDeleted: number;
+    exportsDeleted: number;
+    buildsDeleted?: number;
+    bytesFreed: number;
+}
+export interface ITaskStore {
+    loadTasks(projectId: string): Task[];
+    saveTasks(projectId: string, tasks: Task[]): void;
+}
+export interface MemoryEntry {
+    key: string;
+    value: string;
+    updatedAt: number;
+}
+export interface IMemoryStore {
+    get(projectId: string, key: string): MemoryEntry | undefined;
+    set(projectId: string, key: string, value: string): MemoryEntry;
+    delete(projectId: string, key: string): boolean;
+    list(projectId: string): MemoryEntry[];
+}
+export interface IStore {
+    /**
+     * Open a new build (dev server start / prod build). Returns buildId.
+     * Writes projects/{projectId}/builds/{buildId}/meta.json.
+     * (Replaces openSession() from v0.3.x)
+     */
+    openBuild(projectId: string, patch?: Partial<Omit<BuildMeta, 'id' | 'projectId' | 'builtAt'>>): string;
+    /**
+     * Mark a build as ended.
+     * (Replaces closeSession() for build-plugin connections from v0.3.x)
+     */
+    closeBuild(buildId: string, closedAt?: number): void;
+    /**
+     * Write or update tab metadata at tabs/{tabId}/meta.json.
+     * Merge semantics: caller-provided fields overwrite, others preserved.
+     */
+    upsertTab(tabId: string, patch: Partial<Omit<TabMeta, 'id'>>): TabMeta;
+    /** Get tab metadata. */
+    getTab(tabId: string): TabMeta | undefined;
+    /**
+     * Mark a tab as disconnected.
+     * New signature: (tabId, disconnectedAt?) — no sessionId param.
+     */
+    closeTab(tabId: string, disconnectedAt?: number): void;
+    /**
+     * Open or update a session (one pageload). Writes sessions/{sessionId}/meta.json.
+     * participants list is extended (not replaced) on each call.
+     * (Replaces openLoad() from v0.3.x)
+     */
+    upsertSession(sessionId: string, meta: Partial<Omit<SessionMeta, 'id'>> & {
+        tabId: string;
+        startedAt: number;
+    }): SessionMeta;
+    /**
+     * Mark a session as ended.
+     * (Replaces closeLatestLoad() from v0.3.x)
+     */
+    closeSession(sessionId: string, endedAt?: number): void;
+    /** Get session metadata. */
+    getSession(sessionId: string): SessionMeta | undefined;
+    /**
+     * List sessions by recency.
+     * New signature: opts object with optional tabId / projectId / buildId / limit.
+     * (Replaces listSessions(projectId, limit?) from v0.3.x)
+     */
+    listSessions(opts?: {
+        tabId?: string;
+        projectId?: string;
+        buildId?: string;
+        limit?: number;
+    }): SessionMeta[];
+    /**
+     * Append a single event to sessions/{sessionId}/timeline.jsonl.
+     * event.projectId and event.buildId should be pre-stamped by the bridge.
+     * (Replaces append(sessionId=buildId, event, tabId?) from v0.3.x)
+     */
+    appendEvent(sessionId: string, event: StoreEvent): void;
+    /**
+     * Append a batch of events.
+     * (Replaces appendBatch() from v0.3.x)
+     */
+    appendEventBatch(sessionId: string, events: StoreEvent[]): void;
+    /**
+     * Append an rrweb recording chunk to sessions/{sessionId}/recording.jsonl.
+     * (Replaces appendRecording(sessionId, tabId, chunk, loadId?) from v0.3.x)
+     */
+    appendRecording(sessionId: string, chunk: unknown): void;
+    /** Write a project-level note. */
+    writeNote(projectId: string, key: string, value: string): void;
+    /**
+     * Upsert project metadata. `id` and `createdAt` are never overwritten.
+     * Throws if `patch.parentProjectId` would create a cycle.
+     */
+    upsertProject(projectId: string, patch: Partial<Omit<ProjectMeta, 'id' | 'createdAt'>>): ProjectMeta;
+    /** Read a single project's metadata. */
+    getProject(projectId: string): ProjectMeta | undefined;
+    /** List all known projects. */
+    listProjects(): ProjectMeta[];
+    /** Upsert build metadata. Creates the project dir if missing. */
+    upsertBuild(projectId: string, buildId: string, patch: Partial<Omit<BuildMeta, 'id' | 'projectId'>>): BuildMeta;
+    /** Read a single build's metadata. */
+    getBuild(projectId: string, buildId: string): BuildMeta | undefined;
+    /** List builds for a project, newest first. */
+    listBuilds(projectId: string, limit?: number): BuildMeta[];
+    /** Get a forest (or sub-tree from `rootId`) from parentProjectId links. */
+    getProjectTree(rootId?: string): ProjectTreeNode[];
+    /**
+     * Upsert visitor metadata. Merges with existing meta:
+     *   - `firstSeenAt` preserved; `lastSeenAt` advances
+     *   - `sessionCount` increments when caller passes `incrementSession: true`
+     *   - `tabIds` / `projectIds` deduped and LRU-capped at 50
+     *   - `userId` overwritten if patch carries a non-empty value
+     *   - `lastEnv` overwritten if patch carries one
+     */
+    upsertVisitor(visitorId: string, patch: {
+        userId?: string;
+        seenAt?: number;
+        incrementSession?: boolean;
+        addTabId?: string;
+        addProjectId?: string;
+        lastEnv?: VisitorEnv;
+    }): VisitorMeta;
+    /** Read a single visitor's metadata. */
+    getVisitor(visitorId: string): VisitorMeta | undefined;
+    /** List known visitors, newest lastSeenAt first. */
+    listVisitors(opts?: {
+        projectId?: string;
+        limit?: number;
+    }): VisitorMeta[];
+    /**
+     * Read the last N events from a session timeline.
+     * New signature: no tabId param (tab is implicit per session).
+     */
+    tail(sessionId: string, opts?: TailOptions): StoreEvent[];
+    /** Search events in a session timeline by substring match. */
+    search(sessionId: string, query: string, opts?: SearchOptions): StoreEvent[];
+    /** List recording chunks for a session. */
+    listRecordings(sessionId: string): RecordingChunkSummary[];
+    /** Return recording chunks overlapping the requested time window. */
+    sliceRecordings(sessionId: string, since: number, until: number): RecordingChunk[];
+    /** Persist a replay export. */
+    writeExport(input: {
+        sessionId: string;
+        tabId?: string;
+        since: number;
+        until: number;
+        label?: string;
+        events: unknown[];
+        startTs: number;
+        endTs: number;
+        chunkCount: number;
+    }): ReplayExportMeta;
+    /** Read export metadata by id. */
+    getExport(exportId: string): ReplayExportMeta | undefined;
+    /** Read the raw events array for an export. */
+    readExportEvents(exportId: string): unknown[] | undefined;
+    /** List exports for a project, newest first. */
+    listExports(projectId: string, limit?: number): ReplayExportMeta[];
+    /** Get a summary of a session (counts, last error, etc.). */
+    summary(sessionId: string): SessionSummary;
+    /** Read project notes. */
+    listNotes(projectId: string): Array<{
+        key: string;
+        value: string;
+        ts: number;
+    }>;
+    /** Delete old sessions and recordings according to retention policy. */
+    purge(policy?: RetentionPolicy): PurgeResult;
+    /** Close any open file handles. */
+    close(): void | Promise<void>;
+}

package/dist/store/types.js

@@ -0,0 +1,19 @@
+/**
+ * Store types — the public interface for the JSONL-based persistence layer.
+ *
+ * v0.4.0 layout (new, flat):
+ *   {dataDir}/projects/{projectId}/meta.json
+ *   {dataDir}/projects/{projectId}/tasks.json
+ *   {dataDir}/projects/{projectId}/memory.json
+ *   {dataDir}/projects/{projectId}/notes.jsonl
+ *   {dataDir}/projects/{projectId}/builds/{buildId}/meta.json
+ *   {dataDir}/tabs/{tabId}/meta.json
+ *   {dataDir}/sessions/{sessionId}/meta.json       ← one per pageload
+ *   {dataDir}/sessions/{sessionId}/timeline.jsonl  ← mixed parent+child events
+ *   {dataDir}/sessions/{sessionId}/recording.jsonl ← rrweb chunks
+ *   {dataDir}/visitors/{visitorId}/meta.json       ← per-browser identity (0.5+)
+ *
+ * Legacy layout (v0.3.x, read-only fallback — daemon warns on startup):
+ *   {dataDir}/{projectId}/sessions/{buildId}/tabs/{tabId}/...
+ */
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@harness-fe/mcp-server",
+  "version": "3.0.1",
+  "description": "Unified MCP daemon: stdio MCP for AI agents + WS bridge for Vite plugin and runtime client.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Morphicai/harness-fe.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/Morphicai/harness-fe#readme",
+  "bugs": {
+    "url": "https://github.com/Morphicai/harness-fe/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "harness-fe": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "rrweb-player": "1.0.0-alpha.4",
+    "ws": "^8.18.0",
+    "zod": "^4.4.3",
+    "@harness-fe/protocol": "3.0.0",
+    "@harness-fe/dashboard-ui": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "fast-check": "^3.22.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "watch": "tsc --watch --preserveWatchOutput",
+    "start": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/auth.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import type { IncomingMessage } from 'node:http';
+import {
+    extractToken,
+    isAuthEnabled,
+    isAuthorized,
+    verifyToken,
+} from './auth.js';
+
+function fakeReq(init: { headers?: Record<string, string>; url?: string }): IncomingMessage {
+    return {
+        headers: init.headers ?? {},
+        url: init.url ?? '/',
+    } as unknown as IncomingMessage;
+}
+
+describe('auth: isAuthEnabled', () => {
+    it('disabled when no token', () => {
+        expect(isAuthEnabled({})).toBe(false);
+        expect(isAuthEnabled({ token: '' })).toBe(false);
+    });
+    it('enabled with token', () => {
+        expect(isAuthEnabled({ token: 'x' })).toBe(true);
+    });
+});
+
+describe('auth: extractToken', () => {
+    it('reads Authorization: Bearer …', () => {
+        const req = fakeReq({ headers: { authorization: 'Bearer my-token' } });
+        expect(extractToken(req)).toBe('my-token');
+    });
+    it('reads cookie harness_fe_token=…', () => {
+        const req = fakeReq({ headers: { cookie: 'other=1; harness_fe_token=cookie-tok; bar=2' } });
+        expect(extractToken(req)).toBe('cookie-tok');
+    });
+    it('reads ?token=… query string', () => {
+        const req = fakeReq({ url: '/dashboard?foo=1&token=qs-tok&bar=2' });
+        expect(extractToken(req)).toBe('qs-tok');
+    });
+    it('reads WS subprotocol harness-fe.token.…', () => {
+        const req = fakeReq({
+            headers: { 'sec-websocket-protocol': 'json, harness-fe.token.ws-tok' },
+        });
+        expect(extractToken(req)).toBe('ws-tok');
+    });
+    it('header beats cookie beats query', () => {
+        const req = fakeReq({
+            headers: { authorization: 'Bearer hdr', cookie: 'harness_fe_token=ck' },
+            url: '/?token=qs',
+        });
+        expect(extractToken(req)).toBe('hdr');
+    });
+    it('returns undefined when none provided', () => {
+        expect(extractToken(fakeReq({}))).toBeUndefined();
+    });
+});
+
+describe('auth: verifyToken (timing-safe)', () => {
+    it('matches identical tokens', () => {
+        expect(verifyToken('abc', 'abc')).toBe(true);
+    });
+    it('rejects mismatched tokens', () => {
+        expect(verifyToken('abc', 'abd')).toBe(false);
+    });
+    it('rejects empty/undefined', () => {
+        expect(verifyToken(undefined, 'abc')).toBe(false);
+        expect(verifyToken('', 'abc')).toBe(false);
+        expect(verifyToken('abc', '')).toBe(false);
+    });
+    it('handles different length safely (no throw)', () => {
+        expect(verifyToken('a', 'abcdefg')).toBe(false);
+    });
+});
+
+describe('auth: isAuthorized', () => {
+    it('passes everything when auth disabled', () => {
+        expect(isAuthorized(fakeReq({}), {})).toBe(true);
+    });
+    it('passes valid token via header', () => {
+        const req = fakeReq({ headers: { authorization: 'Bearer s3cret' } });
+        expect(isAuthorized(req, { token: 's3cret' })).toBe(true);
+    });
+    it('rejects missing token when auth enabled', () => {
+        expect(isAuthorized(fakeReq({}), { token: 's3cret' })).toBe(false);
+    });
+    it('rejects wrong token', () => {
+        const req = fakeReq({ headers: { authorization: 'Bearer nope' } });
+        expect(isAuthorized(req, { token: 's3cret' })).toBe(false);
+    });
+});