Debugg AI

Debugg AI — MCP 서버

AI 기반 브라우저 테스트를 Model Context Protocol을 통해 제공합니다. 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 릴리스를 다운로드합니다. 이 프로젝트가 이미 ngrok 바이너리에 대해 하는 것과 동일합니다 — 일반적인 경우 직접 설치할 필요가 없습니다. 해당 다운로드가 실행되지 않은 경우(npm install --ignore-scripts, 오프라인/에어갭 설치), CADDY_BIN을 자체 설치로 지정하세요 (brew install caddy / apt install caddy / 참조 caddyserver.com/docs/install) — 누락된 경우 첫 번째 localhost-URL 호출에서 명확한 오류로 표시되며, 조용히 멈추지 않습니다. 공개 URL 호출, 모든 비브라우저 도구, 그리고 test_suite {action:"run"}(자체 전용 터널을 사용하고 Caddy를 완전히 우회)는 어느 쪽이든 필요하지 않습니다.

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은 빌드에 필요한 여러 디렉토리를 COPY하지 않습니다 (handlers, tools, types, config) 그리고 더 이상 존재하지 않는 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은 ngrok을 통해 자동 터널링됩니다.

매개변수	유형	설명
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을 설정하세요.

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

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

실행은 매번 로그인하지 않습니다. 검증된 로그인 후 백엔드는 해당 계정의 세션을 캡처하고 동일한 신원에 대한 다음 실행에서 복원하여 로그인을 완전히 건너뜁니다 — 이것이 검사가 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 }
],
"credentialWarning": {
  "requested": "qa+invitefix@example.com",
  "used": ["qatest123@example.com"],
  "message": "This run signed in with an environment default credential even though '…' was specified. …"
}

source은 task | explicit | credential_id (지정한 계정) 또는 env | env_default (환경의 저장된 계정)입니다. 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은 자동으로 터널링됩니다. 성공적인 수집 시 knowledgeGraph.imported === true과 함께 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}을 반환합니다. 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이 동일한 엔드포인트를 반복적으로 호출)는 카운트와 함께 단일 항목으로 축소되므로, count: 47과 함께 나타나는 /api/poll은 사용자가 원래 요청한 실행 가능한 "무한 리페치 루프" 신호입니다.

성능 예산: 1 URL에 <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?}	환경 삭제(자격 증명 계단식 삭제) — 확인 필요
sessions	{uuid, username?, credentialId?}	환경이 보유한 계정별 캡처된 로그인 세션, isUsable 및 usableCount 포함
clearSessions	{uuid, username?, credentialId?, confirm?}	세션을 무효화하여 다음 실행 시 실제 로그인 수행 — 범위 없는 삭제는 확인 필요

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

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

페이지네이션

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

{
  "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으로 마이그레이션(작업 기반 도구)

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): 터널 상태(ngrok 세션 터널, 해당 Caddy 인스턴스 및 포트 라우트 잠금)는 프로세스 내에 있으며, 베어러 토큰의 해시로 호출자별로 키가 지정됩니다 — 프로세스 간 조정이 없습니다. 일반 라운드 로빈 로드 밸런서 뒤에서 여러 복제본을 실행하면 한 호출자의 호출이 다른 복제본에 도달하여 전체 세션에 대해 하나가 아닌 도달한 복제본당 터널 하나를 생성할 수 있습니다(추가 ngrok 비용, 복제본 수로 제한, 기존 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를 제공하며, node dist/index.js을 가리키는 프로젝트 범위 서버 debugg-ai-local을 등록합니다 — 새로 빌드된 로컬 코드입니다. 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

---

Apache-2.0 라이선스 © 2025 DebuggAI