MCP JS Debugger

MCP JS Debugger

Um servidor MCP (Model Context Protocol) que expõe recursos de depuração do Chrome DevTools Protocol, permitindo que assistentes de IA depurem aplicações JavaScript e TypeScript.

Recursos

• Conecte-se a qualquer depurador compatível com CDP (Node.js, Chrome, Edge)
• Definir, listar e remover breakpoints
• Percorrer o código (passar por cima, entrar, sair)
• Inspecionar pilhas de chamadas com suporte a source maps
• Avaliar expressões em qualquer frame da pilha
• Visualizar e modificar variáveis
• Pausar em exceções
• Suporte completo a source maps para depurar código transpilado

Instalação

npm install
npm run build

Integração com Claude Code

Adicione à sua configuração do Claude Code:

claude mcp add mcp-js-debugger -- npx mcp-js-debugger

Ou adicione ao .mcp.json:

{
  "mcpServers": {
    "mcp-js-debugger": {
      "command": "npx",
      "args": ["mcp-js-debugger"]
    }
  }
}

Uso

Iniciando um alvo de depuração

Inicie sua aplicação Node.js com o inspector:

# Pause on first line (recommended for setting initial breakpoints)
node --inspect-brk=9229 your-script.js

# Or start without pausing
node --inspect=9229 your-script.js

Ferramentas disponíveis

Ferramenta	Descrição
connect_debugger	Conectar a um endpoint CDP via URL WebSocket
disconnect_debugger	Desconectar de uma sessão de depuração
set_breakpoint	Definir um breakpoint por URL e número de linha
remove_breakpoint	Remover um breakpoint por ID
list_breakpoints	Listar todos os breakpoints em uma sessão
resume_execution	Retomar a execução após pausa
step_over	Passar por cima da instrução atual
step_into	Entrar em uma chamada de função
step_out	Sair da função atual
pause_execution	Pausar a execução em andamento
get_call_stack	Obter a pilha de chamadas atual com localizações de origem
evaluate_expression	Avaliar uma expressão JavaScript
get_scope_variables	Obter variáveis em um escopo
set_variable_value	Modificar o valor de uma variável
set_pause_on_exceptions	Configurar o tratamento de exceções
get_original_location	Mapear localização gerada para a origem original
get_script_source	Obter o código-fonte do script
list_scripts	Listar scripts carregados

Fluxo de trabalho de exemplo

1. Inicie sua aplicação com --inspect-brk:

   node --inspect-brk=9229 app.js
   

2. Obtenha a URL WebSocket:

   curl http://localhost:9229/json
   

3. Conecte o depurador:

   connect_debugger(websocket_url: "ws://localhost:9229/<id>")
   

4. Defina breakpoints:

   set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)
   

5. Retome a execução para atingir o breakpoint:

   resume_execution(session_id: "...")
   

6. Inspecione o estado quando pausado:

   get_call_stack(session_id: "...")
   get_scope_variables(session_id: "...", call_frame_id: "...", scope_index: 0)
   evaluate_expression(session_id: "...", expression: "myVariable")
   

7. Continue a depuração:

   step_over(session_id: "...")
   resume_execution(session_id: "...")
   

Suporte a source maps

O servidor carrega automaticamente source maps para código transpilado (TypeScript, JavaScript empacotado, etc.). Quando source maps estão disponíveis:

• Pilhas de chamadas mostram localizações de origem originais
• Breakpoints podem ser definidos em arquivos de origem originais
• get_original_location mapeia posições geradas para a origem original
• get_script_source pode retornar o conteúdo da origem original

Desenvolvimento

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Arquitetura

• cdp-client.ts - Wrapper de cliente de protocolo Chrome DevTools de baixo nível
• session-manager.ts - Gerencia múltiplas sessões de depuração
• source-map-manager.ts - Lida com carregamento de source maps e mapeamento de posições
• server.ts - Implementação do servidor MCP com manipuladores de ferramentas
• types.ts - Definições de tipos TypeScript

Requisitos

• Node.js 18.0.0 ou posterior
• Um alvo de depuração compatível com CDP (Node.js, Chrome, Edge, etc.)

Licença

Apache-2.0