convez.ai
MCP ServerDevOps & InfraestruturaAvançado
Morphicai

Harness-FE

Morphicai/harness-fe

Agente que construiu a app continua assistindo e corrigindo após o deploy

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que mantém agentes de IA conectados a aplicações frontend após o deploy, fornecendo source-mapping, instrumentação de UI com atributos de localização de código, e um gateway bidirecional para monitoramento e correção em tempo real. Inclui SDK de browser, captura server-side para Next.js, e overlay extensível para relatórios de usuários.

Instalação

$npx convez-ai Morphicai/harness-fe

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 1 semana
Versão
v4.7.0
Issues abertas
18
Contribuidores
6

Casos de uso

  • Manter agentes de IA monitorando aplicações frontend em produção
  • Rastrear erros e problemas de UI com mapeamento preciso de código-fonte
  • Capturar logs, erros e eventos de rede para debug remoto assistido por IA
  • Implementar sobreposição interativa para anotações de usuários com screenshots

Veredito

Ferramenta inovadora e bem arquitetada para ligar agentes de IA a ciclos de vida completos de aplicações. Ecossistema maduro com plugins para Vite/Next.js e capacidades enterprise (RBAC, auditoria). Ideal para times que querem autonomia de IA além do build.

README

A tradução para o português deste README ainda está na fila.


Features

  • Source-Aware Instrumentation — Injects data-morphix-loc and data-morphix-comp attributes into JSX / Vue elements (via build plugin OR @harness-fe/react-jsx jsxImportSource), giving AI agents precise file:line:column references for every UI element.
  • MCP Gateway — Connects AI agents (Claude, Cursor, Kiro) to browser + server runtimes via WebSocket / HTTP. Solo mode auto-spawns a shared loopback gateway; team mode (harness --governed) adds RBAC tokens, project→agent binding, and audit. Bidirectional command/event communication with a unified timeline per page-load.
  • Browser Runtime + Overlay — A lightweight browser SDK that captures console / network / errors / DOM (rrweb), exposes an in-page "H" overlay so users can file annotated screenshots (arrow + text on a snapdom-captured PNG), and surfaces a "My reports" view to manage their submissions. The overlay is extensible — add custom action buttons via registerOverlayPlugin to send the current scene/logs to your own system (issue tracker, Slack, webhook). See docs/overlay-plugins.md.
  • Server-Side Capture (Next.js) — @harness-fe/node-runtime collects Server Component errors, Route Handler / Server Action durations, and uncaught Node exceptions. <HarnessScript> is a Server Component that uses React cache() to bind the same sessionId across SSR and the client runtime — one refresh = one sessions/{id}/timeline.jsonl.
  • Edge Runtime Compatible — When Next emits an Edge worker bundle the SDK auto-switches to an HTTP-batch transport (POST /events on the gateway) so Cloudflare Workers / Vercel Edge routes flow into the same gateway as Node routes.
  • Visitor Identity — Anonymous, stable per-browser identifier (localStorage) + optional userId from the app's auth layer. Lets agents build a real user journey across refreshes, tabs, and same-origin iframes.
  • Annotated Feedback Loop — Users file tasks through the overlay; the screenshot's arrow + text annotations are flattened into the PNG so vision models read the annotations directly off pixels. Agents fetch the image via tasks_get_attachment as a native MCP image-content block.
  • Multi-Bundler & Multi-Framework — Stable on Vite + React, Webpack + React, Vite/Webpack + Vue 3, Next.js (App + Pages Router, webpack + Turbopack). Any React 17+ toolchain via @harness-fe/react-jsx jsxImportSource.
  • Zero Production Overhead — All instrumentation, WebSocket / HTTP connections, the overlay, and the Node SDK are gated behind NODE_ENV === 'development'.

How It Works

Harness-FE uses a three-layer architecture to connect AI agents with your running application:

graph LR
    Agent["🤖 AI Agent<br/>(Claude / Kiro)"]
    GW["⚡ Gateway<br/>(harness)"]
    Plugin["🔧 Build Plugin<br/>(Vite / Webpack)"]
    Runtime["🌐 Runtime Client<br/>(Browser)"]

    Agent <-->|stdio or HTTP-MCP| GW
    GW <-->|WebSocket /ws| Plugin
    GW <-->|WebSocket /ws| Runtime
LayerRoleCommunication
Build PluginTransforms source files at dev-time, injecting location and component metadata into JSX/Vue templates. Sends HMR and error events to the gateway.WebSocket /ws → Gateway
Runtime ClientRuns in the browser, captures DOM snapshots, executes commands (click, type, query), and renders annotation overlays.WebSocket /ws → Gateway
GatewayThe central bridge. Exposes tools to AI agents via stdio MCP (solo) or HTTP MCP (team), stores events, and routes commands/events between agents and browser/plugin peers.stdio or HTTP-MCP ↔ AI Agent, WebSocket ↔ Peers

Data flow: Bundler transforms source → Browser renders instrumented DOM → Runtime captures state → Gateway relays to AI Agent → Agent sends commands back through the same path.

Supported Environments

EnvironmentVersionStatus
Vite + React5.x – 7.x✅ Stable (@harness-fe/vite)
Webpack + React5.x✅ Stable (@harness-fe/webpack)
Vite + Vue 35.x – 7.x✅ Stable
Webpack + Vue 35.x✅ Stable
Next.js (App + Pages Router)13+✅ Stable (@harness-fe/next + @harness-fe/react-jsx)
Any React toolchain (Remix, Astro, Turbopack, …)React 17+✅ Stable via @harness-fe/react-jsx jsxImportSource

Getting Started

In a hurry? Jump to the 90-second Quickstart.

Prerequisites

  • Node.js >= 20
  • pnpm >= 8 (recommended), npm >= 9, or yarn >= 1.22

Installation

pnpm (recommended):

pnpm add -D @harness-fe/vite @harness-fe/runtime

npm:

npm install -D @harness-fe/vite @harness-fe/runtime

yarn:

yarn add -D @harness-fe/vite @harness-fe/runtime

Which path are you on?

You are…UseAuthSetup
Solo dev — one app, local@harness-fe/cli mcp over stdio (auto-spawns shared gateway)none (loopback trusted)Quick start below + npx @harness-fe/skill install
A team — many apps sharing one gatewayharness --governed (token + RBAC + project→agent binding)scoped token per agentTeam / governed mode

Whichever path: install the skill first (npx @harness-fe/skill install) so your agent knows how to use harness-fe without you spelling out each tool. See docs/agent-setup.md.

Quick start — Vite + React (6 steps)

  1. Install packages:

    pnpm add -D @harness-fe/vite @harness-fe/runtime
    
  2. Configure Vite — add the plugin to your vite.config.ts:

    import { defineConfig } from 'vite';
    import react from '@vitejs/plugin-react';
    import { harnessFE } from '@harness-fe/vite';
    export default defineConfig({ plugins: [react(), harnessFE()] });
    
  3. Install the agent skill (recommended — do this first) — teach your agent how to drive harness-fe so you don't have to hand-hold it:

    npx @harness-fe/skill install      # auto-detects Claude Code / Cursor / Kiro
    

    The skill drops a curated playbook (mental model + tool catalog + decision flows) into your IDE. Your agent then knows which tool to reach for from a plain-English bug report — you describe the problem, it drives the app.

  4. Wire the MCP server — add harness-fe to your agent's .mcp.json (solo / local — no token, trusted on loopback):

    {
      "mcpServers": {
        "harness-fe": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@harness-fe/cli", "mcp"]
        }
      }
    }
    

    harness mcp auto-spawns a shared gateway on 127.0.0.1:47729 and proxies MCP traffic to it. Multiple IDE windows share the same gateway automatically. Sharing across a team? Use governed mode instead. Phone / second-machine debugging: docs/lan-mode.md.

  5. Start your dev server — pnpm dev.

  6. Describe a problem to your agent — "the increment button does nothing" — and it uses the skill + tools to inspect console/network, locate the source (file:line), fix, and verify. The agent that built it never leaves.

Adopting in legacy Vue projects? See docs/vue2-compat.md — the plugin will never break your build, but you may want to dry-run first to see which files miss out on source-aware tagging.

Embedding in Electron / Tauri / multi-window hosts? See docs/electron.md for how to make every renderer share one sessionId so the agent gets a unified cross-window timeline.

Quick start — Next.js (App or Pages Router)

For Next.js the recommended path is plugin-less (via react-jsx for source tagging + next for SSR session continuity). Two file touches.

  1. Install:

    pnpm add -D @harness-fe/next @harness-fe/react-jsx @harness-fe/runtime @harness-fe/node-runtime
    
  2. tsconfig.json — enable the source-tag JSX runtime:

    { "compilerOptions": { "jsxImportSource": "@harness-fe/react-jsx" } }
    
  3. next.config.mjs — wrap with withHarness():

    import { withHarness } from '@harness-fe/next/config';
    export default withHarness({/* …your config… */}, { projectId: 'my-app' });
    
  4. app/layout.tsx — drop in the Server Component (yes, no 'use client' needed):

    import { HarnessScript } from '@harness-fe/next';
    import { getCurrentUser } from '@/lib/auth';
    export default async function RootLayout({ children }) {
        const user = await getCurrentUser().catch(() => null);
        return (
            <html><body>
                <HarnessScript
                    projectId="my-app"
                    userId={user?.id}
                    buildId={process.env.NEXT_PUBLIC_GIT_SHA}
                />
                {children}
            </body></html>
        );
    }
    
  5. pnpm dev. Two peer connected lines should show in the gateway log per refresh — one role=node-runtime, one role=runtime-client, same sessionId.

Optional — structured logs with @harness-fe/log

For explicit logs (instead of relying on auto-captured console.*), use the isomorphic logger. Same import works in Server Components, Route Handlers, Server Actions, and Client Components — events from both server and client land in the same session timeline.

pnpm add @harness-fe/log
import { log } from '@harness-fe/log';

// Anywhere — Server Component, Route Handler, Client Component, shared util
log.info('Cart loaded', { items: items.length });
log.scope('checkout').warn('Stripe latency high', { ms: latency });
log.error('Webhook failed', err);

Agents can ask "show me all log.warn(...) in this session" because log events are tagged app-log — distinct from auto-captured server-log / browser console. See packages/log/README.md for details.

User feedback (in-page overlay)

When the runtime loads in dev a discreet "H" mark appears bottom-right. Clicking opens the info card. From there users can:

  • Copy snapshot — markdown block with project / build / session / tab / url ready to paste to an agent.
  • Report a problem — picks an element → snapdom captures it with 32 px context → user draws arrows + text → flattened PNG ships as part of a task.submit event. Vision-capable agents read the annotations directly off the pixels.
  • My reports — list of this visitor's tasks across all sessions: status, agent's resolution note, inline edit, copy-for-agent, delete with two-click confirm.

Packages

PackageDescription
@harness-fe/protocolShared types, Zod schemas, message + wire definitions
@harness-fe/coreCore library — WS bridge, event store, recording/replay, caller identity + per-project tenant isolation. No HTTP server; gateway owns all transports.
@harness-fe/gatewayGateway — MCP (stdio + HTTP, per-session), /ws for browser runtime, /console back-office, /admin for governed mode. Embeds core in-process.
@harness-fe/cliharness CLI — solo (harness mcp: auto-spawn shared gateway + stdio proxy), serve (headless shared gateway), governed (harness --governed: RBAC + tokens + audit)
@harness-fe/console-uiReact SPA served at /console — session browser, replay viewer, governance panel (tokens / servers / audit)
@harness-fe/sandboxStandalone browser sandbox + interceptor lib (fetch / xhr / ws / storage / navigation / globals / indexeddb / console / errors). Used by @harness-fe/runtime; also consumable directly
@harness-fe/runtimeBrowser SDK — capture(via @harness-fe/sandbox), rrweb, overlay, "Report a problem", "My reports"
@harness-fe/node-runtimeNode SDK — Server Component / Route Handler / uncaught error capture. Dual transport: WS in Node runtime, HTTP-batch in Edge runtime
@harness-fe/nextNext.js integration — <HarnessScript> server component, withHarness() next-config wrapper
@harness-fe/logIsomorphic structured logger — same log.info/warn/error works in Server Components, Route Handlers, and Client Components; same sessionId everywhere
@harness-fe/react-jsxjsxImportSource runtime — source-aware tagging for ANY React toolchain, no bundler plugin needed
@harness-fe/viteVite plugin
@harness-fe/webpackWebpack plugin
@harness-fe/unpluginCore unplugin (shared by all bundler plugins)
@harness-fe/skill⭐ Start here — curated agent playbook; npx @harness-fe/skill install into Claude Code / Cursor / Kiro so the agent knows how to use harness-fe without you spelling out each tool

Documentation

  • VISION.md — Why this project exists; the three deployment directions that drive the roadmap
  • docs/agent-setup.md — ⭐ Connect your agent: install the skill first, then wire .mcp.json (solo or governed)
  • docs/gateway-team-mode.md — Share one gateway across a team: governed mode, scope RBAC, project→agent binding, audit
  • ARCHITECTURE.md — Package responsibilities, data flow diagrams, sessionId resolution chain, and protocol reference
  • docs/architecture/sandbox.md — The @harness-fe/sandbox lib (browser API patching + interceptor middleware) — design + safety contract + 9-channel matrix
  • ROADMAP.md — Milestones, organised by mission direction
  • docs/troubleshooting.md — Events not showing? sessionId mismatch? Where do timeline files live? Start here
  • CONTRIBUTING.md — Development setup, commit conventions, and PR process

License

MIT © 2026 MorphixAI

Ver o original no GitHub

Bom para

Relacionados