@diegosouzacdv/jev-browser-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1635,11 +1635,87 @@ proxies publicam exclusivamente a allowlist read-only e reaplicam sanitização
 Prompt Guard em cada resultado. Portanto, ferramentas novas ou mutantes que o
 21st venha a publicar não ficam automaticamente acessíveis ao executor.
 
-Para testes de tela conduzidos por Jev e Playwright, inclusive a instalação do
-MCP Node via GitHub em outros harnesses, consulte
-[`docs/jev-browser-mcp.md`](docs/jev-browser-mcp.md). A escolha entre o browser
-headless do harness e Chrome/Edge visível fica em `config/ui-testing.json`; a
-chave do OpenRouter fica no ambiente do processo.
+### MCP de navegador com Jev e Playwright
+
+O pacote independente `@diegosouzacdv/jev-browser-mcp` conecta qualquer harness
+compatível com MCP por `stdio` ao Jev e ao Playwright. Requer Node.js 22 ou mais
+recente. Instale o navegador do Playwright uma vez para execuções no modo
+`harness`:
+
+```sh
+npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
+```
+
+Registre o servidor MCP no formato aceito pelo seu harness. Exemplo de
+configuração comum:
+
+```json
+{
+  "mcpServers": {
+    "jev-browser": {
+      "command": "npx",
+      "args": ["--yes", "@diegosouzacdv/jev-browser-mcp"],
+      "env": {
+        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
+        "JEV_BROWSER_MODE": "harness"
+      }
+    }
+  }
+}
+```
+
+Configure `OPENROUTER_API_KEY` no secret manager ou no ambiente do processo
+que inicia o harness. Não coloque a chave no JSON. O endpoint e o modelo
+Decisions têm valores padrão no pacote; `JEV_PROVIDER_URL` e `JEV_MODEL` podem
+substituí-los.
+
+Escolha o navegador por variáveis de ambiente:
+
+- `JEV_BROWSER_MODE=harness` inicia um navegador isolado e sem interface,
+  adequado para testes automatizados e CI.
+- `JEV_BROWSER_MODE=computer` abre o Chrome ou Edge instalado. O MCP usa um
+  perfil persistente próprio; faça login nele uma vez. Não configure o perfil
+  pessoal que já está aberto no computador.
+- `JEV_BROWSER_CHANNEL=chrome` ou `msedge` escolhe o navegador.
+- `JEV_BROWSER_PROFILE` define o caminho absoluto do perfil persistente no
+  modo `computer`.
+
+Para um fluxo conhecido, o agente do harness consulta o cenário e os critérios
+de aceitação no projeto e chama `run_browser_flow` uma vez. Informe o objetivo,
+a URL inicial, o resultado esperado e planos candidatos declarativos. O Jev
+escolhe um dos planos com base no snapshot acessível da página; o MCP executa
+os passos e confere se o resultado esperado apareceu. Exemplo resumido:
+
+```json
+{
+  "flow": "Adicionar o produto ao carrinho",
+  "initial_url": "http://127.0.0.1:4173/products/coffee",
+  "expected_outcome": "Coffee added to cart",
+  "candidate_plans": {
+    "add_product": {
+      "description": "Adicionar o produto visível ao carrinho",
+      "steps": [
+        {"action": "click", "role": "button", "name": "Add to cart"},
+        {"action": "wait_for_text", "text": "Coffee added to cart"}
+      ]
+    }
+  }
+}
+```
+
+O servidor também oferece `choose_next_action` para exploração passo a passo;
+esse modo exige chamadas separadas do harness e costuma ser mais lento. Os
+planos aceitam ações limitadas como clique por papel e nome acessível,
+preenchimento, espera por texto, rolagem e reação idempotente a um comentário
+único. Não aceitam JavaScript arbitrário, coordenadas nem seletores livres.
+Valores digitados ficam no Playwright e são removidos do conteúdo enviado ao
+Jev. Não coloque senhas, tokens ou outros segredos na descrição do fluxo ou
+nos critérios.
+
+A resposta informa o status, o plano escolhido, as ações executadas, a captura
+final e se o resultado esperado foi confirmado. Consulte o [guia completo do
+MCP Jev Browser](docs/jev-browser-mcp.md) para schemas, limites, tempos e
+detalhes de segurança.
 
 O sidecar PostgreSQL de teste pode ser validado localmente com:
 

package/docs/jev-browser-mcp.md

@@ -1,193 +0,0 @@
-# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegosouzacdv/jev-browser-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Portable MCP server for bounded Playwright screen flows selected by Jev",
   "license": "MIT",
   "repository": {