convez.ai
MCP ServerDesenvolvimento WebIntermediário
zigrivers

Surface

zigrivers/surface

Auditoria de UI com verificação mensurável + análise de IA local

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server e CLI para auditoria de UIs web em execução, combinando verificações mensuráveis com análise assistida por IA. Detecta problemas de interface, explica achados e verifica correções localmente, sem enviar dados capturados para servidores externos.

Instalação

$npx convez-ai zigrivers/surface

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
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
v0.2.4
Issues abertas
0
Contribuidores
1

Casos de uso

  • Detectar problemas visuais e de acessibilidade em aplicações web rodando
  • Validar correções de UI antes de deploy com QA automatizado
  • Executar fluxos de browser QA determinísticos e controlados em CI/CD

Veredito

Ferramenta robusta para QA de UI que une medições determinísticas com capacidades de modelo, mantendo privacidade local. Excelente para times que precisam validar UIs antes de release com rigor técnico e automatização.

README

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

Surface

Surface is a local-first CLI and MCP server for auditing built, running web UIs. It combines measured checks, deterministic local state, and optional model-assisted review so agents can find UI issues, explain them, and verify fixes without sending captured UI data anywhere by default.

Install

npm install --global @zigrivers/surface
surface --help

Run without installing:

npx @zigrivers/surface --help

Homebrew installation is available through the zigrivers/surface tap:

brew tap zigrivers/surface
brew install surface

Local Development

corepack enable
pnpm install
pnpm run check

Build and link the CLI locally:

pnpm --filter @zigrivers/surface build
pnpm --filter @zigrivers/surface exec npm link
surface --help

If npm link reports that surface already exists because Homebrew or another global install owns the binary, avoid overwriting that package-manager-owned file unless you intend to replace it. For a one-off local smoke test, run the built CLI directly:

node packages/cli/dist/index.js --help

Browser QA

Surface includes agent-led browser QA powered by agent-browser. Use it when you want an agent to run reviewed browser flows, explore a target within policy limits, collect redacted evidence, replay candidate findings, and make release gates aware of browser-flow failures.

Run QA against the default local target:

surface qa --localhost --explore --task "complete checkout"

Run a reviewed flow file against a custom local port:

surface flow run surface-flows/checkout.yml --url http://localhost:5173

Apply an action policy to allow only the browser actions, origins, routes, fixture accounts, and teardown contracts that are safe for the target:

surface qa --url https://app.example.com \
  --flows "surface-flows/*.yml" \
  --action-policy .surface/qa/action-policy.json

Use reviewed flow results in CI gates:

surface gate --ci --with-flows --url http://localhost:5173

Primary browser QA commands:

CommandPurpose
surface qaRun agent-led QA over a target, optional reviewed flows, and bounded exploration
surface flow run <flow.yml>Run deterministic source-controlled browser QA flows
surface evidence <ref>Read redacted browser QA evidence metadata
surface replay <ref>Replay a browser QA finding or candidate
surface report qa --run <qaRunId>Render QA reports as Markdown, JSON, or manifest output
surface gate --with-flowsInclude verified browser QA flow results in the quality gate

Safety defaults are intentionally strict:

  • Action policies gate destructive or browser-mutating behavior, including payment, account, save, delete, upload, submit, and externally visible actions.
  • Resolved secrets must not be passed through argv, logs, traces, serialized step payloads, or artifacts.
  • Browser QA state and evidence are stored under .surface/qa.
  • --localhost is a boolean shortcut for http://localhost:3000; use --url or --target for custom ports.

For deeper implementation details, see docs/superpowers/specs/2026-06-08-browser-qa-orchestrator-design.md and docs/superpowers/plans/2026-06-08-browser-qa-orchestrator-implementation.md.

Model Fallback

Surface audits stay measured-only by default. When you explicitly opt in, surface audit can reuse authenticated subscription CLIs for judged synthesis without requiring project API keys.

Run a one-off audit through direct subscription providers:

surface audit --url http://localhost:5173 \
  --model-fallback direct \
  --model-channels claude,gemini \
  --model-depth 3

Let Surface try direct providers first and report compatible MMR fallback availability if direct providers cannot run:

surface audit --url http://localhost:5173 --model-fallback auto

Screenshot egress is separate from model fallback consent. Binary screenshots are blocked for subscription-backed providers in this release; use --model-screenshots redacted-only only when you want redacted screenshot metadata considered alongside text artifacts.

Primary model fallback controls:

ControlPurpose
--model-fallback off|direct|mmr|autoSelect measured-only, direct CLI, MMR-only, or direct-then-MMR behavior
--model-channel <id>Add a direct subscription channel; repeatable
--model-channels <ids>Set comma-separated direct subscription channel order
--model-depth <1-5>Control judged synthesis depth and reconciliation
--model-screenshots blocked|redacted-onlyKeep screenshots blocked or permit redacted screenshot metadata
surface cleanup model-egressRemove persisted model egress artifacts from the Surface state directory

BYO-key and local model providers still take precedence over subscription fallback when configured. MMR is a fallback boundary only when a compatible Surface audit capability is available; the current diff-shaped MMR review flow is reported as unavailable instead of receiving captured UI artifacts.

Reliability and State Safety

Surface persists audit, gate, browser QA, and verdict records through a durable local state store. Recent releases tighten those paths so state transitions are atomic, canonical durable fields are validated before persistence, and CLI/MCP verdict writes produce the same canonical records.

Capture and browser automation failures are also sanitized before they reach machine-readable error envelopes. Unsafe agent-browser command details are replaced with redacted context, keeping raw capture output and command failure payloads out of logs and artifacts.

The 0.2.3 release also aligns live agent-browser computed-style artifacts with the visual hierarchy and responsiveness lenses, honors requested capture configuration through surface capture, and projects completed or failed pipeline runs through surface status and surface next.

Packages

PackagePurpose
@zigrivers/surfaceCLI package; publishes the surface binary
@zigrivers/surface-coreCore schemas, state, scoring, and orchestration
@zigrivers/surface-mcpMCP server adapter
@zigrivers/surface-groundingMeasured grounding tools
@zigrivers/surface-adapter-agnosticFramework-agnostic HTML adapter
@zigrivers/surface-adapter-reactReact adapter
@zigrivers/surface-adapter-svelteSvelte adapter
@zigrivers/surface-adapter-vueVue adapter

Release Checks

Release preparation is local-first to avoid routine GitHub Actions usage:

pnpm run check
pnpm run release:verify

The GitHub release workflow is manual and intended only for release publication, primarily to support npm trusted publishing and provenance.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados