Debugg AI

Debugg AI — Servidor MCP

Testes de navegador com tecnologia de IA via o Model Context Protocol. Aponte para qualquer URL (ou localhost) e descreva o que testar — um agente de IA navega pelo seu aplicativo e retorna aprovação/reprovação com capturas de tela.

Configuração

Requer Node.js 20.20.0 ou posterior (requisito transitivo do posthog-node@^5.26.0).

Obtenha uma chave de API em debugg.ai e adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Ou com Docker:

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

Ferramentas

O servidor expõe 8 ferramentas: três ferramentas de Navegador mais uma ferramenta baseada em ação por entidade gerenciada. As ferramentas principais são check_app_in_browser (agente de IA completo) e probe_page (sonda de página leve sem LLM). As demais — project, environment, test_suite, test_case, executions — cada uma recebe um discriminador action (ex.: {"action":"list"}) que seleciona a operação. Ações destrutivas delete exigem confirmação (um prompt de elicitação onde suportado, caso contrário confirm: true).

Navegador

check_app_in_browser

Executa um agente de navegador de IA no seu aplicativo. O agente navega, interage e reporta com capturas de tela. URLs de localhost são tuneladas automaticamente via ngrok.

Parâmetro	Tipo	Descrição
description	string obrigatório	O que testar (linguagem natural)
url	string obrigatório	URL de destino — http://localhost:3000 é tunelada automaticamente
environmentId	string	UUID de um ambiente específico
credentialId	string	UUID de uma credencial específica
credentialRole	string	Escolher uma credencial por função (ex.: admin, guest)
username	string	Nome de usuário para login (efêmero — não persistido)
password	string	Senha para login (efêmera — não persistida)
repoName	string	Substituir nome do repositório git detectado automaticamente (ex.: my-org/my-repo)

Uma verificação focada por chamada. O agente tem um orçamento interno de ~25 passos; divida suítes mais amplas em várias chamadas.

Cada execução bem-sucedida retorna um bloco browserSession junto com a captura de tela — URLs S3 pré-assinadas para o HAR capturado (rastreamento completo de rede) e log do console (cada mensagem do console JS). Use-os para detectar loops de refetch, erros de hidratação e outros problemas de tempo de execução que passam em verificações de tipo e testes unitários:

"browserSession": {
  "harUrl": "https://...session_18139.har?X-Amz-...",
  "consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
  "recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
  "harStatus": "downloaded",
  "consoleLogStatus": "downloaded",
  "harRedactionStatus": "redacted",
  "consoleLogRedactionStatus": "redacted"
}

As URLs são S3 pré-assinadas de curta duração — busque novamente a execução pai via executions {action:"get", uuid} para renovar. harStatus / consoleLogStatus desambiguam 'downloaded' (URL acessível), 'not_available' (página não emitiu nada), 'failed' (captura falhou). Em uma execução recente, as URLs geralmente são null porque o upload da captura é assíncrono após o agente terminar — consulte executions {action:"get", uuid: executionId} até o status atingir 'downloaded'. Cabeçalhos de Autorização / Cookie / token/secret/api_key são removidos no lado do servidor antes que os artefatos sejam persistidos.

trigger_crawl

Dispara um rastreamento de agente de navegador no lado do servidor para popular o grafo de conhecimento do projeto. URLs de localhost são tuneladas automaticamente. Retorna {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} com knowledgeGraph.imported === true na ingestão bem-sucedida. O bloco browserSession (URLs de HAR + log do console, mesmo formato acima) também está presente em rastreamentos concluídos.

probe_page

Sonda de página em lote leve sem LLM. Passe de 1 a 20 URLs; cada uma navega, aguarda o carregamento e retorna o estado renderizado — captura de tela + metadados da página + erros estruturados do console + resumo da rede. Sem loop de agente, sem custo de LLM, sem asserções de cenário. Use para verificações do tipo "eu quebrei /settings?", smoke de múltiplas rotas após uma refatoração, varreduras de CI por PR e verificações rápidas de disponibilidade onde o loop de agente de 60-150s do check_app_in_browser é excessivo.

Parâmetro	Tipo	Descrição
targets	array obrigatório	1-20 entradas: [{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	string obrigatório	URL pública ou localhost (tunelada automaticamente)
targets[].waitForLoadState	enum	'load' (padrão) / 'domcontentloaded' / 'networkidle'
targets[].waitForSelector	string	Seletor CSS opcional para aguardar após a navegação
targets[].timeoutMs	number	Tempo limite por URL, 1000-30000 (padrão 10000)
includeHtml	boolean	Retornar HTML bruto em cada resultado (padrão false)
captureScreenshots	boolean	Retornar um PNG por destino (padrão true)

Todo o lote compartilha uma única execução de backend + sessão de navegador + túnel — 5 URLs em uma chamada é drasticamente mais rápido que 5 chamadas paralelas de URL única. O campo error por URL preserva a resiliência do lote: um único destino com falha não faz os outros falharem.

A chave de agregação networkSummary é origin + pathname — loops de refetch (?n=0..4 atingindo repetidamente o mesmo endpoint) colapsam em uma única entrada com a contagem, então /api/poll aparecendo com count: 47 é o sinal acionável de "loop de refetch infinito" que os usuários originalmente solicitaram.

Orçamento de desempenho: <10s para 1 URL, <25s para 20. Porta morta de localhost retorna LocalServerUnreachable em <2s sem consumir uma execução de fluxo de trabalho.

project

Ação	Parâmetros	Resultado
get	{uuid}	Detalhe curado do projeto
list	{q?, page?, pageSize?}	Resumos paginados
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	Projeto criado

A resolução de equipe e repositório é feita por ou uuid ou nome (correspondência exata sem distinção entre maiúsculas e minúsculas; NotFound se nenhum, AmbiguousMatch se múltiplos). Não há update/delete — renomeie ou exclua um projeto pelo aplicativo web DebuggAI.

environment

Ação	Parâmetros	Resultado
get	{uuid, projectUuid?}	Ambiente com credenciais inline (senhas nunca retornadas)
list	{projectUuid?, q?, page?, pageSize?}	Ambientes paginados, cada um com um array de credenciais
create	{name, url, description?, projectUuid?, credentials?}	Ambiente criado (opcionalmente semeia credenciais)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}	Ambiente corrigido; operações de credencial executam remover → atualizar → adicionar
delete	{uuid, projectUuid?, confirm?}	Exclui ambiente (em cascata para credenciais) — requer confirmação

projectUuid é resolvido automaticamente do repositório git quando omitido. Falhas por credencial aparecem em credentialWarnings[] sem bloquear a operação do ambiente.

test_suite

Ação	Parâmetros	Resultado
list	{projectUuid|projectName, search?, page?, pageSize?}	Suítes paginadas com status + taxa de aprovação
create	{name, description, projectUuid|projectName}	Suíte criada
run	{suiteUuid|(suiteName+project), targetUrl?}	Aciona todos os testes de forma assíncrona
results	{suiteUuid|(suiteName+project)}	Suíte + resultados por teste
delete	{suiteUuid|(suiteName+project), confirm?}	Exclusão suave — requer confirmação

test_case

Ação	Parâmetros	Resultado
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	Caso de teste criado (não executado automaticamente)
update	{testUuid, name?, description?, agentTaskDescription?}	Caso de teste corrigido
delete	{testUuid, confirm?}	Exclusão suave — requer confirmação

executions

Ação	Parâmetros	Resultado
get	{uuid}	Detalhe completo (nodeExecutions + estado + errorInfo) + artefatos de captura de tela/gif
list	{status?, projectUuid?, page?, pageSize?}	Resumos paginados

404 do backend aparece como isError: true com {error: 'NotFound', message, uuid}. Credenciais são sempre retornadas sem senhas.

Paginação

Cada resposta em modo de filtro é paginada. Formato da resposta:

{
  "filter": { "...echoed query params..." },
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

Passe page opcional (indexado em 1, padrão 1) e pageSize (padrão 20, máximo 200; valores excessivos são limitados). Nenhuma resposta é truncada silenciosamente.

Recursos

Junto com as ferramentas, o servidor expõe as entidades somente leitura como recursos MCP para que os clientes possam navegar e mencioná-los com @ como contexto:

URI	O quê
debugg-ai://projects	Todos os projetos (primeira página)
debugg-ai://environments	Ambientes para o projeto detectado automaticamente
debugg-ai://executions	Execuções recentes (primeira página)
debugg-ai://project/{uuid}	Um projeto, detalhe completo
debugg-ai://environment/{uuid}	Um ambiente (credenciais inline, senhas redigidas)
debugg-ai://execution/{uuid}	Uma execução, detalhe completo do nó + links de artefatos

Leituras despacham para os mesmos manipuladores das ferramentas project / environment / executions, então os dados e a autenticação são idênticos. Recursos são aditivos — clientes sem suporte a recursos continuam usando as ferramentas.

Invariantes de segurança

• Senhas são somente gravação. Elas nunca aparecem em nenhum corpo de resposta de nenhuma ferramenta.
• URLs de túnel (*.ngrok.debugg.ai) são removidas de todas as respostas do agente de navegador, incluindo texto de autoria do agente.
• 404s do backend aparecem como isError: true com {error: 'NotFound', ...}, nunca como exceções lançadas.
• DEBUGGAI_API_KEY ausente aparece como um erro de ferramenta estruturado na primeira invocação — o servidor ainda registra e lista as ferramentas normalmente.

Migração para v3.0.0 (ferramentas baseadas em ação)

A v3 consolidou as 20 ferramentas por verbo em 8 ferramentas baseadas em ação. Ferramenta antiga → novo tool {action}:

Removida	Substituição
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Removidas — use o aplicativo web DebuggAI
search_environments	environment {action:"get"} / {action:"list"}
create_environment / update_environment / delete_environment	environment {action:"create"|"update"|"delete"}
create_test_suite / search_test_suites / run_test_suite / get_test_suite_results / delete_test_suite	test_suite {action:"create"|"list"|"run"|"results"|"delete"}
create_test_case / update_test_case / delete_test_case	test_case {action:"create"|"update"|"delete"}
search_executions	executions {action:"get"|"list"}
trigger_crawl parâmetro headless	Removido — sempre headless

Ações delete agora exigem confirmação (prompt de elicitação ou confirm: true). Os clientes captam a nova superfície ao reiniciar o MCP.

Migração da v1.x (mudança disruptiva na v2.0.0)

A v2 colapsou uma superfície de 22 ferramentas para 11. Mapeamento de ferramenta antiga → nova:

Removida	Substituição
list_projects, get_project	search_projects (modo uuid vs modo filtro)
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — credenciais inline em cada ambiente
create_credential	create_environment({credentials: [...]}) semear, ou update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — resolução de nome com tratamento de ambiguidade
list_executions, get_execution	search_executions
cancel_execution	Removida — o desligamento do backend é automático

Mudanças no formato da resposta: o campo count simples nas respostas de lista desapareceu — use pageInfo.totalCount.

Configuração

Var de ambiente	Obrigatória	Finalidade
DEBUGGAI_API_KEY	sim	Chave de API do backend. Apelidos: DEBUGGAI_API_TOKEN, DEBUGGAI_JWT_TOKEN.
DEBUGGAI_API_URL	não	URL base do backend. Padrão: https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	não	token (padrão) ou bearer.
LOG_LEVEL	não	error / warn / info (padrão) / debug.
POSTHOG_API_KEY	não	Substituir a chave de projeto de telemetria embutida (ex.: fork privado).
DEBUGGAI_TELEMETRY_DISABLED	não	Defina como 1 / true / yes / on para desabilitar totalmente a telemetria.

DEBUGGAI_API_KEY=your_api_key

Transporte remoto / HTTP (opcional)

Por padrão, o servidor fala stdio (npx local). Ele pode, em vez disso, ser executado como um MCP remoto hospedado e multiusuário sobre HTTP Streamable sem estado + OAuth:

DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest

É um Servidor de Recursos OAuth: toda POST /mcp precisa de Authorization: Bearer <token>; tokens ausentes/inválidos recebem um 401 com um WWW-Authenticate apontando para os metadados RFC 9728, e os clientes executam o fluxo OAuth contra o servidor de autorização anunciado. O portador tem escopo de requisição — api.debugg.ai o valida.

Endpoint	Finalidade
POST /mcp	MCP Streamable HTTP (protegido por portador)
GET /.well-known/oauth-protected-resource	Metadados RFC 9728 (descoberta do servidor de autorização)
GET /health	Verificação de saúde do balanceador de carga / ECS

Variável de ambiente	Padrão	Finalidade
DEBUGGAI_MCP_TRANSPORT	stdio	Defina como http para o transporte remoto
PORT	3000	Porta de escuta HTTP
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	URL pública de recurso deste servidor (RFC 9728 resource)
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	Servidor de autorização anunciado aos clientes
DEBUGGAI_TOKEN_TYPE	token	Defina como bearer para que tokens OAuth sejam encaminhados como Authorization: Bearer

Instalações via stdio não precisam de nada disso.

Telemetria

O servidor MCP é fornecido com telemetria habilitada por padrão — uma chave de projeto PostHog somente de escrita embutida (phc_*) para que a equipe possa observar taxas de acerto de cache, cadência de polling, confiabilidade do túnel e outras métricas operacionais em toda a base instalada. Eventos capturados:

Evento	Quando
tool.executed / tool.failed	Por chamada de ferramenta
workflow.executed	Por execução do agente do navegador (carrega pollCount, durationMs, finalIntervalMs)
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	Por evento de ciclo de vida do túnel
template.lookup / project.lookup	Acerto/erro de cache com durationMs em chamada fria

Postura de privacidade:

• O ID distinto é SHA-256(api_key).slice(0, 16) — nunca a chave bruta, sem PII.
• Chaves phc_* são somente de escrita por convenção do PostHog; seguro embutir no código fonte.
• Defina DEBUGGAI_TELEMETRY_DISABLED=1 para desativar completamente (resolve para um provedor no-op; nenhum evento sai do processo).

O modo ativo é registrado na inicialização:

Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)

Desenvolvimento Local

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

O conjunto de avaliação inicia o servidor MCP compilado como um subprocesso, exercita cada ferramenta contra um backend real e grava artefatos por fluxo em scripts/evals/artifacts/<timestamp>/. Veja scripts/evals/flows/ para os cenários individuais.

Registro MCP: debugg-ai-local vs debugg-ai

Este repositório fornece um .mcp.json que registra um servidor com escopo de projeto chamado debugg-ai-local apontando para node dist/index.js — o código local recém-compilado. Ele só é ativado quando o diretório de trabalho do Claude Code é este repositório.

Seus outros projetos devem usar o registro debugg-ai com escopo de usuário que obtém o pacote npm publicado:

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

Após editar o código aqui, execute npm run mcp:local (que apenas recompila) para que a próxima invocação de debugg-ai-local capte suas alterações.

Links

Dashboard · Docs · Issues · Discord

---

Licença Apache-2.0 © 2025 DebuggAI