DebugAI

@debugai/mcp

Dale a tu agente de codificación un depurador en lugar de un bucle de grep.

Tu agente entrega un error a debug_error y recibe la causa raíz, el archivo y la línea exactos, y hasta 3 correcciones clasificadas como ediciones listas para aplicar. Cada corrección está etiquetada con si una verificación mecánica realmente pasó, para que el agente sepa cuáles fueron verificadas y cuáles son la estimación propia del modelo.

Configura automáticamente Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI y Cline. Funciona en cualquier otro cliente MCP con una entrada manual. Node 18 o posterior.

Configuración

npx -y @debugai/mcp setup

Eso es todo. Te inicia sesión a través de tu navegador (sin clave que buscar o copiar), escribe la configuración para cada cliente MCP que encuentre en esta máquina, y luego verifica que todo funcione realmente.

Reinicia los clientes que nombre y tu agente tendrá las herramientas.

¿Prefieres leer primero? debugai.io/start?src=npm recorre lo mismo por cliente.

Qué hace ese comando en tu máquina

Vale la pena saberlo antes de ejecutar algo que edite la configuración de tu editor:

• Te inicia sesión con un código corto que confirmas en el navegador. Cuenta gratuita, 10 depuraciones al día, sin tarjeta.
• Almacena tu clave en ~/.debugai/config.json con permisos 0600. Ese es el único archivo que la contiene.
• Añade una entrada debugai a la configuración de cada cliente MCP que detecte. Cada archivo se respalda primero (<file>.debugai-backup-<timestamp>), se preserva cualquier otra configuración en el archivo, y un archivo que no pueda analizar se deja intacto y se reporta en su lugar. Una advertencia dicha claramente: si tu configuración contiene comentarios, la reescritura los elimina, porque JSON no tiene dónde ponerlos. Recibes una advertencia antes de que ocurra y el respaldo aún los contiene.
• Omite VS Code por defecto, porque la extensión DebugAI ya registra este servidor allí y una segunda entrada mostraría cada herramienta dos veces. install --client=vscode lo hace de todos modos si quieres el servidor sin la extensión.
• Nunca escribe tu clave en una configuración de cliente. Las configuraciones de cliente se envían a repositorios. Las claves no deberían.

Vista previa sin escribir nada:

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

Deshacer todo:

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

Comandos

Comando	Qué hace
setup	login luego install, y luego verifica. El que quieres.
login	Inicio de sesión en navegador. --key dbg_… para pegar una clave en su lugar (CI, máquinas aisladas). --force para volver a vincular.
logout	Elimina la clave almacenada.
status	Qué clave y cuenta están activas ahora mismo.
install	Escribe configuraciones de cliente. --list, --client=cursor, --all, --dry-run, --remove.
uninstall	Elimina la entrada de cada configuración de cliente.
doctor	Diagnostica una configuración rota: clave, accesibilidad de API, cableado por cliente.

npx -y @debugai/mcp install --list imprime cada cliente compatible, dónde vive su configuración en tu sistema operativo, y si DebugAI ya está en él.

Iniciar sesión desde dentro de un chat

Si tu agente llama a una herramienta de DebugAI antes de que hayas iniciado sesión, la herramienta responde con un código corto y una URL en lugar de un error. Confírmalo en el navegador, dile al agente que lo intente de nuevo, y la llamada se completará. Sin edición de configuración y sin reinicio del cliente, porque la clave se relee en cada llamada.

Las herramientas

debug_error

Dale un error, obtén un análisis.

Entrada	Requerida	Descripción
errorText	sí	Mensaje de error completo, excepción o rastreo de pila.
language	no	javascript, typescript, python, go, rust o auto (predeterminado).
codeSnippet	no	Código alrededor de la línea que falla, si el agente lo tiene.
filePath	no	Ruta al archivo que lanzó el error.

Devuelve la causa raíz, hasta 3 correcciones clasificadas por confianza, el framework detectado y si la respuesta provino de la caché. Desde 2.0, cada corrección también incluye, cuando es derivable: edits (cadenas exactas antiguas/nuevas que la herramienta de edición de tu agente puede aplicar directamente), unified_diff y verify_with (un comando de verificación a nivel de sintaxis para ejecutar después de aplicar). Solo lectura: nunca toca tus archivos. Aplicar una corrección es decisión de tu agente y tuya.

Cada corrección está etiquetada con su estado de verificación, y hay tres, no dos: verificada (una verificación mecánica pasó, actualmente clases de análisis e importación), verificación fallida (confianza limitada estrictamente) o no verificada (el número de confianza es la estimación propia del modelo, nada lo verificó). Etiquetamos el tercer caso en lugar de ocultarlo.

report_outcome

Dile a DebugAI si una corrección aplicada realmente funcionó.

Entrada	Requerida	Descripción
debugLogId	sí	El debug_log_id de la respuesta de debug_error.
result	sí	worked o failed.
fixRank	no	Qué corrección clasificada se aplicó (1-3).
newError	no	Si falló: el error que viste después de aplicar.

Las correcciones confirmadas de rango 1 se recuerdan por proyecto, así que la próxima vez que aparezca el mismo error se comienza desde la corrección confirmada. Los seguimientos de correcciones fallidas son la retroalimentación que mejora las respuestas futuras. Se pide a los agentes que llamen a esto una vez por corrección aplicada, a través del mismo flujo de retroalimentación humana que pasa por la extensión de VS Code.

Ejemplo, en Claude Code:

Pega un rastreo de pila y pregunta "¿por qué está fallando esto?". Claude llama a debug_error y recibe algo como:

Causa raíz: db.session se usa después de que el contexto de la solicitud se cerró. Corrección 1 (94% de confianza): mueve la consulta dentro del manejador de solicitudes...

Hacer que tu agente lo use

El servidor les dice a los agentes que se conectan para qué sirve, pero una regla en tu archivo de proyecto es la versión determinista. Añade esto a CLAUDE.md, .cursorrules o lo que tu agente lea:

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

No necesitas este paquete. La extensión DebugAI registra el servidor MCP automáticamente (VS Code 1.101+) y añade aplicación de correcciones con un clic, escaneo proactivo e indexación del código base encima. También está en Open VSX, para Cursor, Windsurf y VSCodium.

Configuración manual

setup cubre esto, y install --client=<id> cubre el caso donde un cliente está instalado en un lugar inusual. Si aún prefieres editar el archivo tú mismo, la entrada es la misma en todas partes:

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

Dónde va:

Cliente	Archivo
Claude Code	~/.claude.json (o 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 de VS Code, saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Zed usa una clave diferente y un comando anidado:

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

Luego ejecuta npx -y @debugai/mcp login una vez para almacenar tu clave. Si prefieres establecer la clave por cliente, DEBUGAI_API_KEY en el bloque env de ese cliente aún funciona y aún gana sobre la almacenada.

Variables de entorno

Variable	Predeterminado	Descripción
DEBUGAI_API_KEY	(ninguno)	Tu clave de API. Anula api_key en el archivo de configuración.
DEBUGAI_API_BASE	Producción de DebugAI	Anulación para configuraciones autoalojadas o de prueba. Vuelve a api_base en el archivo de configuración.
DEBUGAI_TIMEOUT_MS	150000	Plazo por solicitud. Los análisis profundos pueden tomar 30-90s.
DEBUGAI_CONFIG_PATH	~/.debugai/config.json	Ubicación alternativa del archivo de configuración. Rara vez necesario.

Límites y honestidad

• Nivel gratuito: 10 depuraciones/día. Pro ($12/mes): 1,000/mes límite flexible, nunca bloqueado estrictamente en él.
• Cuando alcanzas el límite diario, la herramienta lo dice y se detiene. No reintentará silenciosamente.
• Los errores simples se enrutan a un modelo rápido. Los feos de múltiples archivos se enrutan a uno más fuerte en los niveles pagos. La insignia Model: en cada respuesta te dice cuál respondió.
• Los análisis se ejecutan en los servidores de DebugAI. El texto del error y cualquier fragmento que pases se envían allí, y Claude (Anthropic) hace el análisis. Política de privacidad: debugai.io/privacy.

Solución de problemas

Ejecuta npx -y @debugai/mcp doctor primero. Verifica tu versión de Node, si hay una clave almacenada y de dónde vino, si esa clave aún se autentica contra la API, los permisos del archivo de configuración y qué clientes detectados carecen de la entrada de DebugAI. La mayoría de las respuestas están en esa salida.

• "autenticación fallida": la clave fue rotada o revocada. Ejecuta npx -y @debugai/mcp login --force.
• Las herramientas no aparecen en el cliente: el cliente no se reinició, o lee un archivo de configuración diferente. install --list muestra qué archivo se escribió.
• No pasa nada en npx @debugai/mcp: correcto. Es un servidor stdio esperando que un cliente MCP hable primero. Usa --help para verificar la instalación.
• Tiempos de espera: los análisis profundos pueden tomar hasta 90s. Si tu cliente tiene su propio tiempo de espera de herramientas, súbelo por encima de eso.

Registro de cambios

2.1.1: solo metadatos. Añade mcpName para la verificación de propiedad del registro MCP oficial, corrige el enlace del repositorio en la página del paquete npm.

2.1.0: configuración con un comando. Inicio de sesión en navegador a través de un enlace de dispositivo (sin pegar claves), escritura automática de configuración de cliente con respaldos, doctor para diagnosticar una configuración rota e inicio de sesión en conversación cuando un agente llama a una herramienta antes de que tengas una cuenta.

2.0.0: herramienta report_outcome, edits listos para aplicar por corrección y la etiqueta de verificación de tres estados.

Desarrollo

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

Fuente

github.com/1shizaan/debugai-mcp es la fuente de este paquete, reflejada desde el directorio donde se desarrolla. Lleva el historial completo de confirmaciones de estos archivos, así que git log y git blame funcionan normalmente.

El cliente es MIT y completo: el servidor stdio, el inicio de sesión por enlace de dispositivo, el escritor de configuración y las pruebas están todos aquí. El análisis en sí se ejecuta en los servidores de DebugAI y no es parte de este paquete.

Las incidencias y solicitudes de extracción son bienvenidas en ese repositorio.

MIT © DebugAI