Debugg AI
oficialPermita que seus agentes de geração de código criem e executem testes ponta a ponta sem configuração contra novas alterações de código em navegadores remotos por meio da plataforma de testes Debugg AI.
O que você pode fazer com Debugg AI MCP?
- Executar testes de IA no navegador — Peça ao assistente para
check_app_in_browserem qualquer URL ou localhost, descrevendo o que testar em linguagem natural, e obtenha resultados de aprovação/reprovação com capturas de tela. - Sondar múltiplas páginas rapidamente — Use
probe_pagepara verificar em lote 1–20 URLs em busca de erros de console, problemas de rede e estado renderizado, sem custo de LLM ou loops de agente. - Disparar rastreamentos do grafo de conhecimento — Chame
trigger_crawlpara acionar um rastreamento de agente de navegador no servidor que popula o grafo de conhecimento do projeto com artefatos de HAR e logs de console. - Gerenciar suítes e casos de teste — Crie, execute e revise resultados para entidades
test_suiteetest_case, com resultados por teste e taxas de aprovação. - Inspecionar artefatos de execução — Recupere detalhes completos de execução via
executions, incluindo capturas de tela, rastros de rede HAR e logs de console para depurar problemas em tempo de execução. - Gerenciar ambientes e sessões — Crie ou atualize ambientes com credenciais via
environment, e usesessions/clearSessionspara controlar a reutilização de sessões de login ativas.
Documentação
Debugg AI — Servidor MCP
Testes de navegador com IA via 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).
Testar URLs http://localhost:... requer o binário caddy — check_app_in_browser,
probe_page e trigger_crawl fazem túnel de alvos localhost por meio de um proxy reverso Caddy local.
Isso é instalado automaticamente: a dependência npm @radically-straightforward/caddy baixa uma
versão fixada do Caddy para sua plataforma durante npm install/npx, assim como este projeto já
faz para o binário ngrok — nada para instalar manualmente no caso normal. Se esse download
nunca ocorreu (npm install --ignore-scripts, uma instalação offline/isolada), aponte CADDY_BIN para
sua própria instalação (brew install caddy / apt install caddy / veja
caddyserver.com/docs/install) — a ausência aparece como um
erro claro na primeira chamada de URL localhost, não um travamento silencioso. Chamadas de URL pública, todas as
ferramentas que não são de navegador e test_suite {action:"run"} (que usa seu próprio túnel dedicado e
ignora o Caddy completamente) não precisam disso de qualquer forma.
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
A etapa npm install do Dockerfile captaria caddy da mesma forma automática que instalações locais
fazem, em princípio — mas no momento em que este texto foi escrito, o Dockerfile não COPY vários diretórios que o
build agora precisa (handlers, tools, types, config) e ainda referencia um diretório tunnels/
que não existe mais, então um build novo provavelmente falha antes que isso importe. Essa é uma
lacuna pré-existente, não relacionada ao Caddy. A imagem quinnosha/debugg-ai-mcp atualmente publicada
é anterior à dependência do Caddy de qualquer forma — chamadas de URL localhost para
check_app_in_browser/probe_page/trigger_crawl falharão com CaddyBinaryNotFoundError
dentro dessa imagem até que ela seja reconstruída (Dockerfile corrigido) e republicada, ou CADDY_BIN aponte para
uma incorporada separadamente. Chamadas de URL pública, as ferramentas que não são de navegador e test_suite {action:"run"}
não são afetadas de qualquer forma.
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 (por exemplo, {"action":"list"}) que seleciona a operação. Ações destrutivas de delete exigem confirmação (um prompt de elicitação quando suportado, caso contrário confirm: true).
Navegador
check_app_in_browser
Executa um agente de navegador com IA contra seu aplicativo. O agente navega, interage e reporta com capturas de tela. URLs localhost são automaticamente tuneladas via ngrok.
| Parâmetro | Tipo | Descrição |
|---|---|---|
description | string obrigatório | O que testar (linguagem natural) |
url | string obrigatório | URL alvo — http://localhost:3000 é automaticamente tunelada |
environmentId | string | UUID de um ambiente específico |
credentialId | string | UUID de uma credencial específica |
credentialRole | string | Escolher uma credencial por função (por exemplo, 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) |
loginCredentials | array | Contas para logins que o agente encontra durante a tarefa — [{username, password, label?}] |
useEnvironmentCredentials | boolean | Padrão true. false proíbe o preenchimento automático das credenciais armazenadas do ambiente; sem conta nomeada significa não fazer login de forma alguma |
freshSession | boolean | Padrão false. true força um login real em vez de reutilizar a sessão ativa mantida para essa conta |
auth | object | Pré-condição de autenticação — {precondition, entryUrl, deepUrl, environmentId, username, password} |
repoName | string | Substituir o nome do repositório git detectado automaticamente (por exemplo, my-org/my-repo) |
Uma verificação focada por chamada. O agente tem um orçamento interno de ~25 etapas; divida suítes maiores em várias chamadas.
Credenciais: passe como parâmetros, não em prosa
Nomear uma conta apenas em description não faz o agente usá-la — ele recorre à credencial armazenada do ambiente, e a rejeição da conta errada pelo aplicativo parece uma falha do aplicativo. Qualquer coisa que você passe como parâmetro supera o padrão do ambiente para todos os logins na execução, não apenas o primeiro:
username/password(oucredentialId/credentialRole) — a identidade da execução.auth.username/auth.password— fixa o login de pré-condição quando você também usaauth.precondition: "login".loginCredentials— contas para um formulário de login que o agente encontra no meio da tarefa. Esta é a opção para fluxos como definir senha → ser redirecionado para o login → entrar como a conta que você acabou de criar, onde dividir em chamadas separadas perderia o estado do navegador.
Defina useEnvironmentCredentials: false quando uma substituição silenciosa pelo usuário de teste padrão invalidaria a verificação.
Verificando uma página que não precisa de login? Passe useEnvironmentCredentials: false e não nomeie nenhuma conta. Essa combinação significa exatamente o que diz — não fazer login — e a execução pula a autenticação completamente em vez de procurar um formulário de login. Use para páginas públicas, sites de marketing, documentação e qualquer coisa pré-autenticação. Também é mais rápido: no padrão (auto), o agente seguirá um link "Entrar" para fora da sua página e tentará a conta armazenada do ambiente antes de avaliar qualquer coisa.
Reutilização de sessão: por que uma verificação pode reportar "nenhum formulário de login"
As execuções não fazem login toda vez. Após um login verificado, o backend captura a sessão dessa conta e a restaura na próxima execução para a mesma identidade, o que pula o login completamente — é por isso que uma verificação pode legitimamente retornar com submitted: false e nenhum formulário de login: já estava autenticada. Uma execução restaurada se reporta em logins com reason: "restored_session", para que você possa distingui-la de uma execução que genuinamente não encontrou formulário.
As sessões são chaveadas por conta, então nomear uma conta diferente nunca reutiliza a de outra pessoa. Duas maneiras de contornar a reutilização:
freshSession: trueem uma única chamada — faça login de verdade desta vez e recapture. Use quando o fluxo de login é o que você está verificando, quando suspeitar que a sessão armazenada está desatualizada ou quando a única rota do aplicativo entre personas é um logout.- Ferramenta
environment,action: "clearSessions"— invalida as sessões armazenadas para que execuções subsequentes façam login. Restrinja comusername/credentialId; limpezas sem escopo exigem confirmação porque todas as contas do ambiente então reautenticam.
Use action: "sessions" para ver o que um ambiente está mantendo atualmente e se cada uma seria reutilizada.
Os resultados reportam a identidade realmente usada, então uma errada é visível em vez de se passar por um aplicativo quebrado:
"logins": [
{ "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true }
],
"credentialWarning": {
"requested": "qa+invitefix@example.com",
"used": ["qatest123@example.com"],
"message": "This run signed in with an environment default credential even though '…' was specified. …"
}
source é task | explicit | credential_id (uma conta que você nomeou) ou env | env_default (a conta armazenada do ambiente). credentialWarning aparece apenas quando você nomeou uma conta e um padrão do ambiente foi usado mesmo assim. loginError aparece quando uma conta nomeada não pôde ser resolvida e a execução recusou substituir por uma diferente.
Toda 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 o log do console (toda mensagem JS do console). Use-os para detectar loops de refetch, erros de hidratação e outros problemas de runtime que passam em type-checks 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 buscável), 'not_available' (a página não emitiu nada), 'failed' (a captura falhou). Em uma execução nova, as URLs são comumente null porque a captura é enviada de forma assíncrona após o agente terminar — faça polling de executions {action:"get", uuid: executionId} até o status atingir 'downloaded'. Cabeçalhos de Autorização / Cookie / token/secret/api_key são limpos no servidor antes de os artefatos serem persistidos.
trigger_crawl
Dispara um rastreamento de agente de navegador no servidor para popular o grafo de conhecimento do projeto. URLs 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, mesma forma acima) também está presente em rastreamentos concluídos.
probe_page
Sonda de página em lote leve, sem LLM. Passe 1-20 URLs; cada uma navega, estabiliza no conteúdo (o DOM ficando quieto, com limite — nunca em silêncio de rede, que um aplicativo ao vivo nunca atinge) e retorna o estado renderizado — captura de tela + metadados da página + erros estruturados do console + resumo de rede. Sem loop de agente, sem custo de LLM, sem asserções de cenário. Use para "será que eu quebrei /settings?", fumaça multi-rota após um refactor, varreduras por PR em CI e verificações rápidas de disponibilidade onde o loop de agente de 60-150s do check_app_in_browser é exagero.
| 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 | 'domcontentloaded' (padrão, + uma estabilização de conteúdo com limite) / 'load' (também bloqueia em embeds de terceiros) / 'networkidle' (aceito, nunca emitido — a rede de um site ao vivo não fica ociosa) |
targets[].waitForSelector | string | Seletor CSS opcional para aguardar após a navegação |
targets[].timeoutMs | number | Timeout por URL, 1000-30000 (padrão 10000) |
includeHtml | boolean | Retornar HTML bruto em cada resultado (padrão false) |
captureScreenshots | boolean | Retornar um PNG por alvo (padrão true) |
Todos os alvos em um lote compartilham um túnel de sessão, mas apenas lotes de mesma porta (ou todos públicos) compartilham uma única execução de backend — 5 URLs em uma porta em uma chamada é dramaticamente mais rápido que 5 chamadas paralelas de URL única. Um lote que mistura múltiplas portas locais se decompõe em uma execução sequencial de backend por grupo de porta (ainda uma chamada, ainda um results[] mesclado na sua ordem original, mas N viagens de ida e volta de backend em vez de uma — mais lento, não rejeitado). O campo error por URL preserva a resiliência do lote: um único alvo com falha não falha os outros.
A chave de agregação de 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 infinito de refetch" que os usuários originalmente pediram.
Orçamento de desempenho: <10s para 1 URL, <25s para 20. Porta morta em localhost retorna LocalServerUnreachable em <2s sem queimar uma execução de workflow.
project
| Ação | Params | Resultado |
|---|---|---|
get | {uuid} | Detalhe curado do projeto |
list | {q?, page?, pageSize?} | Resumos paginados |
create | {name, platform, (teamUuid|teamName), (repoUuid|repoName)} | Projeto criado |
Equipe e repositório resolvem por uuid ou nome (correspondência exata sem diferenciar maiúsculas; NotFound se nenhum, AmbiguousMatch se múltiplos). Não há update/delete — renomeie ou exclua um projeto no aplicativo web DebuggAI.
environment
| Ação | Params | Resultado |
|---|---|---|
get | {uuid, projectUuid?} | Env com credenciais embutidas (senhas nunca retornadas) |
list | {projectUuid?, q?, page?, pageSize?} | Envs paginados, cada um com um array de credenciais |
create | {name, url, description?, projectUuid?, credentials?} | Env criado (opcionalmente semeia credenciais) |
update | {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?} | Env corrigido; operações de credencial executam remover → atualizar → adicionar |
delete | {uuid, projectUuid?, confirm?} | Exclui env (cascata de credenciais) — requer confirmação |
sessions | {uuid, username?, credentialId?} | Sessões de login capturadas que o env mantém, por conta, com isUsable e um usableCount |
clearSessions | {uuid, username?, credentialId?, confirm?} | Invalida-as para que a próxima execução faça login de verdade — limpezas sem escopo exigem confirmação |
projectUuid resolve automaticamente a partir do repositório git quando omitido. Falhas por credencial aparecem em credentialWarnings[] sem bloquear a operação do env.
sessions / clearSessions gerenciam as sessões autenticadas ativas que o backend reutiliza para pular o login (veja Reutilização de sessão). O conteúdo das sessões nunca é retornado — um cookie de sessão é uma credencial portadora. clearSessions marca sessões como inválidas em vez de excluir as linhas, para que a reutilização pare imediatamente enquanto o histórico de captura permanece legível.
test_suite
| Ação | Params | Resultado |
|---|---|---|
list | {projectUuid|projectName, search?, page?, pageSize?} | Suites paginados com status + taxa de aprovação |
create | {name, description, projectUuid|projectName} | Suite criado |
run | {suiteUuid|(suiteName+project), targetUrl?} | Dispara todos os testes de forma assíncrona |
results | {suiteUuid|(suiteName+project)} | Suite + resultados por teste |
delete | {suiteUuid|(suiteName+project), confirm?} | Exclusão suave — requer confirmação |
test_case
| Ação | Params | 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 | Params | Resultado |
|---|---|---|
get | {uuid} | Detalhe completo (nodeExecutions + estado + errorInfo) + artefatos de screenshot/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
Toda 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 (baseado em 1, padrão 1) e pageSize (padrão 20, máximo 200; valores acima do limite são ajustados). Nenhuma resposta é truncada silenciosamente.
Recursos
Além das 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 auto-detectado |
debugg-ai://executions | Execuções recentes (primeira página) |
debugg-ai://project/{uuid} | Um projeto, detalhe completo |
debugg-ai://environment/{uuid} | Um ambiente (credenciais embutidas, senhas ocultas) |
debugg-ai://execution/{uuid} | Uma execução, detalhe completo do nó + links de artefatos |
As leituras são despachadas para os mesmos handlers das ferramentas project / environment /
executions, então os dados e a autenticação são idênticos. Os 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 escrito pelo agente. - 404s do backend aparecem como
isError: truecom{error: 'NotFound', ...}, nunca como exceções lançadas. DEBUGGAI_API_KEYausente aparece como um erro de ferramenta estruturado na primeira invocação — o servidor ainda registra e lista 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 headless param | Removido — sempre headless |
Ações delete agora exigem confirmação (prompt de elicitação, ou confirm: true). Os clientes adotam a nova superfície ao reiniciar o MCP.
Migração da v1.x (mudança que quebra na v2.0.0)
A v2 reduziu uma superfície de 22 ferramentas para 11. Mapeamento ferramenta antiga → ferramenta 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 embutidas em cada env |
create_credential | create_environment({credentials: [...]}) seed, 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 das respostas: o campo count simples nas respostas de lista foi removido — use pageInfo.totalCount.
Configuração
| Variável de ambiente | Obrigatória | Finalidade |
|---|---|---|
DEBUGGAI_API_KEY | sim | Chave de API do backend. Aliases: 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. |
DEBUGGAI_EVAL_TEMPLATE | não | Substitui o slug do fluxo de trabalho de Avaliação de App para o qual check_app_in_browser despacha. Padrão: flow/e2es/app-eval. O despacho fixa este slug para que uma renomeação de template do backend não o quebre. |
LOG_LEVEL | não | error / warn / info (padrão) / debug. |
POSTHOG_API_KEY | não | Substitui a chave de projeto de telemetria embutida (ex.: fork privado). |
DEBUGGAI_TELEMETRY_DISABLED | não | Defina como 1 / true / yes / on para desativar a telemetria completamente. |
DEBUGGAI_API_KEY=your_api_key
Transporte remoto / HTTP (opcional)
Por padrão, o servidor fala stdio (npx local). Ele pode, em vez disso, rodar como um
MCP remoto hospedado e multiusuário sobre Streamable HTTP sem estado + OAuth:
DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest
É um Resource Server 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 bearer é escopado por requisição —
api.debugg.ai o valida.
| Endpoint | Finalidade |
|---|---|
POST /mcp | MCP Streamable HTTP (protegido por bearer) |
GET /.well-known/oauth-protected-resource | Metadados RFC 9728 (descoberta do servidor de autorização) |
GET /health | Verificação de saúde do load-balancer / 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 nenhuma dessas.
Implantações multi-réplica (go/no-go antes do rollout): o estado do túnel (a sessão de túnel ngrok,
sua instância Caddy e seu bloqueio de rota de porta) está em processo, chaveado por chamador por um hash do
token bearer — não há coordenação entre processos. Rodar várias réplicas atrás de um load
balancer round-robin simples significa que chamadas de um mesmo chamador podem cair em réplicas diferentes e criar um
túnel por réplica que ele atingir em vez de um para a sessão inteira (custo extra de ngrok, limitado pelo
número de réplicas, auto-recuperável via o desligamento automático por inatividade de 55 minutos existente — nunca um bug
de correção entre sessões, já que qualquer chamada de ferramenta individual permanece em uma réplica durante toda a sua duração). Para obter
o comportamento pretendido de "um túnel por sessão" em uma implantação HTTP multi-réplica, configure
roteamento afim à sessão no load balancer (hash fixo/consistente chaveado pela mesma identidade
que getSessionKey() deriva — na prática, o token bearer Authorization do chamador). Veja
docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 para o raciocínio completo e o
caminho de degradação honesto se isso não for configurado.
Telemetria
O servidor MCP vem com telemetria habilitada por padrão — uma chave de projeto PostHog embutida somente gravação (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 na base instalada. Eventos capturados:
| Evento | Quando |
|---|---|
tool.executed / tool.failed | Por chamada de ferramenta |
workflow.executed | Por execução de agente de 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 gravação por convenção do PostHog; seguras para embutir no código-fonte. - Defina
DEBUGGAI_TELEMETRY_DISABLED=1para optar por sair completamente (resolve para um provedor no-op; nenhum evento sai do processo).
O modo ativo é registrado no boot:
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
A suíte de avaliação inicia o servidor MCP compilado como um subprocesso, exercita cada ferramenta contra um backend real e escreve 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 inclui um .mcp.json que registra um servidor escopado por 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 escopado por usuário debugg-ai que puxa do 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 adote suas alterações.
Links
Dashboard · Docs · Issues · Discord
Licença Apache-2.0 © 2025 DebuggAI