@diegosouzacdv/jev-browser-mcp 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/jev-browser-mcp.md +192 -0
- package/package.json +1 -1
package/docs/jev-browser-mcp.md
CHANGED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# Automação de tela com Jev e Playwright
|
|
2
|
+
|
|
3
|
+
## Instalar em outros harnesses com npm/npx
|
|
4
|
+
|
|
5
|
+
O repositório também contém um pacote Node independente do harness. Ele fala
|
|
6
|
+
MCP por `stdio`, executa o Playwright no mesmo processo e pode ser iniciado por
|
|
7
|
+
qualquer harness que aceite `command` e `args` para um servidor MCP. O pacote
|
|
8
|
+
usa o mesmo `config/ui-testing.json` deste repositório; não precisa instalar o
|
|
9
|
+
Python do orquestrador.
|
|
10
|
+
|
|
11
|
+
Instale a versão publicada do npm diretamente no harness. Para fixar uma
|
|
12
|
+
versão em produção, use o número explícito no argumento do pacote:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{
|
|
16
|
+
"mcpServers": {
|
|
17
|
+
"jev-browser": {
|
|
18
|
+
"command": "npx",
|
|
19
|
+
"args": ["--yes", "@diegosouzacdv/jev-browser-mcp@0.1.1"],
|
|
20
|
+
"env": {
|
|
21
|
+
"OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
|
|
22
|
+
"JEV_BROWSER_MODE": "harness"
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
O formato de interpolação de variáveis varia por harness. Injete a chave por
|
|
30
|
+
um secret manager ou pelo ambiente do processo; não grave a chave no arquivo
|
|
31
|
+
de configuração. Para instalar no projeto Node do próprio harness:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
npm install @diegosouzacdv/jev-browser-mcp
|
|
35
|
+
npx --yes @diegosouzacdv/jev-browser-mcp --install-browser
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
No modo `harness`, a instalação baixa uma vez o Chrome/Edge que o Playwright
|
|
39
|
+
controlará. No modo `computer`, o pacote abre o Chrome/Edge instalado e usa um
|
|
40
|
+
perfil persistente exclusivo em `browser.computer_user_data_dir`; personalize
|
|
41
|
+
as escolhas com `JEV_BROWSER_MODE`, `JEV_BROWSER_CHANNEL` e
|
|
42
|
+
`JEV_BROWSER_PROFILE`. O browser permanece aquecido enquanto o processo MCP
|
|
43
|
+
estiver ativo e fecha quando o harness encerra o processo. `JEV_PROVIDER_URL`
|
|
44
|
+
e `JEV_MODEL` podem substituir os valores centrais; a credencial continua no
|
|
45
|
+
nome de variável declarado em `jev.credential_env`.
|
|
46
|
+
|
|
47
|
+
Uma aplicação Node também pode importar `createJevBrowserServer` por
|
|
48
|
+
`@diegosouzacdv/jev-browser-mcp/server` e conectar o servidor ao transporte MCP
|
|
49
|
+
que ela já utiliza.
|
|
50
|
+
|
|
51
|
+
O pacote é montado pela raiz do repositório, mas o campo `files` do `package.json`
|
|
52
|
+
inclui somente o código Node, a configuração compartilhada e esta documentação
|
|
53
|
+
(além do README que o npm inclui automaticamente). Ele não publica o restante
|
|
54
|
+
do orquestrador. A instalação por npm é a recomendada; use a referência GitHub
|
|
55
|
+
somente quando precisar experimentar uma revisão ainda não publicada.
|
|
56
|
+
|
|
57
|
+
### Contrato do pacote
|
|
58
|
+
|
|
59
|
+
O executável oferece `choose_next_action` e `run_browser_flow`, mantém uma
|
|
60
|
+
sessão do browser por processo e reutiliza essa sessão entre chamadas. O plano
|
|
61
|
+
passado ao Jev continua declarativo e limitado a clique por papel/nome
|
|
62
|
+
acessível, preenchimento de texto, espera por texto, teclas de rolagem e
|
|
63
|
+
reações idempotentes a um comentário único. Não aceita JavaScript, seletores
|
|
64
|
+
livres nem coordenadas. Ele usa a biblioteca Playwright diretamente, sem iniciar
|
|
65
|
+
um segundo servidor MCP do Playwright. O transporte MCP usa `stdio`; toda saída
|
|
66
|
+
de diagnóstico vai para `stderr` para não misturar com JSON-RPC.
|
|
67
|
+
|
|
68
|
+
O modo `computer` grava cookies no perfil exclusivo configurado, e conteúdo da
|
|
69
|
+
página pode conter instruções maliciosas. O Jev recebe a captura acessível com
|
|
70
|
+
uma instrução para tratar esse conteúdo como dado não confiável; não inclua
|
|
71
|
+
segredos no fluxo, no resultado esperado ou nas descrições dos planos.
|
|
72
|
+
|
|
73
|
+
Para um fluxo conhecido, o LLM do harness procura o cenário e os critérios de
|
|
74
|
+
aceitação no projeto e chama `jev_browser.run_browser_flow` com planos
|
|
75
|
+
candidatos declarativos. O MCP abre uma única sessão do Playwright, navega para
|
|
76
|
+
a página inicial, captura o snapshot acessível e pede ao Jev que escolha um
|
|
77
|
+
plano. Em seguida, executa o plano inteiro na mesma sessão e confere o
|
|
78
|
+
resultado esperado na tela.
|
|
79
|
+
|
|
80
|
+
Cada plano pode usar `click`, `type`, `wait_for_text`, teclas aprovadas de
|
|
81
|
+
navegação/rolagem (`PageDown`, `PageUp`, `Home`, `End`, `ArrowDown`, `ArrowUp`)
|
|
82
|
+
e as ações `like_comment` e `unlike_comment`. Cliques e entrada de texto usam
|
|
83
|
+
papel e nome acessível exatos; as ações de reação localizam uma única linha pelo
|
|
84
|
+
autor e texto, inspecionam os controles dentro dela e não clicam novamente
|
|
85
|
+
quando já estão no estado pedido. O rótulo é comparado como palavra inteira
|
|
86
|
+
para que `Curtir` não seja confundido com `Descurtir`. Não há JavaScript
|
|
87
|
+
arbitrário, coordenadas ou seletores livres. Se um alvo estiver
|
|
88
|
+
ausente ou ambíguo, o MCP interrompe o plano e devolve a última evidência para o
|
|
89
|
+
harness decidir como continuar.
|
|
90
|
+
|
|
91
|
+
Exemplo de chamada:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"flow": "Adicionar o produto ao carrinho e confirmar o resumo",
|
|
96
|
+
"initial_url": "http://127.0.0.1:4173/products/coffee",
|
|
97
|
+
"expected_outcome": "Coffee added to cart",
|
|
98
|
+
"candidate_plans": {
|
|
99
|
+
"add_and_confirm": {
|
|
100
|
+
"description": "Adicionar o produto visível ao carrinho e abrir o resumo",
|
|
101
|
+
"steps": [
|
|
102
|
+
{"action": "click", "role": "button", "name": "Add to cart"},
|
|
103
|
+
{"action": "wait_for_text", "text": "Coffee added to cart"},
|
|
104
|
+
{"action": "click", "role": "link", "name": "View cart"}
|
|
105
|
+
]
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
O plano é montado pelo LLM do harness, mas o Jev escolhe qual plano fornecido
|
|
112
|
+
deve executar usando o fluxo e o snapshot inicial. O Jev não cria ações, nomes
|
|
113
|
+
de controles ou valores de formulário. Valores de `type` são usados localmente
|
|
114
|
+
pelo Playwright e são removidos do texto enviado ao provedor e da evidência de
|
|
115
|
+
retorno. Use valores de teste; autenticação deve ficar no perfil de navegador
|
|
116
|
+
configurado.
|
|
117
|
+
|
|
118
|
+
O MCP também mantém `choose_next_action` para fluxos exploratórios em que o
|
|
119
|
+
harness precisa inspecionar e decidir entre ações uma por vez. Esse caminho é
|
|
120
|
+
mais lento porque exige uma nova decisão e uma nova chamada de ferramenta por
|
|
121
|
+
ação; prefira `run_browser_flow` quando os passos esperados puderem ser
|
|
122
|
+
descritos antes da execução.
|
|
123
|
+
|
|
124
|
+
## Configuração
|
|
125
|
+
|
|
126
|
+
Edite `config/ui-testing.json`. O próprio arquivo declara URL e modelo do
|
|
127
|
+
provedor, nome da variável de credencial e limites de entrada e resposta;
|
|
128
|
+
preserve a estrutura completa exigida pelo validador.
|
|
129
|
+
|
|
130
|
+
`browser.mode` aceita `harness` ou `computer`:
|
|
131
|
+
|
|
132
|
+
- `harness` usa Chrome headless e perfil isolado, adequado a execuções do
|
|
133
|
+
harness e CI; o estado de autenticação é descartado ao final da chamada.
|
|
134
|
+
- `computer` abre o Chrome ou Edge instalado em modo visível e usa o diretório
|
|
135
|
+
persistente `browser.computer_user_data_dir`, separado por navegador. Não
|
|
136
|
+
reutiliza o perfil pessoal já aberto. Faça login uma vez nesse perfil; os
|
|
137
|
+
cookies permanecem nele entre chamadas.
|
|
138
|
+
|
|
139
|
+
`browser.max_flow_steps` limita a soma de passos declarados entre os planos e
|
|
140
|
+
`browser.max_text_entry_chars` limita cada valor digitado. O resultado contém
|
|
141
|
+
`status`, o plano escolhido, as ações executadas, a última captura acessível e
|
|
142
|
+
se o critério esperado apareceu. `incomplete` significa que o fluxo não foi
|
|
143
|
+
comprovado; confiança do Jev não substitui essa verificação.
|
|
144
|
+
|
|
145
|
+
`harness_browser` e `computer_browser` aceitam `chrome` ou `msedge`.
|
|
146
|
+
`computer_user_data_dir` deve ficar fora do repositório e conter `{browser}`;
|
|
147
|
+
o diretório persistente armazena dados de login e é resolvido sob a pasta home
|
|
148
|
+
do usuário quando começa com `~`. O Playwright MCP fica desabilitado até
|
|
149
|
+
`ORQUESTRADOR_MCP_PLAYWRIGHT_ENABLED=1` ser configurado no ambiente do harness.
|
|
150
|
+
|
|
151
|
+
Defina o valor secreto na variável indicada por `jev.credential_env`, usando o
|
|
152
|
+
secret manager ou ambiente do processo que inicia o harness. Não grave a chave
|
|
153
|
+
em `config/ui-testing.json`. `provider_url` é o endpoint HTTPS completo da API
|
|
154
|
+
Decisions. O cliente não
|
|
155
|
+
segue redirects e recusa URL com credencial, query string ou fragmento. O Jev
|
|
156
|
+
fica indisponível quando a política de MCP está em modo offline.
|
|
157
|
+
|
|
158
|
+
Na primeira execução, aqueça uma vez o cache local do pacote declarado em
|
|
159
|
+
`browser.playwright_mcp_package` com `npx --yes <pacote> --help`. O MCP inicia
|
|
160
|
+
depois com `--offline`, evitando uma consulta ao registry npm em cada fluxo.
|
|
161
|
+
Quando a versão configurada mudar, aqueça o novo pacote uma vez.
|
|
162
|
+
|
|
163
|
+
## Desempenho e evidência
|
|
164
|
+
|
|
165
|
+
O servidor Python `mcp_servers/jev_browser_server.py` usa uma decisão remota do
|
|
166
|
+
Jev por fluxo. Inclua o fluxo
|
|
167
|
+
completo em um plano candidato para evitar chamadas separadas ao harness; a
|
|
168
|
+
seleção do plano, a navegação e a reação ao comentário ficam em uma chamada MCP.
|
|
169
|
+
A sessão Playwright fecha antes de o MCP Python retornar. O perfil do modo
|
|
170
|
+
`computer` preserva o login para chamadas seguintes; nesse servidor o processo
|
|
171
|
+
e a janela não são reutilizados. O pacote Node mantém o browser aquecido até o
|
|
172
|
+
harness encerrar o processo. O snapshot enviado ao Jev e
|
|
173
|
+
devolvido ao harness remove o rodapé e, se ainda exceder o limite, mantém o
|
|
174
|
+
início e o fim da captura com um marcador de truncamento.
|
|
175
|
+
|
|
176
|
+
A chamada composta aquecida deve ficar dentro da meta de 20 segundos em páginas
|
|
177
|
+
que respondem normalmente; a inicialização fria, páginas lentas, MFA e conteúdo
|
|
178
|
+
sob demanda podem excedê-la. O MCP devolve `total_ms`, `browser_session_ms`,
|
|
179
|
+
`navigation_ms`, `initial_snapshot_ms`, `jev_decision_ms` e `browser_plan_ms`
|
|
180
|
+
para localizar o custo. O teto observado em um fluxo sintético local anterior
|
|
181
|
+
foi 6,411 s; isso não mede o Instagram nem garante o mesmo tempo em outros sites.
|
|
182
|
+
|
|
183
|
+
O snapshot inicial, o fluxo, o resultado esperado e as descrições dos planos
|
|
184
|
+
são enviados ao endpoint Decisions. Os passos e valores de texto dos planos
|
|
185
|
+
não são enviados. Não inclua segredos em `flow`, `expected_outcome` ou nas
|
|
186
|
+
descrições. A resposta retorna o plano escolhido, custo/confiança do provedor
|
|
187
|
+
quando disponíveis e o snapshot final sanitizado. O fluxo só passa quando o
|
|
188
|
+
texto esperado aparece nesse snapshot.
|
|
189
|
+
|
|
190
|
+
Consulte a [introdução do Jev](https://docs.typesafe.ai/introduction) e o
|
|
191
|
+
[tutorial da API Decisions no OpenRouter](https://openrouter.ai/docs/guides/community/jev-tutorial)
|
|
192
|
+
para os tipos de resposta e autenticação.
|