Debugg AI

официальный

Предоставьте вашим агентам генерации кода возможность создавать и запускать сквозные тесты без конфигурации для новых изменений кода в удаленных браузерах через платформу тестирования Debugg AI.

GitHub

Что можно делать с Debugg AI MCP?

Запустите AI-браузерного агента для любого URL — опишите, что нужно протестировать на естественном языке, и check_app_in_browser выполнит навигацию, взаимодействие и вернёт результат (пройдено/не пройдено) со скриншотами.
Проверьте несколько страниц без затрат на LLM — отправьте до 20 URL-адресов в probe_page для быстрого получения скриншотов, ошибок консоли и сводок по сети в одном пакете.
Запустите обход графа знаний — используйте trigger_crawl, чтобы AI-агент исследовал ваше приложение и заполнил граф знаний проекта.
Управляйте наборами тестов и тестовыми случаями — создавайте, просматривайте, запускайте и проверяйте результаты наборов тестов через test_suite, а также определяйте отдельные случаи с помощью test_case.
Просматривайте артефакты выполнения — получайте полные детали выполнения, скриншоты, HAR-трассировки и журналы консоли через executions для отладки ошибок.
Просматривайте проекты, окружения и выполнения как ресурсы — ссылайтесь на сущности напрямую через URI debugg-ai:// для получения контекста без вызова инструментов.

Документация

Debugg AI — MCP-сервер

Тестирование в браузере на базе ИИ через Model Context Protocol. Укажите любой URL (или localhost) и опишите, что нужно протестировать — ИИ-агент исследует ваше приложение и вернет результат «пройден/не пройден» со скриншотами.

Настройка

Требуется Node.js 20.20.0 или новее (транзитивное требование от posthog-node@^5.26.0).

Получите API-ключ на debugg.ai, затем добавьте в конфигурацию MCP-клиента:

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

Или с помощью Docker:

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

Инструменты

Сервер предоставляет 8 инструментов: три браузерных инструмента плюс по одному инструменту на основе действий для каждой управляемой сущности. Основные инструменты — check_app_in_browser (полноценный ИИ-агент) и probe_page (легковесная проверка страницы без LLM). Остальные — project, environment, test_suite, test_case, executions — каждый принимает дискриминатор action (например, {"action":"list"}), который выбирает операцию. Деструктивные действия delete требуют подтверждения (запрос на подтверждение, где поддерживается, иначе confirm: true).

Браузер

`check_app_in_browser`

Запускает ИИ-агента браузера для вашего приложения. Агент перемещается, взаимодействует и сообщает о результатах со скриншотами. URL-адреса localhost автоматически туннелируются через ngrok.

Параметр	Тип	Описание
`description`	string обязательный	Что тестировать (на естественном языке)
`url`	string обязательный	Целевой URL — `http://localhost:3000` туннелируется автоматически
`environmentId`	string	UUID конкретного окружения
`credentialId`	string	UUID конкретных учетных данных
`credentialRole`	string	Выбор учетных данных по роли (например, `admin`, `guest`)
`username`	string	Имя пользователя для входа (временное — не сохраняется)
`password`	string	Пароль для входа (временный — не сохраняется)
`repoName`	string	Переопределить автоматически определенное имя git-репозитория (например, `my-org/my-repo`)

Одна целенаправленная проверка за вызов. У агента внутренний бюджет ~25 шагов; разделяйте более крупные наборы тестов на несколько вызовов.

Каждый успешный запуск возвращает блок browserSession вместе со скриншотом — предварительно подписанные URL-адреса S3 для захваченного HAR (полная трассировка сети) и журнала консоли (каждое сообщение JS-консоли). Используйте их для обнаружения циклов повторной загрузки, ошибок гидратации и других проблем времени выполнения, которые проходят проверки типов и модульные тесты:

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

URL-адреса — это краткосрочные предварительно подписанные S3 — повторно запросите родительское выполнение через executions {action:"get", uuid} для обновления. harStatus / consoleLogStatus уточняют 'downloaded' (URL доступен для загрузки), 'not_available' (страница ничего не выдала), 'failed' (сбой захвата). При новом запуске URL-адреса обычно null, потому что захват загружается асинхронно после завершения работы агента — опрашивайте executions {action:"get", uuid: executionId}, пока статус не достигнет 'downloaded'. Заголовки Authorization / Cookie / token/secret/api_key удаляются на стороне сервера перед сохранением артефактов.

`trigger_crawl`

Запускает серверный обход браузерным агентом для заполнения графа знаний проекта. URL-адреса localhost туннелируются автоматически. Возвращает {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} с knowledgeGraph.imported === true при успешном приеме. Блок browserSession (URL-адреса HAR + журнала консоли, той же формы, что и выше) также присутствует при завершенных обходах.

`probe_page`

Легковесная пакетная проверка страниц без LLM. Передайте 1-20 URL-адресов; каждый из них загружается, ожидает загрузки и возвращает отрендеренное состояние — скриншот + метаданные страницы + структурированные ошибки консоли + сводку по сети. Без цикла агента, без затрат на LLM, без утверждений сценария. Используйте для проверок типа «не сломал ли я /settings?», многостраничного дымового тестирования после рефакторинга, проверок каждого PR в CI и быстрых проверок работоспособности, где цикл агента check_app_in_browser длительностью 60-150 секунд избыточен.

Параметр	Тип	Описание
`targets`	array обязательный	1-20 записей: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	string обязательный	Публичный URL или localhost (автоматическое туннелирование)
`targets[].waitForLoadState`	enum	`'load'` (по умолчанию) / `'domcontentloaded'` / `'networkidle'`
`targets[].waitForSelector`	string	Необязательный CSS-селектор для ожидания после навигации
`targets[].timeoutMs`	number	Тайм-аут для каждого URL, 1000-30000 (по умолчанию 10000)
`includeHtml`	boolean	Возвращать необработанный HTML в каждом результате (по умолчанию false)
`captureScreenshots`	boolean	Возвращать один PNG для каждой цели (по умолчанию true)

Весь пакет использует одно внутреннее выполнение + сеанс браузера + туннель — 5 URL-адресов в одном вызове значительно быстрее, чем 5 параллельных вызовов с одним URL. Поле error для каждого URL сохраняет устойчивость пакета: сбой одной цели не приводит к сбою других.

Ключ агрегации networkSummary — origin + pathname — циклы повторной загрузки (?n=0..4, многократно обращающийся к одной и той же конечной точке) сворачиваются в одну запись с подсчетом, так что /api/poll, отображаемый с count: 47, является действенным сигналом «бесконечного цикла повторной загрузки», который изначально запрашивали пользователи.

Бюджет производительности: <10 с для 1 URL, <25 с для 20. Недоступный порт localhost возвращает LocalServerUnreachable менее чем за 2 с, не расходуя выполнение рабочего процесса.

`project`

Действие	Параметры	Результат
`get`	`{uuid}`	Детальная информация о курируемом проекте
`list`	`{q?, page?, pageSize?}`	Постраничные сводки
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	Созданный проект

Команда и репозиторий определяются либо по uuid, либо по имени (точное совпадение без учета регистра; NotFound, если нет, AmbiguousMatch, если несколько). Нет update/delete — переименуйте или удалите проект из веб-приложения DebuggAI.

`environment`

Действие	Параметры	Результат
`get`	`{uuid, projectUuid?}`	Окружение с встроенными учетными данными (пароли никогда не возвращаются)
`list`	`{projectUuid?, q?, page?, pageSize?}`	Постраничный список окружений, каждое с массивом учетных данных
`create`	`{name, url, description?, projectUuid?, credentials?}`	Созданное окружение (опционально заполняет учетные данные)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Исправленное окружение; операции с учетными данными выполняются удалить → обновить → добавить
`delete`	`{uuid, projectUuid?, confirm?}`	Удаляет окружение (каскадно удаляет учетные данные) — требуется подтверждение

projectUuid автоматически определяется из git-репозитория, если не указан. Сбои отдельных учетных данных отображаются в credentialWarnings[], не блокируя операцию с окружением.

`test_suite`

Действие	Параметры	Результат
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	Постраничный список наборов тестов со статусом + процентом прохождения
`create`	`{name, description, projectUuid\|projectName}`	Созданный набор тестов
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	Асинхронно запускает все тесты
`results`	`{suiteUuid\|(suiteName+project)}`	Набор тестов + результаты по каждому тесту
`delete`	`{suiteUuid\|(suiteName+project), confirm?}`	Мягкое удаление — требуется подтверждение

`test_case`

Действие	Параметры	Результат
`create`	`{name, description, agentTaskDescription, suiteUuid\|(suiteName+project), relativeUrl?, maxSteps?}`	Созданный тестовый случай (не запускается автоматически)
`update`	`{testUuid, name?, description?, agentTaskDescription?}`	Исправленный тестовый случай
`delete`	`{testUuid, confirm?}`	Мягкое удаление — требуется подтверждение

`executions`

Действие	Параметры	Результат
`get`	`{uuid}`	Полная информация (`nodeExecutions` + состояние + errorInfo) + артефакты скриншотов/gif
`list`	`{status?, projectUuid?, page?, pageSize?}`	Постраничные сводки

Ошибка 404 от бэкенда отображается как isError: true с {error: 'NotFound', message, uuid}. Учетные данные всегда возвращаются без паролей.

Пагинация

Каждый ответ в режиме фильтрации постраничный. Формат ответа:

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

Передайте необязательные page (индексация с 1, по умолчанию 1) и pageSize (по умолчанию 20, максимум 200; завышенные значения ограничиваются). Ни один ответ никогда не усекается без предупреждения.

Ресурсы

Наряду с инструментами сервер предоставляет сущности только для чтения как MCP ресурсы, чтобы клиенты могли просматривать их и @-упоминать как контекст:

URI	Что
`debugg-ai://projects`	Все проекты (первая страница)
`debugg-ai://environments`	Окружения для автоматически определенного проекта
`debugg-ai://executions`	Последние выполнения (первая страница)
`debugg-ai://project/{uuid}`	Один проект, полная информация
`debugg-ai://environment/{uuid}`	Одно окружение (учетные данные встроены, пароли скрыты)
`debugg-ai://execution/{uuid}`	Одно выполнение, полная информация об узле + ссылки на артефакты

Чтения направляются тем же обработчикам, что и инструменты project / environment / executions, поэтому данные и аутентификация идентичны. Ресурсы являются дополнительными — клиенты без поддержки ресурсов продолжают использовать инструменты.

Инварианты безопасности

Пароли предназначены только для записи. Они никогда не появляются ни в одном теле ответа от любого инструмента.
URL-адреса туннелей (*.ngrok.debugg.ai) удаляются из всех ответов браузерного агента, включая текст, созданный агентом.
Ошибки 404 от бэкенда отображаются как isError: true с {error: 'NotFound', ...}, никогда как выброшенные исключения.
Отсутствующий DEBUGGAI_API_KEY отображается как структурированная ошибка инструмента при первом вызове — сервер по-прежнему регистрирует и перечисляет инструменты в обычном режиме.

Миграция на v3.0.0 (инструменты на основе действий)

Версия 3 объединила 20 инструментов для каждого глагола в 8 инструментов на основе действий. Старый инструмент → новый tool {action}:

Удален	Замена
`search_projects`	`project {action:"get"}` / `project {action:"list"}`
`create_project`	`project {action:"create"}`
`update_project`, `delete_project`	Удалены — используйте веб-приложение 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`	Удален — всегда безголовый режим

Действия delete теперь требуют подтверждения (запрос на подтверждение или confirm: true). Клиенты получают новую поверхность при перезапуске MCP.

Миграция с v1.x (критическое изменение в v2.0.0)

Версия 2 сократила поверхность с 22 инструментов до 11. Сопоставление старых инструментов с новыми:

Удален	Замена
`list_projects`, `get_project`	`search_projects` (режим uuid против режима фильтра)
`list_environments`, `get_environment`	`search_environments`
`list_credentials`, `get_credential`	`search_environments` — учетные данные встроены в каждое окружение
`create_credential`	`create_environment({credentials: [...]})` заполнение, или `update_environment({addCredentials: [...]})`
`update_credential`	`update_environment({updateCredentials: [{uuid, ...patch}]})`
`delete_credential`	`update_environment({removeCredentialIds: [uuid]})`
`list_teams`, `list_repos`	`create_project({teamName, repoName})` — разрешение имен с обработкой неоднозначности
`list_executions`, `get_execution`	`search_executions`
`cancel_execution`	Удален — завершение работы бэкенда автоматическое

Изменения формата ответа: поле count в ответах списка больше нет — используйте pageInfo.totalCount.

Конфигурация

Переменная окружения	Обязательна	Назначение
`DEBUGGAI_API_KEY`	да	Ключ API бэкенда. Псевдонимы: `DEBUGGAI_API_TOKEN`, `DEBUGGAI_JWT_TOKEN`.
`DEBUGGAI_API_URL`	нет	Базовый URL бэкенда. По умолчанию `https://api.debugg.ai`.
`DEBUGGAI_TOKEN_TYPE`	нет	`token` (по умолчанию) или `bearer`.
`LOG_LEVEL`	нет	`error` / `warn` / `info` (по умолчанию) / `debug`.
`POSTHOG_API_KEY`	нет	Переопределить встроенный ключ проекта телеметрии (например, для частного форка).
`DEBUGGAI_TELEMETRY_DISABLED`	нет	Установите в `1` / `true` / `yes` / `on`, чтобы полностью отключить телеметрию.

DEBUGGAI_API_KEY=your_api_key

Удаленная / HTTP-передача (необязательно)

По умолчанию сервер использует stdio (локальный npx). Вместо этого он может работать как размещенный, многопользовательский удаленный MCP через Stateless Streamable HTTP + OAuth:

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

Это OAuth сервер ресурсов: каждый POST /mcp требует Authorization: Bearer <token>; отсутствующие/недействительные токены получают 401 с WWW-Authenticate, указывающим на метаданные RFC 9728, а клиенты выполняют поток OAuth против объявленного сервера авторизации. Токен-носитель ограничен запросом — api.debugg.ai проверяет его.

Конечная точка	Назначение
`POST /mcp`	MCP Streamable HTTP (защищено токеном-носителем)
`GET /.well-known/oauth-protected-resource`	Метаданные RFC 9728 (обнаружение сервера авторизации)
`GET /health`	Проверка работоспособности балансировщика / ECS

Переменная окружения	По умолчанию	Назначение
`DEBUGGAI_MCP_TRANSPORT`	`stdio`	Установите в `http` для удалённого транспорта
`PORT`	`3000`	Порт прослушивания HTTP
`DEBUGGAI_MCP_PUBLIC_URL`	`https://mcp.debugg.ai`	Публичный URL-адрес ресурса этого сервера (RFC 9728 `resource`)
`DEBUGGAI_OAUTH_ISSUER`	`https://auth.debugg.ai`	Сервер авторизации, объявляемый клиентам
`DEBUGGAI_TOKEN_TYPE`	`token`	Установите в `bearer`, чтобы токены OAuth пересылались как `Authorization: Bearer`

Для установок через stdio ничего из этого не требуется.

Телеметрия

MCP-сервер поставляется с телеметрией, включённой по умолчанию — встроенный ключ проекта PostHog только для записи (phc_*), чтобы команда могла отслеживать частоту попаданий в кеш, периодичность опросов, надёжность туннеля и другие операционные метрики по всей базе установок. Захватываемые события:

Событие	Когда
`tool.executed` / `tool.failed`	При каждом вызове инструмента
`workflow.executed`	При каждом выполнении браузерного агента (несёт `pollCount`, `durationMs`, `finalIntervalMs`)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	При каждом событии жизненного цикла туннеля
`template.lookup` / `project.lookup`	Попадание/промах кеша с `durationMs` при холодном вызове

Позиция по конфиденциальности:

Идентификатор — SHA-256(api_key).slice(0, 16) — никогда не содержит исходный ключ, никаких персональных данных.
Ключи phc_* доступны только для записи по соглашению PostHog; их безопасно встраивать в исходный код.
Установите DEBUGGAI_TELEMETRY_DISABLED=1 для полного отказа (превращается в пустого провайдера; никакие события не покидают процесс).

Активный режим регистрируется при запуске:

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)

Локальная разработка

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

Набор тестов запускает собранный MCP-сервер как подпроцесс, проверяет каждый инструмент на реальном бэкенде и записывает артефакты каждого потока в scripts/evals/artifacts/<timestamp>/. См. scripts/evals/flows/ для отдельных сценариев.

Регистрация MCP: `debugg-ai-local` против `debugg-ai`

Этот репозиторий поставляется с .mcp.json, который регистрирует сервер с областью проекта с именем debugg-ai-local, указывающий на node dist/index.js — только что собранный локальный код. Он активируется только тогда, когда рабочий каталог Claude Code является этим репозиторием.

В ваших других проектах следует использовать регистрацию debugg-ai с областью пользователя, которая загружается из опубликованного пакета npm:

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

После редактирования кода здесь запустите npm run mcp:local (который просто пересобирает), чтобы следующий вызов debugg-ai-local подхватил ваши изменения.

Ссылки

Панель управления · Документация · Задачи · Discord