@diegosouzacdv/jev-browser-mcp 0.1.0

package/config/ui-testing.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "browser": {
+    "mode": "harness",
+    "harness_browser": "chrome",
+    "playwright_mcp_package": "@playwright/mcp@0.0.79",
+    "computer_browser": "chrome",
+    "computer_user_data_dir": "~/.cache/orquestrador/jev-browser-{browser}",
+    "max_flow_steps": 24,
+    "max_text_entry_chars": 2000
+  },
+  "jev": {
+    "provider_url": "https://openrouter.ai/api/alpha/decisions",
+    "credential_env": "OPENROUTER_API_KEY",
+    "model": "typesafe/jev-1.13",
+    "request_timeout_seconds": 30,
+    "max_flow_chars": 12000,
+    "max_snapshot_chars": 12000,
+    "max_action_count": 32,
+    "max_action_description_chars": 300,
+    "max_response_bytes": 65536
+  }
+}

package/docs/jev-browser-mcp.md

@@ -0,0 +1,193 @@
+# Automação de tela com Jev e Playwright
+
+## Instalar em outros harnesses com npm/npx
+
+O repositório também contém um pacote Node independente do harness. Ele fala
+MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
+qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
+usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
+Python do orquestrador.
+
+Depois que a versão desejada estiver disponível no GitHub, configure o harness
+para iniciar o pacote pela referência Git. Use uma tag ou SHA publicado para
+fixar a versão:
+
+```json
+{
+  "mcpServers": {
+    "jev-browser": {
+      "command": "npx",
+      "args": ["--yes", "github:diegosouzacdv/orquestrador#<tag-ou-sha>"],
+      "env": {
+        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
+        "JEV_BROWSER_MODE": "harness"
+      }
+    }
+  }
+}
+```
+
+O formato de interpolação de variáveis varia por harness. Injete a chave por
+um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
+de configuração. Para instalar no projeto Node do próprio harness:
+
+```sh
+npm install github:diegosouzacdv/orquestrador#<tag-ou-sha>
+npx jev-browser-mcp --install-browser
+```
+
+No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
+controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
+perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
+as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
+`JEV_BROWSER_PROFILE`. O browser permanece aquecido enquanto o processo MCP
+estiver ativo e fecha quando o harness encerra o processo. `JEV_PROVIDER_URL`
+e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
+nome de variável declarado em `jev.credential_env`.
+
+Uma aplicação Node também pode importar `createJevBrowserServer` por
+`@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
+que ela já utiliza.
+
+O pacote é montado pela raiz do repositório, mas o campo `files` do `package.json`
+inclui somente o código Node, a configuração compartilhada e esta documentação
+(além do README que o npm inclui automaticamente). Ele não publica o restante
+do orquestrador. A instalação por Git passa a ser possível quando a referência
+escolhida tiver sido enviada ao GitHub.
+
+### Contrato do pacote
+
+O executável oferece `choose_next_action` e `run_browser_flow`, mantém uma
+sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
+passado ao Jev continua declarativo e limitado a clique por papel/nome
+acessível, preenchimento de texto, espera por texto, teclas de rolagem e
+reações idempotentes a um comentário único. Não aceita JavaScript, seletores
+livres nem coordenadas. Ele usa a biblioteca Playwright diretamente, sem iniciar
+um segundo servidor MCP do Playwright. O transporte MCP usa `stdio`; toda saída
+de diagnóstico vai para `stderr` para não misturar com JSON-RPC.
+
+O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
+página pode conter instruções maliciosas. O Jev recebe a captura acessível com
+uma instrução para tratar esse conteúdo como dado não confiável; não inclua
+segredos no fluxo, no resultado esperado ou nas descrições dos planos.
+
+Para um fluxo conhecido, o LLM do harness procura o cenário e os critérios de
+aceitação no projeto e chama `jev_browser.run_browser_flow` com planos
+candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
+a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
+plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
+resultado esperado na tela.
+
+Cada plano pode usar `click`, `type`, `wait_for_text`, teclas aprovadas de
+navegação/rolagem (`PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`)
+e as ações `like_comment` e `unlike_comment`. Cliques e entrada de texto usam
+papel e nome acessível exatos; as ações de reação localizam uma única linha pelo
+autor e texto, inspecionam os controles dentro dela e não clicam novamente
+quando já estão no estado pedido. O rótulo é comparado como palavra inteira
+para que `Curtir` não seja confundido com `Descurtir`. Não há JavaScript
+arbitrário, coordenadas ou seletores livres. Se um alvo estiver
+ausente ou ambíguo, o MCP interrompe o plano e devolve a última evidência para o
+harness decidir como continuar.
+
+Exemplo de chamada:
+
+```json
+{
+  "flow": "Adicionar o produto ao carrinho e confirmar o resumo",
+  "initial_url": "http://127.0.0.1:4173/products/coffee",
+  "expected_outcome": "Coffee added to cart",
+  "candidate_plans": {
+    "add_and_confirm": {
+      "description": "Adicionar o produto visível ao carrinho e abrir o resumo",
+      "steps": [
+        {"action": "click", "role": "button", "name": "Add to cart"},
+        {"action": "wait_for_text", "text": "Coffee added to cart"},
+        {"action": "click", "role": "link", "name": "View cart"}
+      ]
+    }
+  }
+}
+```
+
+O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
+deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
+de controles ou valores de formulário. Valores de `type` são usados localmente
+pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
+retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
+configurado.
+
+O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
+harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
+mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
+ação; prefira `run_browser_flow` quando os passos esperados puderem ser
+descritos antes da execução.
+
+## Configuração
+
+Edite `config/ui-testing.json`. O próprio arquivo declara URL e modelo do
+provedor, nome da variável de credencial e limites de entrada e resposta;
+preserve a estrutura completa exigida pelo validador.
+
+`browser.mode` aceita `harness` ou `computer`:
+
+- `harness` usa Chrome headless e perfil isolado, adequado a execuções do
+  harness e CI; o estado de autenticação é descartado ao final da chamada.
+- `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
+  persistente `browser.computer_user_data_dir`, separado por navegador. Não
+  reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
+  cookies permanecem nele entre chamadas.
+
+`browser.max_flow_steps` limita a soma de passos declarados entre os planos e
+`browser.max_text_entry_chars` limita cada valor digitado. O resultado contém
+`status`, o plano escolhido, as ações executadas, a última captura acessível e
+se o critério esperado apareceu. `incomplete` significa que o fluxo não foi
+comprovado; confiança do Jev não substitui essa verificação.
+
+`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
+`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;
+o diretório persistente armazena dados de login e é resolvido sob a pasta home
+do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
+`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
+
+Defina o valor secreto na variável indicada por `jev.credential_env`, usando o
+secret manager ou ambiente do processo que inicia o harness. Não grave a chave
+em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
+Decisions. O cliente não
+segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
+fica indisponível quando a política de MCP está em modo offline.
+
+Na primeira execução, aqueça uma vez o cache local do pacote declarado em
+`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
+depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
+Quando a versão configurada mudar, aqueça o novo pacote uma vez.
+
+## Desempenho e evidência
+
+O servidor Python `mcp_servers/jev_browser_server.py` usa uma decisão remota do
+Jev por fluxo. Inclua o fluxo
+completo em um plano candidato para evitar chamadas separadas ao harness; a
+seleção do plano, a navegação e a reação ao comentário ficam em uma chamada MCP.
+A sessão Playwright fecha antes de o MCP Python retornar. O perfil do modo
+`computer` preserva o login para chamadas seguintes; nesse servidor o processo
+e a janela não são reutilizados. O pacote Node mantém o browser aquecido até o
+harness encerrar o processo. O snapshot enviado ao Jev e
+devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
+início e o fim da captura com um marcador de truncamento.
+
+A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
+que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
+sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
+`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_ms`
+para localizar o custo. O teto observado em um fluxo sintético local anterior
+foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
+
+O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
+são enviados ao endpoint Decisions. Os passos e valores de texto dos planos
+não são enviados. Não inclua segredos em `flow`, `expected_outcome` ou nas
+descrições. A resposta retorna o plano escolhido, custo/confiança do provedor
+quando disponíveis e o snapshot final sanitizado. O fluxo só passa quando o
+texto esperado aparece nesse snapshot.
+
+Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
+[tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)
+para os tipos de resposta e autenticação.

package/mcp_servers/jev-browser-npm/bin/jev-browser-mcp.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+
+const usage = `jev-browser-mcp - Jev + Playwright MCP server
+
+Usage:
+  jev-browser-mcp                 Start the MCP stdio server
+  jev-browser-mcp --install-browser
+                                  Install the configured browser for harness mode
+  jev-browser-mcp --help           Show this help
+
+Configuration is read from config/ui-testing.json. Set OPENROUTER_API_KEY in
+the environment and use JEV_BROWSER_MODE=harness or computer to choose a browser.
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
+    process.stdout.write(usage);
+    return;
+  }
+  const server = await import("../src/server.mjs");
+  if (args.length === 1 && args[0] === "--install-browser") {
+    process.exitCode = await server.installConfiguredBrowser();
+    return;
+  }
+  if (args.length > 0) throw new Error("Unknown argument. Run jev-browser-mcp --help.");
+  server.runStdioServer();
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error?.message || "Could not start jev-browser-mcp"}\n`);
+  process.exitCode = 1;
+});

package/mcp_servers/jev-browser-npm/src/config.mjs

@@ -0,0 +1,162 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const CONFIG_PATH = path.join(PACKAGE_ROOT, "config", "ui-testing.json");
+const CONFIG_KEYS = {
+  root: ["version", "browser", "jev"],
+  browser: [
+    "mode",
+    "harness_browser",
+    "computer_browser",
+    "playwright_mcp_package",
+    "computer_user_data_dir",
+    "max_flow_steps",
+    "max_text_entry_chars",
+  ],
+  jev: [
+    "provider_url",
+    "credential_env",
+    "model",
+    "request_timeout_seconds",
+    "max_flow_chars",
+    "max_snapshot_chars",
+    "max_action_count",
+    "max_action_description_chars",
+    "max_response_bytes",
+  ],
+};
+
+export class JevBrowserError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "JevBrowserError";
+  }
+}
+
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireKeys(value, keys, scope) {
+  if (!record(value)) throw new JevBrowserError(`config/ui-testing.json ${scope} must be an object`);
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+    throw new JevBrowserError(`config/ui-testing.json ${scope} has missing or unsupported fields`);
+  }
+}
+
+function positiveNumber(value, name, integer = false) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0 || (integer && !Number.isInteger(parsed))) {
+    throw new JevBrowserError(`config/ui-testing.json ${name} must be a positive ${integer ? "integer" : "number"}`);
+  }
+  return parsed;
+}
+
+function validProviderUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new JevBrowserError("Jev provider URL must be a valid HTTPS endpoint");
+  }
+  if (parsed.protocol !== "https:" || !parsed.hostname || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new JevBrowserError("Jev provider URL must be HTTPS without credentials, query, or fragment");
+  }
+  return parsed.toString();
+}
+
+function profileDirectory(template, channel, override) {
+  let value = override?.trim() || template.replace("{browser}", channel);
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    value = path.join(homedir(), value.slice(2));
+  }
+  if (!path.isAbsolute(value)) throw new JevBrowserError("JEV_BROWSER_PROFILE must be an absolute path");
+  const resolved = path.resolve(value);
+  const insidePackage = path.relative(PACKAGE_ROOT, resolved);
+  if (insidePackage === "" || (!insidePackage.startsWith(`..${path.sep}`) && insidePackage !== ".." && !path.isAbsolute(insidePackage))) {
+    throw new JevBrowserError("browser profile must be outside the installed package directory");
+  }
+  return resolved;
+}
+
+export function loadSettings({ env = process.env, configPath = CONFIG_PATH } = {}) {
+  let document;
+  try {
+    document = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    throw new JevBrowserError("config/ui-testing.json is unreadable or invalid JSON");
+  }
+  requireKeys(document, CONFIG_KEYS.root, "root");
+  requireKeys(document.browser, CONFIG_KEYS.browser, "browser");
+  requireKeys(document.jev, CONFIG_KEYS.jev, "jev");
+  if (document.version !== 1) throw new JevBrowserError("config/ui-testing.json has an unsupported version");
+
+  if (!new Set(["harness", "computer"]).has(document.browser.mode)) {
+    throw new JevBrowserError("config/ui-testing.json browser.mode must be harness or computer");
+  }
+  if (!new Set(["chrome", "msedge"]).has(document.browser.harness_browser)
+    || !new Set(["chrome", "msedge"]).has(document.browser.computer_browser)) {
+    throw new JevBrowserError("config/ui-testing.json browser channels must be chrome or msedge");
+  }
+  if (typeof document.browser.playwright_mcp_package !== "string"
+    || !/^@playwright\/mcp@\d+\.\d+\.\d+$/.test(document.browser.playwright_mcp_package)) {
+    throw new JevBrowserError("config/ui-testing.json browser.playwright_mcp_package must pin an exact MCP version");
+  }
+  const mode = (env.JEV_BROWSER_MODE || document.browser.mode).trim();
+  if (!new Set(["harness", "computer"]).has(mode)) {
+    throw new JevBrowserError("JEV_BROWSER_MODE must be harness or computer");
+  }
+  const configuredChannel = mode === "harness" ? document.browser.harness_browser : document.browser.computer_browser;
+  const channel = (env.JEV_BROWSER_CHANNEL || configuredChannel).trim();
+  if (!new Set(["chrome", "msedge"]).has(channel)) {
+    throw new JevBrowserError("JEV_BROWSER_CHANNEL must be chrome or msedge");
+  }
+  const profileTemplate = document.browser.computer_user_data_dir;
+  const profileRemainder = typeof profileTemplate === "string" ? profileTemplate.replace("{browser}", "") : "";
+  if (typeof profileTemplate !== "string" || profileTemplate.split("{browser}").length !== 2
+    || profileRemainder.includes("{") || profileRemainder.includes("}")) {
+    throw new JevBrowserError("config/ui-testing.json browser.computer_user_data_dir must contain {browser}");
+  }
+
+  const configuredProviderUrl = validProviderUrl(document.jev.provider_url);
+  const providerUrl = validProviderUrl(env.JEV_PROVIDER_URL?.trim() || configuredProviderUrl);
+  const credentialEnv = String(document.jev.credential_env || "").trim();
+  if (!/^[A-Z][A-Z0-9_]*$/.test(credentialEnv)) {
+    throw new JevBrowserError("config/ui-testing.json jev.credential_env must be an environment variable name");
+  }
+  const configuredModel = String(document.jev.model || "").trim();
+  if (!configuredModel) throw new JevBrowserError("config/ui-testing.json jev.model is required");
+  const model = (env.JEV_MODEL?.trim() || configuredModel).trim();
+  if (!model) throw new JevBrowserError("Jev model must not be empty");
+
+  return Object.freeze({
+    env,
+    browser: Object.freeze({
+      mode,
+      channel,
+      profileDir: profileDirectory(profileTemplate, channel, env.JEV_BROWSER_PROFILE),
+      maxFlowSteps: positiveNumber(document.browser.max_flow_steps, "browser.max_flow_steps", true),
+      maxTextEntryChars: positiveNumber(document.browser.max_text_entry_chars, "browser.max_text_entry_chars", true),
+    }),
+    jev: Object.freeze({
+      providerUrl,
+      credentialEnv,
+      model,
+      requestTimeoutMs: positiveNumber(document.jev.request_timeout_seconds, "jev.request_timeout_seconds") * 1000,
+      maxFlowChars: positiveNumber(document.jev.max_flow_chars, "jev.max_flow_chars", true),
+      maxSnapshotChars: positiveNumber(document.jev.max_snapshot_chars, "jev.max_snapshot_chars", true),
+      maxActionCount: positiveNumber(document.jev.max_action_count, "jev.max_action_count", true),
+      maxActionDescriptionChars: positiveNumber(document.jev.max_action_description_chars, "jev.max_action_description_chars", true),
+      maxResponseBytes: positiveNumber(document.jev.max_response_bytes, "jev.max_response_bytes", true),
+    }),
+  });
+}
+
+export function packageRoot() {
+  return PACKAGE_ROOT;
+}