@harness-fe/mcp-server 3.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MorphixAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Morphicai/harness-fe/main/branding/logo.svg" alt="Harness-FE" width="96" />
+</p>
+
+# @harness-fe/mcp-server
+
+> The MCP daemon for [Harness-FE](https://github.com/Morphicai/harness-fe). Bridges AI agents (Claude, Cursor, Kiro) with running dev servers and browser tabs.
+
+The MCP server exposes tools over **stdio MCP** to AI agents and runs a **WebSocket bridge** for the Vite/Webpack plugin and the browser runtime client. One daemon can serve multiple projects simultaneously.
+
+## Install
+
+```bash
+# Run on demand (recommended)
+npx @harness-fe/mcp-server
+
+# Or install globally
+pnpm add -g @harness-fe/mcp-server
+harness-fe
+```
+
+## Use with Claude Code
+
+Register the daemon as an MCP server in your Claude Code settings:
+
+```jsonc
+{
+    "mcpServers": {
+        "harness-fe": {
+            "command": "npx",
+            "args": ["-y", "@harness-fe/mcp-server"]
+        }
+    }
+}
+```
+
+Cursor, Kiro, and other MCP-compatible clients use the same pattern.
+
+## Multiple daemons (port = identity)
+
+The daemon's identity is its listening port. Same port = same daemon
+= same on-disk store. Different port = independent daemons with
+independent stores.
+
+This means:
+
+- **All IDEs targeting default 47729 share one daemon automatically.**
+  No extra config needed. Cursor + Claude Desktop + Kiro on the same
+  machine see the same sessions, browser tabs, and projects.
+- **Want isolation? Pick a different `--port`.** That's the whole
+  isolation knob.
+
+| Scenario | Config |
+|---|---|
+| Single shared daemon (default) | Nothing extra |
+| One project gets its own daemon | `"args": ["...", "--port", "47730"]` in that IDE's mcp.json |
+| Monorepo: aggregate everything | All IDEs use default port — they pool automatically |
+| Friendly name in banner / dashboard | `"env": { "HARNESS_FE_LABEL": "my-mono" }` (cosmetic only) |
+
+Data lives at `~/.harness/daemons/<port>/data/`. The label is purely
+cosmetic — isolation comes from the port, never the label.
+
+Full guide: [docs/multi-daemon.md](https://github.com/Morphicai/harness-fe/blob/main/docs/multi-daemon.md)
+
+## LAN mode (real-device debugging)
+
+The daemon binds `127.0.0.1` by default. Token is **entirely
+optional** — set one if you want auth, leave it off for a fully open
+daemon. The CLI never refuses to start; binding decisions are yours.
+
+| You want… | Run | Behavior |
+|-----------|-----|----------|
+| Local-only, zero config | `npx @harness-fe/mcp-server` | Loopback, no auth |
+| Local with auth (defense in depth) | `--token <value>` or `HARNESS_FE_TOKEN=<value>` | Loopback, auth required for HTTP / WS |
+| LAN debug (phone, tablet, other host) — open | `--host 0.0.0.0` | LAN-reachable, no auth. Banner warns you. |
+| LAN debug — protected | `--host 0.0.0.0 --token auto` | LAN-reachable, token required. Banner prints the dashboard URL with `?token=` baked in |
+
+The startup banner always prints the dashboard URL. When a token is
+configured, the first browser hit on `?token=…` hands it off to a
+cookie so the visible URL stays clean for the next 30 days. When no
+token is configured, the bare URL works as-is.
+
+Want a remote agent to share the daemon? Mount the MCP HTTP transport:
+
+```bash
+npx @harness-fe/mcp-server --host 0.0.0.0 --mcp-transport http --mcp-path /mcp
+# … with auth:
+npx @harness-fe/mcp-server --host 0.0.0.0 --token auto \
+  --mcp-transport http --mcp-path /mcp
+```
+
+Remote Claude Code / Cursor config:
+
+```jsonc
+// No-auth daemon:
+{ "type": "http", "url": "http://<lan-ip>:47729/mcp" }
+
+// Token-protected daemon:
+{
+  "type": "http",
+  "url": "http://<lan-ip>:47729/mcp",
+  "headers": { "Authorization": "Bearer <token>" }
+}
+```
+
+**Full guide:** [docs/lan-mode.md](https://github.com/Morphicai/harness-fe/blob/main/docs/lan-mode.md)
+
+## All CLI flags
+
+```
+--host <addr>           Bind address (default 127.0.0.1; use 0.0.0.0 for LAN)
+--port <number>         TCP port (default 47729)
+--token <value|auto>    Optional. When set, all HTTP/WS requests must carry it
+                        (header / cookie / query / WS subprotocol). When unset,
+                        auth is disabled entirely.
+--mcp-transport <kind>  stdio (default) | http
+--mcp-path <path>       Default /mcp
+--public-host <addr>    Override the host printed in outbound URLs
+-h, --help
+```
+
+Matching env vars: `HARNESS_FE_HOST`, `HARNESS_FE_PORT`,
+`HARNESS_FE_TOKEN`, `HARNESS_FE_MCP_TRANSPORT`, `HARNESS_FE_MCP_PATH`,
+`HARNESS_FE_HEADLESS`.
+
+## What it exposes
+
+Tools across these domains (see [Architecture](https://github.com/Morphicai/harness-fe/blob/main/ARCHITECTURE.md)):
+
+- **page** — `navigate`, `click`, `type`, `dom_query`, `evaluate`, `screenshot`, …
+- **console / network / errors** — tail and search runtime events
+- **session** — list, replay, slice rrweb recordings
+- **project** — `source`, `where_is`, `module_graph` (source-code intelligence)
+- **tasks** — point-and-task annotation queue
+
+Persistence lives in `~/.harness/` (JSONL event logs + JSON records).
+
+## Docs
+
+- [Root README](https://github.com/Morphicai/harness-fe#readme)
+- [Architecture](https://github.com/Morphicai/harness-fe/blob/main/ARCHITECTURE.md)
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Token-based auth for the bridge's HTTP + WS surfaces.
+ *
+ * Loopback (127.*, localhost, ::1) — auth disabled by default; the daemon
+ * trusts everything that can reach the loopback socket. As soon as the
+ * daemon is bound to a non-loopback host (e.g. 0.0.0.0 for LAN debugging),
+ * the CLI requires a token and this module enforces it on every HTTP route
+ * and WS upgrade.
+ *
+ * Why a single module: dashboard / replay viewer / events handler /
+ * MCP HTTP transport all live behind the same bridge HTTP server. Bridge
+ * wraps requests with `isAuthorized` once, so individual handlers never
+ * see unauthenticated traffic and don't carry auth code.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const DEFAULT_COOKIE_NAME = "harness_fe_token";
+export declare const DEFAULT_LOGIN_PATH = "/__auth";
+export interface AuthOptions {
+    /** Expected token. Empty/undefined disables token auth. */
+    token?: string;
+    /**
+     * Custom authorization predicate. When supplied, runs *instead of* the
+     * token check on every HTTP request and WS upgrade. Synchronous: the
+     * WS upgrade handshake completes inline. For host-injected auth that
+     * needs an async lookup, cache the result in a cookie via the host's
+     * own middleware and have `authorize` read the cookie.
+     */
+    authorize?: (req: IncomingMessage) => boolean;
+    /** Cookie name set after a successful login. Default: harness_fe_token. */
+    cookieName?: string;
+    /** POST path that consumes the login form. Default: /__auth. */
+    loginPath?: string;
+}
+export declare function isAuthEnabled(opts: AuthOptions): boolean;
+/** Pull token from header / cookie / query / WS subprotocol (first match wins). */
+export declare function extractToken(req: IncomingMessage, opts?: AuthOptions): string | undefined;
+/**
+ * Constant-time token compare. Hashing both sides first means we always
+ * compare equal-length buffers, sidestepping the length-leak that a raw
+ * timingSafeEqual on user input would have.
+ */
+export declare function verifyToken(provided: string | undefined, expected: string): boolean;
+/** True if request is allowed (auth disabled, custom predicate accepts, or token matches). */
+export declare function isAuthorized(req: IncomingMessage, opts: AuthOptions): boolean;
+/**
+ * Write a 401 response. Browsers (Accept: text/html) get a minimal login
+ * form they can post the token through; everything else gets JSON.
+ */
+export declare function sendUnauthorized(req: IncomingMessage, res: ServerResponse, opts: AuthOptions): void;
+/**
+ * Handle POST {loginPath}: read form body, verify token, set cookie, 303 → next.
+ */
+export declare function handleLoginPost(req: IncomingMessage, res: ServerResponse, opts: AuthOptions): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,212 @@
+/**
+ * Token-based auth for the bridge's HTTP + WS surfaces.
+ *
+ * Loopback (127.*, localhost, ::1) — auth disabled by default; the daemon
+ * trusts everything that can reach the loopback socket. As soon as the
+ * daemon is bound to a non-loopback host (e.g. 0.0.0.0 for LAN debugging),
+ * the CLI requires a token and this module enforces it on every HTTP route
+ * and WS upgrade.
+ *
+ * Why a single module: dashboard / replay viewer / events handler /
+ * MCP HTTP transport all live behind the same bridge HTTP server. Bridge
+ * wraps requests with `isAuthorized` once, so individual handlers never
+ * see unauthenticated traffic and don't carry auth code.
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+export const DEFAULT_COOKIE_NAME = 'harness_fe_token';
+export const DEFAULT_LOGIN_PATH = '/__auth';
+const WS_SUBPROTOCOL_PREFIX = 'harness-fe.token.';
+export function isAuthEnabled(opts) {
+    return !!(opts.token || opts.authorize);
+}
+/** Pull token from header / cookie / query / WS subprotocol (first match wins). */
+export function extractToken(req, opts = {}) {
+    const auth = req.headers.authorization;
+    if (typeof auth === 'string' && auth.startsWith('Bearer ')) {
+        const v = auth.slice(7).trim();
+        if (v)
+            return v;
+    }
+    const cookieName = opts.cookieName ?? DEFAULT_COOKIE_NAME;
+    const cookies = parseCookieHeader(req.headers.cookie);
+    if (cookies[cookieName])
+        return decodeURIComponent(cookies[cookieName]);
+    const url = req.url ?? '';
+    const qi = url.indexOf('?');
+    if (qi >= 0) {
+        const params = new URLSearchParams(url.slice(qi + 1));
+        const t = params.get('token');
+        if (t)
+            return t;
+    }
+    const subproto = req.headers['sec-websocket-protocol'];
+    if (typeof subproto === 'string') {
+        for (const p of subproto.split(',')) {
+            const trimmed = p.trim();
+            if (trimmed.startsWith(WS_SUBPROTOCOL_PREFIX)) {
+                return trimmed.slice(WS_SUBPROTOCOL_PREFIX.length);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Constant-time token compare. Hashing both sides first means we always
+ * compare equal-length buffers, sidestepping the length-leak that a raw
+ * timingSafeEqual on user input would have.
+ */
+export function verifyToken(provided, expected) {
+    if (!provided || !expected)
+        return false;
+    const a = createHash('sha256').update(provided).digest();
+    const b = createHash('sha256').update(expected).digest();
+    return timingSafeEqual(a, b);
+}
+/** True if request is allowed (auth disabled, custom predicate accepts, or token matches). */
+export function isAuthorized(req, opts) {
+    if (!isAuthEnabled(opts))
+        return true;
+    // Custom predicate wins when supplied. Hosts that embed the daemon pass
+    // their own check here (e.g. JWT verification reading from a cookie).
+    if (opts.authorize)
+        return opts.authorize(req);
+    return verifyToken(extractToken(req, opts), opts.token);
+}
+/**
+ * Write a 401 response. Browsers (Accept: text/html) get a minimal login
+ * form they can post the token through; everything else gets JSON.
+ */
+export function sendUnauthorized(req, res, opts) {
+    // Custom-authorize mode is for host apps that own their own login UX —
+    // the built-in token form is never the right answer there. Always 401
+    // as JSON and let the host redirect.
+    const wantsLoginForm = !opts.authorize;
+    const accept = (req.headers.accept ?? '').toLowerCase();
+    const wantsHtml = accept.includes('text/html') && wantsLoginForm;
+    if (wantsHtml) {
+        res.statusCode = 401;
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        res.end(renderLoginPage(opts, req.url ?? '/'));
+        return;
+    }
+    res.statusCode = 401;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('www-authenticate', 'Bearer realm="harness-fe"');
+    res.end(JSON.stringify({
+        error: 'unauthorized',
+        message: 'Missing or invalid token. Provide Authorization: Bearer <token>, ?token=<token>, or the harness_fe_token cookie.',
+    }));
+}
+/**
+ * Handle POST {loginPath}: read form body, verify token, set cookie, 303 → next.
+ */
+export async function handleLoginPost(req, res, opts) {
+    if (!isAuthEnabled(opts) || opts.authorize) {
+        // Auth disabled, or the host owns auth via a custom predicate — the
+        // built-in login form isn't meaningful here. Redirect home.
+        res.statusCode = 303;
+        res.setHeader('location', '/');
+        res.end();
+        return;
+    }
+    const chunks = [];
+    let total = 0;
+    const MAX = 4096;
+    for await (const c of req) {
+        const buf = c;
+        total += buf.length;
+        if (total > MAX) {
+            res.statusCode = 413;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+            res.end('payload too large');
+            return;
+        }
+        chunks.push(buf);
+    }
+    const body = Buffer.concat(chunks).toString('utf8');
+    const form = new URLSearchParams(body);
+    const token = form.get('token') ?? '';
+    const next = safeNext(form.get('next') ?? '/');
+    if (!verifyToken(token, opts.token)) {
+        res.statusCode = 401;
+        res.setHeader('content-type', 'text/html; charset=utf-8');
+        res.setHeader('cache-control', 'no-store');
+        res.end(renderLoginPage(opts, next, 'Invalid token. Try again.'));
+        return;
+    }
+    const cookieName = opts.cookieName ?? DEFAULT_COOKIE_NAME;
+    // 30 days. HttpOnly so JS can't read it; SameSite=Lax so cross-tab nav works.
+    const cookie = `${cookieName}=${encodeURIComponent(token)}; Path=/; HttpOnly; SameSite=Lax; Max-Age=2592000`;
+    res.statusCode = 303;
+    res.setHeader('set-cookie', cookie);
+    res.setHeader('location', next);
+    res.end();
+}
+/**
+ * Allow only same-origin relative paths as the post-login redirect. Anything
+ * else degrades to "/" so a crafted form can't redirect to an external site.
+ */
+function safeNext(next) {
+    if (typeof next !== 'string')
+        return '/';
+    if (!next.startsWith('/'))
+        return '/';
+    if (next.startsWith('//'))
+        return '/';
+    return next;
+}
+function parseCookieHeader(raw) {
+    if (!raw)
+        return {};
+    const out = {};
+    for (const part of raw.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const k = part.slice(0, eq).trim();
+        const v = part.slice(eq + 1).trim();
+        if (k)
+            out[k] = v;
+    }
+    return out;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => {
+        switch (c) {
+            case '&': return '&amp;';
+            case '<': return '&lt;';
+            case '>': return '&gt;';
+            case '"': return '&quot;';
+            default: return '&#39;';
+        }
+    });
+}
+function renderLoginPage(opts, next, error) {
+    const loginPath = opts.loginPath ?? DEFAULT_LOGIN_PATH;
+    const safeN = escapeHtml(safeNext(next));
+    const errBlock = error
+        ? `<p style="color:#c0392b;margin:0 0 12px">${escapeHtml(error)}</p>`
+        : '';
+    return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>harness-fe — sign in</title>
+<style>
+body{font:14px/1.4 -apple-system,BlinkMacSystemFont,system-ui,sans-serif;background:#fafafa;color:#222;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}
+form{background:#fff;border:1px solid #e5e7eb;border-radius:8px;padding:24px;max-width:360px;width:100%;box-shadow:0 4px 12px rgba(0,0,0,.04)}
+h1{font-size:16px;margin:0 0 12px}
+input[type=password]{display:block;width:100%;box-sizing:border-box;padding:10px;border:1px solid #d1d5db;border-radius:6px;font-size:14px;margin-bottom:12px}
+button{display:block;width:100%;padding:10px;background:#111;color:#fff;border:0;border-radius:6px;font-size:14px;cursor:pointer}
+.muted{color:#666;font-size:12px;margin-top:12px}
+</style></head>
+<body>
+<form method="post" action="${escapeHtml(loginPath)}" autocomplete="off">
+  <h1>harness-fe</h1>
+  ${errBlock}
+  <input type="password" name="token" placeholder="token" autofocus required>
+  <input type="hidden" name="next" value="${safeN}">
+  <button type="submit">Sign in</button>
+  <p class="muted">Paste the token from the daemon startup banner.</p>
+</form>
+</body></html>`;
+}