Debugg AI

공식

코드 생성 에이전트가 Debugg AI 테스팅 플랫폼을 통해 원격 브라우저에서 새로운 코드 변경 사항에 대해 0-구성 엔드-투-엔드 테스트를 생성 및 실행할 수 있도록 지원합니다.

GitHub

Debugg AI MCP(으)로 무엇을 할 수 있나요?

모든 URL에 대해 AI 브라우저 에이전트 실행 — 자연어로 테스트할 내용을 설명하면 check_app_in_browser가 탐색, 상호작용을 수행하고 스크린샷과 함께 합격/불합격 결과를 반환합니다.
LLM 비용 없이 여러 페이지 탐색 — 최대 20개의 URL을 probe_page에 전송하여 단일 배치로 빠른 스크린샷, 콘솔 오류 및 네트워크 요약을 확인합니다.
지식 그래프 크롤링 트리거 — trigger_crawl을 사용하여 AI 에이전트가 앱을 탐색하고 프로젝트의 지식 그래프를 채우도록 합니다.
테스트 스위트 및 케이스 관리 — test_suite를 통해 테스트 스위트를 생성, 목록 조회, 실행 및 결과를 확인하고, test_case로 개별 케이스를 정의합니다.
실행 아티팩트 검사 — executions를 통해 전체 실행 세부 정보, 스크린샷, HAR 추적 및 콘솔 로그를 검색하여 실패를 디버깅합니다.
프로젝트, 환경 및 실행을 리소스로 탐색 — 도구를 호출하지 않고 컨텍스트를 위해 debugg-ai:// URI를 통해 엔터티를 직접 참조합니다.

문서

Debugg AI — MCP 서버

모델 컨텍스트 프로토콜을 통한 AI 기반 브라우저 테스트. URL(또는 localhost)을 지정하고 테스트할 내용을 설명하면 AI 에이전트가 앱을 탐색하고 스크린샷과 함께 통과/실패 결과를 반환합니다.

설정

Node.js 20.20.0 이상 필요 (posthog-node@^5.26.0의 전이적 요구 사항).

debugg.ai에서 API 키를 발급받은 후 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(완전한 AI 에이전트)과 probe_page(LLM을 사용하지 않는 경량 페이지 프로브)입니다. 나머지 — project, environment, test_suite, test_case, executions — 는 각각 작업을 선택하는 action 구분자(예: {"action":"list"})를 받습니다. 파괴적인 delete 작업은 확인이 필요합니다(지원되는 경우 확인 프롬프트, 그렇지 않으면 confirm: true).

브라우저

`check_app_in_browser`

앱에 대해 AI 브라우저 에이전트를 실행합니다. 에이전트가 탐색하고 상호작용한 후 스크린샷과 함께 결과를 보고합니다. Localhost URL은 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 블록이 반환됩니다 — 캡처된 HAR(전체 네트워크 추적) 및 콘솔 로그(모든 JS 콘솔 메시지)에 대한 사전 서명된 S3 URL입니다. 이를 사용하여 유형 검사 및 단위 테스트를 통과하는 리페치 루프, 하이드레이션 오류 및 기타 런타임 문제를 감지하세요:

"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입니다 — 상태가 'downloaded'에 도달할 때까지 executions {action:"get", uuid: executionId}을 폴링하세요. 인증 / 쿠키 / token/secret/api_key 헤더는 아티팩트가 저장되기 전에 서버 측에서 제거됩니다.

`trigger_crawl`

프로젝트의 지식 그래프를 채우기 위해 서버 측 브라우저 에이전트 크롤링을 실행합니다. Localhost URL은 자동으로 터널링됩니다. 성공적으로 수집되면 knowledgeGraph.imported === true와 함께 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}를 반환합니다. 완료된 크롤링에는 browserSession 블록(위와 동일한 형태의 HAR + 콘솔 로그 URL)도 포함됩니다.

`probe_page`

LLM을 사용하지 않는 경량 배치 페이지 프로브. 1-20개의 URL을 전달하면 각 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 호출보다 훨씬 빠릅니다. URL별 error 필드는 배치 복원력을 유지하여 단일 대상 실패가 다른 대상에 영향을 미치지 않습니다.

networkSummary 집계 키는 origin + pathname입니다 — 리페치 루프(?n=0..4이 동일한 엔드포인트를 반복적으로 호출)는 개수와 함께 단일 항목으로 축소되므로, /api/poll가 count: 47와 함께 표시되면 사용자가 원래 요청했던 실행 가능한 "무한 리페치 루프" 신호입니다.

성능 예산: URL 1개당 10초 미만, 20개당 25초 미만. Localhost의 죽은 포트는 워크플로우 실행을 소모하지 않고 2초 이내에 LocalServerUnreachable을 반환합니다.

`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는 {error: 'NotFound', message, uuid}와 함께 isError: true로 표시됩니다. 자격 증명은 항상 비밀번호 없이 반환됩니다.

페이지네이션

모든 필터 모드 응답은 페이지네이션됩니다. 응답 형태:

{
  "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는 {error: 'NotFound', ...}와 함께 isError: true로 표시되며, 예외가 발생하지 않습니다.
DEBUGGAI_API_KEY이 누락된 경우 첫 번째 호출 시 구조화된 도구 오류로 표시됩니다 — 서버는 여전히 정상적으로 도구를 등록하고 나열합니다.

v3.0.0으로 마이그레이션 (액션 기반 도구)

v3에서는 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의 주요 변경 사항)

v2에서는 22개 도구 구성을 11개로 축소했습니다. 이전 도구 → 새 도구 매핑:

제거됨	대체
`list_projects`, `get_project`	`search_projects` (uuid 모드 vs 필터 모드)
`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)를 사용합니다. 대신 상태 비저장 Streamable HTTP + OAuth를 통해 호스팅된 다중 사용자 원격 MCP로 실행할 수 있습니다:

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

이것은 OAuth 리소스 서버입니다: 모든 POST /mcp에는 Authorization: Bearer <token>이(가) 필요하며, 누락되거나 유효하지 않은 토큰은 RFC 9728 메타데이터를 가리키는 WWW-Authenticate과 함께 401을(를) 받고, 클라이언트는 광고된 인증 서버에 대해 OAuth 흐름을 실행합니다. 베어러는 요청 범위로 지정되며 — api.debugg.ai이(가) 이를 검증합니다.

엔드포인트	목적
`POST /mcp`	MCP 스트리밍 가능 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`	OAuth 토큰이 `Authorization: Bearer`(으)로 전달되도록 `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`을(를) 포함한 캐시 적중/미스

개인정보 보호 방침:

고유 ID는 SHA-256(api_key).slice(0, 16)입니다 — 원시 키가 아니며, 개인 식별 정보가 없습니다.
phc_* 키는 PostHog 규칙에 따라 쓰기 전용이므로 소스에 포함해도 안전합니다.
완전히 옵트아웃하려면 DEBUGGAI_TELEMETRY_DISABLED=1을(를) 설정하세요 (no-op 제공자로 해석되어 프로세스에서 이벤트가 나가지 않음).

활성 모드는 부팅 시 기록됩니다:

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` vs `debugg-ai`

이 저장소는 새로 빌드된 로컬 코드인 node dist/index.js을(를) 가리키는 debugg-ai-local이라는 프로젝트 범위 서버를 등록하는 .mcp.json을(를) 제공합니다. 이는 Claude Code의 작업 디렉터리가 이 저장소일 때만 활성화됩니다.

다른 프로젝트에서는 게시된 npm 패키지에서 가져오는 사용자 범위 debugg-ai 등록을 사용해야 합니다:

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

Debugg AI

Debugg AI MCP(으)로 무엇을 할 수 있나요?

문서

Debugg AI — MCP 서버

설정

도구

브라우저

check_app_in_browser

trigger_crawl

probe_page

project

environment

test_suite

test_case

executions