Debugg AI

공식

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

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

AI 브라우저 테스트 실행 — check_app_in_browser를 통해 자연어 지시로 모든 URL 또는 localhost 앱을 테스트하고, 스크린샷과 함께 통과/실패 결과를 반환하도록 요청하세요.
여러 페이지 빠르게 탐색 — probe_page를 사용하여 1-20개 URL의 콘솔 오류, 네트워크 문제, 렌더링 상태를 LLM 비용 없이 일괄 확인하세요.
테스트 환경 관리 — environment 도구를 사용하여 자격 증명 및 승인된 SSO 호스트가 포함된 환경을 생성, 업데이트 또는 나열하세요.
사이트 크롤링 트리거 — trigger_crawl을 실행하여 서버 측 브라우저 에이전트 크롤링으로 프로젝트의 지식 그래프를 채우세요.
테스트 스위트 실행 및 추적 — 스위트를 생성하고, 비동기 실행을 트리거하며, test_suite 작업을 통해 테스트별 결과를 가져오세요.
실행 아티팩트 검사 — executions를 통해 전체 실행 세부 정보, HAR 네트워크 추적, 콘솔 로그를 검색하여 런타임 문제를 디버깅하세요.

문서

Debugg AI — MCP 서버

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

설정

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

http://localhost:... URL 테스트에는 caddy 바이너리가 필요합니다 — check_app_in_browser, probe_page, trigger_crawl는 로컬 Caddy 리버스 프록시를 통해 localhost 대상을 터널링합니다. 이것은 자동으로 설치됩니다: @radically-straightforward/caddy npm 의존성이 npm install/npx 중에 플랫폼에 맞는 고정된 Caddy 릴리스를 다운로드합니다 — 일반적인 경우 직접 설치할 필요가 없습니다. 이제 이 패키지가 다운로드하는 유일한 바이너리입니다; 터널 클라이언트 자체는 순수 TypeScript입니다 — ngrok 에이전트를 가져오던 ngrok 패키지를 대체했습니다. 다운로드가 실행되지 않은 경우(npm install --ignore-scripts, 오프라인/에어갭 설치), CADDY_BIN을 자체 설치본으로 지정하세요 (brew install caddy / apt install caddy / 참조 caddyserver.com/docs/install) — 누락 시 첫 localhost-URL 호출에서 조용히 멈추는 대신 명확한 오류로 표시됩니다. 공개 URL 호출, 모든 비브라우저 도구, 그리고 자체 전용 터널을 사용하고 Caddy를 완전히 우회하는 test_suite {action:"run"}는 어느 쪽이든 필요하지 않습니다.

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

Dockerfile의 npm install 단계는 원칙적으로 로컬 설치와 동일한 자동 방식으로 caddy를 선택할 수 있습니다 — 하지만 현재 작성 시점 기준으로 Dockerfile는 빌드에 필요한 여러 디렉토리(handlers, tools, types, config)를 COPY하지 않으며 더 이상 존재하지 않는 tunnels/ 디렉토리를 참조하므로, 신규 빌드는 그 전에 실패할 가능성이 높습니다. 이것은 Caddy와 무관한 기존의 격차입니다. 현재 게시된 quinnosha/debugg-ai-mcp 이미지는 어쨌든 Caddy 의존성 이전의 것입니다 — 해당 이미지 내에서 check_app_in_browser/probe_page/trigger_crawl에 대한 localhost-URL 호출은 재빌드(Dockerfile 수정) 및 재게시, 또는 CADDY_BIN이 별도로 포함된 것을 가리킬 때까지 CaddyBinaryNotFoundError로 실패합니다. 공개 URL 호출, 비브라우저 도구, test_suite {action:"run"}는 어느 쪽이든 영향을 받지 않습니다.

도구

서버는 8개의 도구를 노출합니다: 세 개의 브라우저 도구와 관리 엔티티당 하나의 액션 기반 도구. 주요 도구는 check_app_in_browser (전체 AI 에이전트)와 probe_page (경량 no-LLM 페이지 프로브)입니다. 나머지 — project, environment, test_suite, test_case, executions — 각각 작업을 선택하는 action 판별자(예: {"action":"list"})를 받습니다. 파괴적인 delete 작업은 확인이 필요합니다(지원되는 경우 유도 프롬프트, 그렇지 않으면 confirm: true).

브라우저

`check_app_in_browser`

앱에 대해 AI 브라우저 에이전트를 실행합니다. 에이전트가 탐색, 상호작용하고 스크린샷과 함께 보고합니다. Localhost URL은 debugg 터널 서버를 통해 자동 터널링됩니다.

매개변수	유형	설명
`description`	문자열 필수	테스트할 내용 (자연어)
`url`	문자열 필수	대상 URL — `http://localhost:3000`는 자동 터널링됨
`environmentId`	문자열	특정 환경의 UUID
`credentialId`	문자열	특정 자격 증명의 UUID
`credentialRole`	문자열	역할로 자격 증명 선택 (예: `admin`, `guest`)
`username`	문자열	로그인용 사용자 이름 (임시 — 저장되지 않음)
`password`	문자열	로그인용 비밀번호 (임시 — 저장되지 않음)
`loginCredentials`	배열	에이전트가 작업 중에 만나는 로그인용 계정 — `[{username, password, label?}]`
`useEnvironmentCredentials`	부울	기본값 `true`. `false`는 환경의 저장된 자격 증명 자동 입력을 금지합니다; 계정 이름이 없으면 전혀 로그인하지 않음을 의미합니다
`freshSession`	부울	기본값 `false`. `true`는 해당 계정에 대해 유지된 웜 세션을 재사용하는 대신 실제 로그인을 강제합니다
`auth`	객체	인증 사전 조건 — `{precondition, entryUrl, deepUrl, environmentId, username, password}`
`repoName`	문자열	자동 감지된 git 저장소 이름 재정의 (예: `my-org/my-repo`)

호출당 하나의 집중된 검사. 에이전트는 약 25단계의 내부 예산이 있습니다; 더 큰 테스트 스위트는 여러 호출로 분할하세요.

자격 증명: 산문이 아닌 매개변수로 전달

description에서만 계정 이름을 지정하면 에이전트가 사용하지 않습니다 — 환경의 저장된 자격 증명으로 대체되며, 잘못된 계정에 대한 앱의 거부는 애플리케이션 실패처럼 보입니다. 매개변수로 전달하는 모든 것은 실행의 모든 로그인에 대해 환경 기본값보다 우선합니다 (첫 번째만이 아님):

username / password (또는 credentialId / credentialRole) — 실행의 신원.
auth.username / auth.password — auth.precondition: "login"도 사용할 때 사전 조건 로그인을 고정합니다.
loginCredentials — 에이전트가 작업 도중에 만나는 로그인 양식용 계정. 비밀번호 설정 → 로그인 화면으로 이동 → 방금 만든 계정으로 로그인 같은 흐름에 사용하며, 별도 호출로 분할하면 브라우저 상태가 손실됩니다.

기본 테스트 사용자로의 조용한 대체가 검사를 무효화할 때 useEnvironmentCredentials: false를 설정하세요.

크로스 도메인 SSO? 실행은 앱 자체 호스트와 하위 도메인에서만 자격 증명을 입력합니다; 다른 도메인의 로그인 페이지는 offscope_host로 거부됩니다. 환경의 authorizedCredentialHosts에 ID 공급자 호스트를 추가하세요 (environment 참조).

로그인이 필요 없는 페이지를 확인하나요? useEnvironmentCredentials: false를 전달하고 계정을 지정하지 마세요. 그 조합은 말 그대로 로그인하지 않음을 의미하며, 실행은 로그인 양식을 찾는 대신 인증을 완전히 건너뜁니다. 공개 페이지, 마케팅 사이트, 문서 및 인증 전 모든 것에 사용하세요. 또한 더 빠릅니다: 기본(auto)에서 에이전트는 페이지의 "로그인" 링크를 따라가서 평가 전에 환경의 저장된 계정을 시도합니다.

세션 재사용: 검사가 "로그인 양식 없음"을 보고하는 이유

실행은 매번 로그인하지 않습니다. 검증된 로그인 후 백엔드는 해당 계정의 세션을 캡처하고 동일한 신원에 대한 다음 실행에서 복원하여 로그인을 완전히 건너<0xEB><0x9A><0xB1>니다 — 이것이 검사가 submitted: false 및 로그인 양식 없음으로 정당하게 돌아올 수 있는 이유입니다: 이미 로그인되어 있었기 때문입니다. 복원된 실행은 logins에서 reason: "restored_session"으로 자신을 보고하므로, 실제로 양식을 찾지 못한 실행과 구분할 수 있습니다.

세션은 계정별로 키가 지정되므로 다른 계정을 지정해도 다른 사람의 세션을 재사용하지 않습니다. 재사용을 우회하는 두 가지 방법:

단일 호출에 freshSession: true — 이번 한 번 실제 로그인 후 다시 캡처합니다. 로그인 흐름 자체를 확인할 때, 저장된 세션이 오래되었다고 의심될 때, 또는 앱의 페르소나 간 유일한 경로가 로그아웃일 때 사용하세요.
environment 도구, action: "clearSessions" — 저장된 세션을 무효화하여 이후 실행이 로그인하도록 합니다. username / credentialId로 범위를 좁히세요; 범위 없는 삭제는 환경의 모든 계정이 재인증해야 하므로 확인이 필요합니다.

action: "sessions"를 사용하여 환경이 현재 보유한 것과 각각이 재사용될지 확인하세요.

결과는 실제 사용된 신원을 보고하므로 잘못된 신원이 깨진 앱으로 위장하는 대신 표시됩니다:

"logins": [
  { "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true },
  { "username": "qatest123@example.com", "source": "env_default", "submitted": false, "authenticated": false,
    "reason": "offscope_host", "detail": "refused to enter credentials on auth.idp.example: not part of this run's scope …" }
],
"credentialWarning": {
  "requested": "qa+invitefix@example.com",
  "used": ["qatest123@example.com"]
}

source은 task | explicit | credential_id (지정한 계정) 또는 env | env_default (환경의 저장된 계정)입니다. submitted은 자격 증명이 실제로 입력되고 제출된 경우에만 true입니다; reason은 발생한 상황을 말합니다 (예: offscope_host, restored_session), detail은 있는 경우 이에 대한 사람이 읽을 수 있는 설명입니다 — offscope_host 거부의 경우 호스트 이름과 권한 부여 방법을 지정합니다. credentialWarning은 계정을 지정했고 다른 계정에 대한 환경 기본값이 실제로 제출된 경우에만 나타납니다 — 거부되거나 건너뛴 로그인에는 절대 나타나지 않습니다. loginError은 지정된 계정을 확인할 수 없고 실행이 다른 계정으로 대체하지 않기로 결정한 경우 나타납니다.

모든 성공적인 실행은 스크린샷과 함께 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}를 폴링하세요. Authorization / Cookie / token/secret/api_key 헤더는 아티팩트가 저장되기 전에 서버 측에서 스크러빙됩니다.

`trigger_crawl`

프로젝트의 지식 그래프를 채우기 위해 서버 측 브라우저 에이전트 크롤을 실행합니다. Localhost URL은 자동으로 터널링됩니다. 성공적인 수집 시 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}와 함께 knowledgeGraph.skipped === false을 반환합니다. crawlSummary 및 knowledgeGraph은 백엔드의 크롤/가져오기 노드가 보고한 키만 전달합니다 — 누락된 수는 없으며 채워진 0가 아닙니다. browserSession 블록(HAR + 콘솔 로그 URL, 위와 동일한 형태)도 완료된 크롤에 존재합니다.

`probe_page`

경량 no-LLM 일괄 페이지 프로브. 1-20개 URL을 전달하세요; 각각 탐색하고 콘텐츠에 안착하며(DOM이 조용해짐, 제한됨 — 라이브 앱이 도달할 수 없는 네트워크 침묵에는 절대 안 함), 렌더링된 상태 — 스크린샷 + 페이지 메타데이터 + 구조화된 콘솔 오류 + 네트워크 요약을 반환합니다. 에이전트 루프, LLM 비용, 시나리오 어설션이 없습니다. "방금 /settings를 망가뜨렸나?", 리팩터링 후 다중 경로 스모크, CI PR별 스윕, check_app_in_browser의 60-150초 에이전트 루프가 과한 빠른 작동 확인에 사용하세요.

매개변수	유형	설명
`targets`	배열 필수	1-20개 항목: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	문자열 필수	공개 URL 또는 localhost (자동 터널링)
`targets[].waitForLoadState`	열거형	`'domcontentloaded'` (기본값, + 제한된 콘텐츠 안착) / `'load'` (타사 임베드도 차단) / `'networkidle'` (허용되지만 발행되지 않음 — 라이브 사이트의 네트워크는 유휴 상태가 되지 않음)
`targets[].waitForSelector`	문자열	탐색 후 대기할 선택적 CSS 선택자
`targets[].timeoutMs`	숫자	URL당 시간 초과, 1000-30000 (기본값 10000)
`includeHtml`	부울	각 결과에 원시 HTML 반환 (기본값 false)
`captureScreenshots`	부울	대상당 PNG 하나 반환 (기본값 true)

배치의 모든 대상은 하나의 세션 터널을 공유하지만, 동일 포트(또는 모두 공개) 배치만 단일 백엔드 실행을 공유합니다 — 한 호출에서 한 포트의 5개 URL은 5개의 병렬 단일 URL 호출보다 훨씬 빠릅니다. 여러 로컬 포트를 혼합한 배치는 포트 그룹당 하나의 순차 백엔드 실행으로 분해됩니다(여전히 한 호출, 원래 순서의 병합된 results[] 하나, 그러나 N개의 백엔드 왕복 — 느리지만 거부되지 않음). URL당 error 필드는 배치 복원력을 유지합니다: 단일 실패 대상이 다른 대상에 실패를 일으키지 않습니다. networkSummary 집계 키는 origin + pathname — 재요청 루프(동일 엔드포인트를 반복 호출하는 ?n=0..4)는 카운트와 함께 단일 항목으로 축소되므로, /api/poll가 count: 47와 함께 나타나는 것이 사용자들이 원래 요청했던 실행 가능한 "무한 재요청 루프" 신호입니다.

성능 예산: URL 1개에 <10초, 20개에 <25초. 로컬호스트 죽은 포트는 워크플로우 실행을 소모하지 않고 <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?, authorizedCredentialHosts?}`	생성된 환경(선택적으로 자격 증명 시드)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?}`	패치된 환경; 자격 증명 작업은 제거 → 업데이트 → 추가 순서로 실행
`delete`	`{uuid, projectUuid?, confirm?}`	환경 삭제(자격 증명 계단식 삭제) — 확인 필요
`sessions`	`{uuid, username?, credentialId?}`	환경이 보유한 캡처된 로그인 세션(계정별, 각각 자체 `isUsable` 포함)
`clearSessions`	`{uuid, username?, credentialId?, confirm?}`	무효화하여 다음 실행 시 실제 로그인 — 범위 없는 삭제는 확인 필요

projectUuid는 생략 시 git 저장소에서 자동 해석됩니다. 개별 자격 증명 실패는 환경 작업을 차단하지 않고 credentialWarnings[]에 표시됩니다.

authorizedCredentialHosts는 앱 자체 호스트 외에 실행이 이 환경의 자격 증명에 들어갈 수 있는 호스트를 나열합니다 — 크로스 도메인 SSO의 경우 IdP 호스트를 여기에 추가하세요(예: ["auth.example.com"]). 호스트 이름만 가능: 스킴, 경로, 포트 또는 와일드카드 없음(앱 호스트의 하위 도메인은 이미 범위에 포함). update에서 목록을 대체하고, []는 목록을 지웁니다. get/list는 서버가 지원할 때 목록을 반환합니다. 응답은 저장된 목록을 에코합니다. 서버가 저장하지 않은 경우(이전 서버는 필드를 무시), 결과는 조용한 성공 대신 authorizedCredentialHostsWarning: {requested, returned}을 전달합니다.

sessions / clearSessions는 백엔드가 로그인을 건너뛰기 위해 재사용하는 웜 인증 세션을 관리합니다(세션 재사용 참조). 세션 내용은 절대 반환되지 않습니다 — 세션 쿠키는 베어러 자격 증명입니다. clearSessions은 행을 삭제하는 대신 세션을 무효로 표시하므로 캡처 기록은 읽을 수 있는 상태로 유지되면서 재사용이 즉시 중지됩니다.

`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}로 표시됩니다. 자격 증명은 항상 비밀번호 없이 반환됩니다.

페이지네이션

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

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

선택적 page(1-인덱스, 기본값 1) 및 pageSize(기본값 20, 최대 200; 초과 값은 클램프됨)를 전달하세요. 어떤 응답도 조용히 잘리지 않습니다.

get는 단일 이름 아래 하나의 객체를 반환합니다 — {project}, {execution}, {project, environment} — pageInfo 없이.

리소스

도구와 함께, 서버는 읽기 전용 엔티티를 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(*.tunnel.debugg.ai, 그리고 과거 실행이 여전히 참조하는 폐기된 *.ngrok.debugg.ai)은 에이전트가 작성한 텍스트를 포함한 모든 브라우저 에이전트 응답에서 제거됩니다.
백엔드의 404는 예외를 던지는 대신 isError: true와 {error: 'NotFound', ...}로 표시됩니다.
누락된 DEBUGGAI_API_KEY는 첫 호출 시 구조화된 도구 오류로 표시됩니다 — 서버는 여전히 도구를 정상적으로 등록하고 나열합니다.

v6.0.0으로 마이그레이션(백엔드 판정, MCP 작성 텍스트 없음)

실행 판정은 pass | fail | error이며, 백엔드의 reason가 그대로 전달됩니다. 테스트를 시도하지 않은 실행은 outcome: null, skipped: true, skipReason로 읽힙니다.

제거됨	대체
`success`	`outcome`
`failureCategory`	`outcome` + `reason`
`stepsTaken` / `stepsBudget` / `stepsRemaining`	`budget: {maxSteps, usedSteps}`
`failedNode`	`errorInfo`
`get` → `projects[0]` / `executions[0]` / `environments[0]` + `pageInfo` + `filter`	`{project}` / `{execution}` / `{project, environment}`
`message` / `note` 경고 및 결과	구조화된 필드만

전체 목록: CHANGELOG.md 6.0.0.

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`.
`DEBUGGAI_EVAL_TEMPLATE`	아니요	`check_app_in_browser`가 디스패치하는 App Evaluation 워크플로우 슬러그를 재정의합니다. 기본값: `flow/e2es/app-eval`. 디스패치는 이 슬러그에 고정되므로 백엔드 템플릿 이름 변경이 깨뜨릴 수 없습니다.
`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 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`	OAuth 토큰이 `Authorization: Bearer`로 전달되도록 `bearer`로 설정

stdio 설치에는 이 중 어떤 것도 필요하지 않습니다.

다중 복제본 배포(롤아웃 전 go/no-go): 터널 상태(세션 터널, 해당 Caddy 인스턴스 및 포트 라우트 잠금)는 프로세스 내에 있으며, 베어러 토큰의 해시로 호출자별 키가 지정됩니다 — 교차 프로세스 조정이 없습니다. 일반 라운드 로빈 로드 밸런서 뒤에서 여러 복제본을 실행하면 한 호출자의 호출이 다른 복제본에 도달하여 전체 세션에 대해 하나가 아닌 도달한 복제본당 하나의 터널을 생성할 수 있습니다(복제본 수로 제한, 기존 55분 유휴 자동 종료로 자가 치유 — 단일 도구 호출이 전체 기간 동안 한 복제본에 유지되므로 교차 세션 정확성 버그는 절대 아님). 다중 복제본 HTTP 배포에서 의도된 "세션당 하나의 터널" 동작을 얻으려면 로드 밸런서에서 세션 고정 라우팅을 구성하세요(getSessionKey()가 파생하는 동일한 ID에 키가 지정된 스티키/일관성 해시 — 실제로는 호출자의 Authorization 베어러 토큰). 전체 추론과 구성되지 않은 경우의 정직한 저하 경로는 docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1을 참조하세요.

텔레메트리

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) — 원시 키가 절대 아니며, PII가 없습니다.
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`

이 저장소에는 .mcp.json이 포함되어 있으며, debugg-ai-local라는 이름의 프로젝트 범위 서버를 node dist/index.js — 방금 빌드된 로컬 코드를 가리키도록 등록합니다. 이는 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 호출 시 변경 사항이 반영됩니다.

링크

대시보드 · 문서 · 이슈 · 디스코드