Debugg AI

Debugg AI — Servidor MCP

Pruebas de navegador impulsadas por IA a través del Protocolo de Contexto de Modelo. Apúntalo a cualquier URL (o localhost) y describe qué probar — un agente de IA navega por tu aplicación y devuelve aprobado/reprobado con capturas de pantalla.

Configuración

Requiere Node.js 20.20.0 o posterior (requisito transitivo de posthog-node@^5.26.0).

Obtén una clave API en debugg.ai, luego añádela a la configuración de tu cliente MCP:

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

O con Docker:

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

Herramientas

El servidor expone 8 herramientas: tres herramientas de Navegador más una herramienta basada en acciones por entidad gestionada. Las herramientas principales son check_app_in_browser (agente de IA completo) y probe_page (sonda de página ligera sin LLM). El resto — project, environment, test_suite, test_case, executions — cada una toma un discriminador action (ej. {"action":"list"}) que selecciona la operación. Las acciones destructivas delete requieren confirmación (un aviso de elicitación donde sea soportado, de lo contrario confirm: true).

Navegador

check_app_in_browser

Ejecuta un agente de navegador de IA contra tu aplicación. El agente navega, interactúa e informa con capturas de pantalla. Las URLs de localhost se tunelizan automáticamente a través de ngrok.

Parámetro	Tipo	Descripción
description	string requerido	Qué probar (lenguaje natural)
url	string requerido	URL objetivo — http://localhost:3000 se tuneliza automáticamente
environmentId	string	UUID de un entorno específico
credentialId	string	UUID de una credencial específica
credentialRole	string	Elegir una credencial por rol (ej. admin, guest)
username	string	Nombre de usuario para inicio de sesión (efímero — no persistido)
password	string	Contraseña para inicio de sesión (efímera — no persistida)
repoName	string	Sobrescribir el nombre del repositorio git auto-detectado (ej. my-org/my-repo)

Una comprobación enfocada por llamada. El agente tiene un presupuesto interno de ~25 pasos; divide suites más amplias en múltiples llamadas.

Cada ejecución exitosa devuelve un bloque browserSession junto con la captura de pantalla — URLs S3 prefirmadas para el HAR capturado (traza de red completa) y el registro de consola (cada mensaje de consola JS). Úsalos para detectar bucles de refetch, errores de hidratación y otros problemas de tiempo de ejecución que pasan las comprobaciones de tipos y las pruebas unitarias:

"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"
}

Las URLs son S3 prefirmadas de corta duración — vuelve a consultar la ejecución padre a través de executions {action:"get", uuid} para renovarlas. harStatus / consoleLogStatus desambiguan 'downloaded' (URL obtenible), 'not_available' (la página no emitió nada), 'failed' (la captura falló). En una ejecución nueva, las URLs suelen estar null porque la carga de capturas es asíncrona después de que el agente termina — consulta executions {action:"get", uuid: executionId} hasta que el estado alcance 'downloaded'. Las cabeceras de Autorización / Cookie / token/secret/api_key se limpian del lado del servidor antes de que los artefactos se persistan.

trigger_crawl

Dispara un rastreo de agente de navegador del lado del servidor para poblar el grafo de conocimiento del proyecto. Las URLs de localhost se tunelizan automáticamente. Devuelve {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} con knowledgeGraph.imported === true en la ingesta exitosa. El bloque browserSession (URLs de HAR + registro de consola, misma forma que arriba) también está presente en los rastreos completados.

probe_page

Sonda de página por lotes ligera sin LLM. Pasa 1-20 URLs; cada una navega, espera la carga y devuelve el estado renderizado — captura de pantalla + metadatos de página + errores de consola estructurados + resumen de red. Sin bucle de agente, sin coste de LLM, sin aserciones de escenario. Úsalo para "¿acabo de romper /settings?", pruebas de humo multi-ruta después de una refactorización, barridos por PR en CI y comprobaciones rápidas de si está activo donde el bucle de agente de 60-150s de check_app_in_browser es excesivo.

Parámetro	Tipo	Descripción
targets	array requerido	1-20 entradas: [{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	string requerido	URL pública o localhost (auto-tunelizada)
targets[].waitForLoadState	enum	'load' (por defecto) / 'domcontentloaded' / 'networkidle'
targets[].waitForSelector	string	Selector CSS opcional para esperar después de la navegación
targets[].timeoutMs	number	Tiempo de espera por URL, 1000-30000 (por defecto 10000)
includeHtml	boolean	Devolver HTML sin procesar en cada resultado (por defecto false)
captureScreenshots	boolean	Devolver un PNG por objetivo (por defecto true)

Todo el lote comparte una única ejecución de backend + sesión de navegador + túnel — 5 URLs en una llamada es drásticamente más rápido que 5 llamadas paralelas de una sola URL. El campo error por URL preserva la resiliencia del lote: un solo objetivo fallido no hace fallar a los demás.

La clave de agregación de networkSummary es origin + pathname — los bucles de refetch (?n=0..4 golpeando repetidamente el mismo endpoint) se colapsan en una sola entrada con el conteo, por lo que /api/poll apareciendo con count: 47 es la señal procesable de "bucle de refetch infinito" que los usuarios pidieron originalmente.

Presupuesto de rendimiento: <10s para 1 URL, <25s para 20. Puerto muerto de localhost devuelve LocalServerUnreachable en <2s sin consumir una ejecución de flujo de trabajo.

project

Acción	Parámetros	Resultado
get	{uuid}	Detalle del proyecto curado
list	{q?, page?, pageSize?}	Resúmenes paginados
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	Proyecto creado

Equipo y repositorio se resuelven por o bien uuid o bien nombre (coincidencia exacta sin distinción de mayúsculas/minúsculas; NotFound si ninguno, AmbiguousMatch si múltiples). No hay update/delete — renombra o elimina un proyecto desde la aplicación web de DebuggAI.

environment

Acción	Parámetros	Resultado
get	{uuid, projectUuid?}	Entorno con credenciales en línea (las contraseñas nunca se devuelven)
list	{projectUuid?, q?, page?, pageSize?}	Entornos paginados, cada uno con un array de credenciales
create	{name, url, description?, projectUuid?, credentials?}	Entorno creado (opcionalmente siembra credenciales)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}	Entorno parcheado; las operaciones de credenciales se ejecutan eliminar → actualizar → añadir
delete	{uuid, projectUuid?, confirm?}	Elimina el entorno (en cascada las credenciales) — requiere confirmación

projectUuid se auto-resuelve desde el repositorio git cuando se omite. Los fallos por credencial aparecen en credentialWarnings[] sin bloquear la operación del entorno.

test_suite

Acción	Parámetros	Resultado
list	{projectUuid|projectName, search?, page?, pageSize?}	Suites paginadas con estado + tasa de aprobación
create	{name, description, projectUuid|projectName}	Suite creada
run	{suiteUuid|(suiteName+project), targetUrl?}	Dispara todas las pruebas de forma asíncrona
results	{suiteUuid|(suiteName+project)}	Suite + resultados por prueba
delete	{suiteUuid|(suiteName+project), confirm?}	Eliminación suave — requiere confirmación

test_case

Acción	Parámetros	Resultado
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	Caso de prueba creado (no se ejecuta automáticamente)
update	{testUuid, name?, description?, agentTaskDescription?}	Caso de prueba parcheado
delete	{testUuid, confirm?}	Eliminación suave — requiere confirmación

executions

Acción	Parámetros	Resultado
get	{uuid}	Detalle completo (nodeExecutions + estado + errorInfo) + artefactos de captura de pantalla/gif
list	{status?, projectUuid?, page?, pageSize?}	Resúmenes paginados

Un 404 del backend se muestra como isError: true con {error: 'NotFound', message, uuid}. Las credenciales siempre se devuelven sin contraseñas.

Paginación

Cada respuesta en modo filtro está paginada. Forma de la respuesta:

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

Pasa page opcional (indexado en 1, por defecto 1) y pageSize (por defecto 20, máximo 200; los valores sobredimensionados se limitan). Ninguna respuesta se trunca silenciosamente.

Recursos

Junto con las herramientas, el servidor expone las entidades de solo lectura como recursos MCP para que los clientes puedan navegar y @-mencionarlos como contexto:

URI	Qué
debugg-ai://projects	Todos los proyectos (primera página)
debugg-ai://environments	Entornos para el proyecto auto-detectado
debugg-ai://executions	Ejecuciones recientes (primera página)
debugg-ai://project/{uuid}	Un proyecto, detalle completo
debugg-ai://environment/{uuid}	Un entorno (credenciales en línea, contraseñas redactadas)
debugg-ai://execution/{uuid}	Una ejecución, detalle completo del nodo + enlaces a artefactos

Las lecturas se despachan a los mismos manejadores que las herramientas project / environment / executions, por lo que los datos y la autenticación son idénticos. Los recursos son aditivos — los clientes sin soporte de recursos siguen usando las herramientas.

Invariantes de seguridad

• Las contraseñas son de solo escritura. Nunca aparecen en ningún cuerpo de respuesta de ninguna herramienta.
• Las URLs de túnel (*.ngrok.debugg.ai) se eliminan de todas las respuestas del agente de navegador, incluyendo el texto escrito por el agente.
• Los 404 del backend se muestran como isError: true con {error: 'NotFound', ...}, nunca como excepciones lanzadas.
• La falta de DEBUGGAI_API_KEY se muestra como un error de herramienta estructurado en la primera invocación — el servidor aún se registra y lista las herramientas normalmente.

Migración a v3.0.0 (herramientas basadas en acciones)

v3 consolidó las 20 herramientas por verbo en 8 herramientas basadas en acciones. Herramienta antigua → nueva tool {action}:

Eliminada	Reemplazo
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Eliminadas — usa la aplicación web de 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	Eliminado — siempre sin cabeza (headless)

Las acciones delete ahora requieren confirmación (aviso de elicitación, o confirm: true). Los clientes recogen la nueva superficie al reiniciar MCP.

Migración desde v1.x (cambio disruptivo en v2.0.0)

v2 colapsó una superficie de 22 herramientas a 11. Mapeo de herramienta antigua → nueva:

Eliminada	Reemplazo
list_projects, get_project	search_projects (modo uuid vs modo filtro)
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — credenciales en línea en cada entorno
create_credential	create_environment({credentials: [...]}) siembra, o update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — resolución de nombres con manejo de ambigüedad
list_executions, get_execution	search_executions
cancel_execution	Eliminada — el apagado del backend es automático

Cambios en la forma de la respuesta: el campo simple count en las respuestas de lista desapareció — usa pageInfo.totalCount.

Configuración

Var de entorno	Requerida	Propósito
DEBUGGAI_API_KEY	sí	Clave API del backend. Alias: DEBUGGAI_API_TOKEN, DEBUGGAI_JWT_TOKEN.
DEBUGGAI_API_URL	no	URL base del backend. Por defecto https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	no	token (por defecto) o bearer.
LOG_LEVEL	no	error / warn / info (por defecto) / debug.
POSTHOG_API_KEY	no	Sobrescribe la clave de proyecto de telemetría incrustada (ej. fork privado).
DEBUGGAI_TELEMETRY_DISABLED	no	Establecer a 1 / true / yes / on para deshabilitar la telemetría por completo.

DEBUGGAI_API_KEY=your_api_key

Transporte remoto / HTTP (opcional)

Por defecto, el servidor habla stdio (npx local). En su lugar, puede ejecutarse como un MCP remoto multi-usuario alojado sobre HTTP Transmisible sin estado + OAuth:

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

Es un Servidor de Recursos OAuth: cada POST /mcp necesita Authorization: Bearer <token>; los tokens faltantes o inválidos reciben un 401 con un WWW-Authenticate que apunta a los metadatos RFC 9728, y los clientes ejecutan el flujo OAuth contra el servidor de autorización anunciado. El portador tiene alcance de solicitud — api.debugg.ai lo valida.

Endpoint	Propósito
POST /mcp	MCP Streamable HTTP (protegido por portador)
GET /.well-known/oauth-protected-resource	Metadatos RFC 9728 (descubrimiento del servidor de autorización)
GET /health	Verificación de salud del balanceador de carga / ECS

Variable de entorno	Valor predeterminado	Propósito
DEBUGGAI_MCP_TRANSPORT	stdio	Establecer en http para el transporte remoto
PORT	3000	Puerto de escucha HTTP
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	URL pública del recurso de este servidor (RFC 9728 resource)
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	Servidor de autorización anunciado a los clientes
DEBUGGAI_TOKEN_TYPE	token	Establecer en bearer para que los tokens OAuth se reenvíen como Authorization: Bearer

Las instalaciones stdio no necesitan nada de esto.

Telemetría

El servidor MCP se distribuye con telemetría habilitada por defecto — una clave de proyecto PostHog embebida de solo escritura (phc_*) para que el equipo pueda observar tasas de aciertos de caché, cadencia de sondeo, confiabilidad del túnel y otras métricas operativas en toda la base instalada. Eventos capturados:

Evento	Cuándo
tool.executed / tool.failed	Por llamada a herramienta
workflow.executed	Por ejecución del agente navegador (lleva pollCount, durationMs, finalIntervalMs)
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	Por evento del ciclo de vida del túnel
template.lookup / project.lookup	Acierto/fallo de caché con durationMs en llamada en frío

Postura de privacidad:

• El ID distinto es SHA-256(api_key).slice(0, 16) — nunca la clave en bruto, sin PII.
• Las claves phc_* son de solo escritura por convención de PostHog; es seguro incrustarlas en el código fuente.
• Establezca DEBUGGAI_TELEMETRY_DISABLED=1 para excluirse por completo (se resuelve en un proveedor sin operación; ningún evento sale del proceso).

El modo activo se registra al iniciar:

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)

Desarrollo Local

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

El conjunto de pruebas genera el servidor MCP construido como un subproceso, ejercita cada herramienta contra un backend real y escribe artefactos por flujo en scripts/evals/artifacts/<timestamp>/. Consulte scripts/evals/flows/ para los escenarios individuales.

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

Este repositorio incluye un .mcp.json que registra un servidor con alcance de proyecto llamado debugg-ai-local que apunta a node dist/index.js — el código local recién construido. Solo se activa cuando el directorio de trabajo de Claude Code es este repositorio.

Sus otros proyectos deben usar el registro debugg-ai con alcance de usuario que obtiene el paquete npm publicado:

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

Después de editar el código aquí, ejecute npm run mcp:local (que solo reconstruye) para que la próxima invocación de debugg-ai-local recoja sus cambios.

Enlaces

Panel · Documentos · Incidencias · Discord

---

Licencia Apache-2.0 © 2025 DebuggAI