DebugAI

Servidor MCP que fornece a agentes de codificação causa raiz e correções prontas para aplicar para qualquer erro, com um sinalizador verificado mostrando quais correções foram verificadas mecanicamente.

GitHubExperimente este MCPPatrocinado

Documentação

@debugai/mcp

Dê ao seu agente de codificação um depurador em vez de um loop de grep.

Seu agente entrega um erro ao debug_error e recebe de volta a causa raiz, o arquivo e a linha exatos, e até 3 correções classificadas como edições prontas para aplicar. Cada correção é rotulada com se uma verificação mecânica realmente passou, para que o agente saiba quais foram verificadas e quais são a estimativa do próprio modelo.

Configura automaticamente Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI e Cline. Funciona em qualquer outro cliente MCP com uma entrada manual. Node 18 ou posterior.

Configuração

npx -y @debugai/mcp setup

Isso é tudo. Ele faz seu login pelo navegador (sem chave para encontrar ou copiar), escreve a configuração para cada cliente MCP que encontra nesta máquina e depois verifica se tudo realmente funciona.

Reinicie os clientes que ele menciona e seu agente terá as ferramentas.

Prefere ler primeiro? debugai.io/start?src=npm percorre o mesmo processo por cliente.

O que esse comando faz na sua máquina

Vale a pena saber antes de executar algo que edita a configuração do seu editor:

Faz seu login com um código curto que você confirma no navegador. Conta gratuita, 10 depurações por dia, sem cartão.
Armazena sua chave em ~/.debugai/config.json com permissões 0600. Esse é o único arquivo que a contém.
Adiciona uma entrada debugai à configuração de cada cliente MCP que detecta. Cada arquivo é copiado primeiro (<file>.debugai-backup-<timestamp>), todas as outras configurações no arquivo são preservadas, e um arquivo que não consegue analisar é deixado intacto e relatado. Uma ressalva dita claramente: se sua configuração contiver comentários, a reescrita os remove, porque JSON não tem onde colocá-los. Você recebe um aviso antes que isso aconteça e o backup ainda os contém.
Ignora VS Code por padrão, porque a extensão DebugAI já registra este servidor lá e uma segunda entrada mostraria cada ferramenta duas vezes. install --client=vscode faz isso de qualquer forma se você quiser o servidor sem a extensão.
Nunca escreve sua chave na configuração de um cliente. Configurações de clientes são commitadas em repositórios. Chaves não deveriam ser.

Pré-visualize sem escrever nada:

npx -y @debugai/mcp install --dry-run

Desfaça tudo:

npx -y @debugai/mcp uninstall   # removes the entry from every client config
npx -y @debugai/mcp logout      # removes the stored key

Comandos

Comando	O que faz
`setup`	`login` e depois `install`, e então verifica. É o que você quer.
`login`	Login pelo navegador. `--key dbg_…` para colar uma chave em vez disso (CI, máquinas isoladas). `--force` para re-vincular.
`logout`	Remove a chave armazenada.
`status`	Qual chave e conta estão ativas agora.
`install`	Escreve configurações de clientes. `--list`, `--client=cursor`, `--all`, `--dry-run`, `--remove`.
`uninstall`	Remove a entrada de toda configuração de cliente.
`doctor`	Diagnostica uma configuração quebrada: chave, acessibilidade da API, fiação por cliente.

npx -y @debugai/mcp install --list imprime todos os clientes suportados, onde a configuração deles vive no seu sistema operacional e se o DebugAI já está nela.

Entrando em uma conversa

Se seu agente chamar uma ferramenta DebugAI antes de você ter feito login, a ferramenta responde com um código curto e uma URL em vez de um erro. Confirme no navegador, diga ao agente para tentar novamente e a chamada passa. Sem edição de configuração e sem reiniciar o cliente, porque a chave é relida a cada chamada.

As ferramentas

`debug_error`

Dê a ela um erro, receba uma análise.

Entrada	Obrigatória	Descrição
`errorText`	sim	Mensagem de erro completa, exceção ou stack trace.
`language`	não	`javascript`, `typescript`, `python`, `go`, `rust` ou `auto` (padrão).
`codeSnippet`	não	Código ao redor da linha com falha, se o agente o tiver.
`filePath`	não	Caminho para o arquivo que lançou o erro.

Retorna a causa raiz, até 3 correções classificadas por confiança, o framework detectado e se a resposta veio do cache. Desde 2.0, cada correção também carrega, quando derivável: edits (strings exatas antigas/novas que a ferramenta de edição do seu agente pode aplicar diretamente), unified_diff e verify_with (um comando de verificação em nível de sintaxe para executar após aplicar). Somente leitura: nunca toca em seus arquivos. Aplicar uma correção é decisão do seu agente, e sua.

Cada correção é rotulada com seu estado de verificação, e há três, não dois: verificada (uma verificação mecânica passou, atualmente classes de parse e import), verificação falhou (confiança limitada duramente) ou não verificada (o número de confiança é a estimativa do próprio modelo, nada o verificou). Rotulamos o terceiro caso em vez de escondê-lo.

`report_outcome`

Diga ao DebugAI se uma correção aplicada realmente funcionou.

Entrada	Obrigatória	Descrição
`debugLogId`	sim	O `debug_log_id` da resposta do `debug_error`.
`result`	sim	`worked` ou `failed`.
`fixRank`	não	Qual correção classificada foi aplicada (1-3).
`newError`	não	Se falhou: o erro que você viu após aplicar.

Correções confirmadas de classificação 1 são lembradas por projeto, então a próxima ocorrência do mesmo erro começa pela correção confirmada. Acompanhamentos de correções falhas são o feedback que melhora respostas futuras. Pede-se que agentes chamem isso uma vez por correção aplicada, pelo mesmo pipeline pelo qual o feedback humano flui na extensão VS Code.

Exemplo, no Claude Code:

Cole um traceback e pergunte "por que isso está falhando?". Claude chama debug_error e recebe algo como:

Causa raiz: db.session é usado depois que o contexto da requisição foi fechado. Correção 1 (94% de confiança): mova a consulta para dentro do manipulador de requisição...

Fazendo seu agente alcançá-la

O servidor diz aos agentes conectados para que serve, mas uma regra no seu arquivo de projeto é a versão determinística. Adicione isso a CLAUDE.md, .cursorrules ou o que seu agente ler:

On any runtime error, exception, or failing test, call the debugai
debug_error tool before attempting your own fix. After applying a fix,
call report_outcome so the project's error memory stays accurate.

VS Code

Você não precisa deste pacote. A extensão DebugAI registra o servidor MCP automaticamente (VS Code 1.101+) e adiciona aplicação de correção com um clique, varredura proativa e indexação de base de código por cima. Também está no Open VSX, para Cursor, Windsurf e VSCodium.

Configuração manual

setup cobre isso, e install --client=<id> cobre o caso em que um cliente está instalado em um local incomum. Se você ainda preferir editar o arquivo você mesmo, a entrada é a mesma em todos os lugares:

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp"]
    }
  }
}

Onde vai:

Cliente	Arquivo
Claude Code	`~/.claude.json` (ou `claude mcp add debugai -- npx -y @debugai/mcp`)
Claude Desktop	macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Gemini CLI	`~/.gemini/settings.json`
Cline	globalStorage do VS Code, `saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

Zed usa uma chave diferente e um comando aninhado:

{
  "context_servers": {
    "debugai": {
      "source": "custom",
      "command": { "path": "npx", "args": ["-y", "@debugai/mcp"] }
    }
  }
}

Depois execute npx -y @debugai/mcp login uma vez para armazenar sua chave. Se preferir definir a chave por cliente, DEBUGAI_API_KEY no bloco env desse cliente ainda funciona e ainda vence a armazenada.

Variáveis de ambiente

Variável	Padrão	Descrição
`DEBUGAI_API_KEY`	(nenhum)	Sua chave de API. Substitui `api_key` no arquivo de configuração.
`DEBUGAI_API_BASE`	Produção DebugAI	Substituição para setups self-hosted ou de staging. Cai para `api_base` no arquivo de configuração.
`DEBUGAI_TIMEOUT_MS`	`150000`	Prazo por requisição. Análises profundas podem levar 30-90s.
`DEBUGAI_CONFIG_PATH`	`~/.debugai/config.json`	Local alternativo do arquivo de configuração. Raramente necessário.

Limites e honestidade

Nível gratuito: 10 depurações/dia. Pro ($12/mês): 1.000/mês com limite flexível, nunca bloqueado duramente nele.
Quando você atinge o limite diário, a ferramenta diz isso e para. Ela não tentará silenciosamente de novo.
Erros simples vão para um modelo rápido. Erros feios entre arquivos vão para um mais forte em níveis pagos. O selo Model: em cada resposta diz qual respondeu.
Análises rodam nos servidores do DebugAI. O texto do erro e qualquer trecho que você passar são enviados para lá, e Claude (Anthropic) faz a análise. Política de privacidade: debugai.io/privacy.

Solução de problemas

Execute npx -y @debugai/mcp doctor primeiro. Ele verifica sua versão do Node, se uma chave está armazenada e de onde veio, se essa chave ainda autentica contra a API, as permissões no arquivo de configuração e quais clientes detectados estão sem a entrada DebugAI. A maioria das respostas está nessa saída.

"autenticação falhou": a chave foi rotacionada ou revogada. Execute npx -y @debugai/mcp login --force.
Ferramentas não aparecem no cliente: o cliente não foi reiniciado, ou ele lê um arquivo de configuração diferente. install --list mostra qual arquivo foi escrito.
Nada acontece no npx @debugai/mcp: correto. É um servidor stdio esperando um cliente MCP falar primeiro. Use --help para verificar a instalação.
Timeouts: análises profundas podem levar até 90s. Se seu cliente tem seu próprio timeout de ferramenta, aumente-o acima disso.

Changelog

2.1.1: apenas metadados. Adiciona mcpName para verificação de propriedade do registro MCP oficial, corrige o link do repositório na página do pacote npm.

2.1.0: configuração em um comando. Login pelo navegador via link de dispositivo (sem colar chave), escrita automática de configuração de cliente com backups, doctor para diagnosticar uma configuração quebrada e login em conversa quando um agente chama uma ferramenta antes de você ter uma conta.

2.0.0: ferramenta report_outcome, edits prontos para aplicar por correção e o rótulo de verificação de três estados.

Desenvolvimento

npm install
npm test        # builds, then runs unit + spawned-process e2e tests

Fonte

github.com/1shizaan/debugai-mcp é a fonte deste pacote, espelhado do diretório onde é desenvolvido. Carrega o histórico completo de commits desses arquivos, então git log e git blame funcionam normalmente.

O cliente é MIT e completo: o servidor stdio, o login por link de dispositivo, o escritor de configuração e os testes estão todos aqui. A análise em si roda nos servidores do DebugAI e não faz parte deste pacote.

Issues e pull requests são bem-vindos nesse repositório.