Debugg AI

ทางการ

เปิดให้เอเจนต์สร้างโค้ดของคุณสามารถสร้างและรันการทดสอบแบบ end-to-end ที่ไม่ต้องกำหนดค่าใดๆ กับการเปลี่ยนแปลงโค้ดใหม่ในเบราว์เซอร์ระยะไกลผ่านแพลตฟอร์มทดสอบของ Debugg AI

GitHub

คุณทำอะไรได้บ้างด้วย Debugg AI MCP?

รันการทดสอบ AI บนเบราว์เซอร์ — ขอให้ทดสอบ URL ใดๆ หรือแอป localhost ด้วยคำสั่งภาษาธรรมชาติผ่าน check_app_in_browser ซึ่งจะคืนผลผ่าน/ไม่ผ่านพร้อมภาพหน้าจอ
ตรวจสอบหลายเพจอย่างรวดเร็ว — ใช้ probe_page เพื่อตรวจสอบ URL 1-20 รายการเป็นชุดสำหรับข้อผิดพลาดคอนโซล ปัญหาเครือข่าย และสถานะการเรนเดอร์โดยไม่มีค่าใช้จ่าย LLM
จัดการสภาพแวดล้อมการทดสอบ — สร้าง อัปเดต หรือแสดงรายการสภาพแวดล้อมพร้อมข้อมูลรับรองและโฮสต์ SSO ที่ได้รับอนุญาตโดยใช้เครื่องมือ environment
เริ่มการรวบรวมข้อมูลเว็บไซต์ — เรียกใช้ trigger_crawl เพื่อเติมกราฟความรู้ของโปรเจกต์ด้วยการรวบรวมข้อมูลผ่านเอเจนต์เบราว์เซอร์ฝั่งเซิร์ฟเวอร์
รันและติดตามชุดการทดสอบ — สร้างชุด เริ่มการรันแบบอะซิงโครนัส และดึงผลลัพธ์รายการทดสอบผ่านการดำเนินการ test_suite
ตรวจสอบอาร์ติแฟกต์การทำงาน — ดึงรายละเอียดการรันเต็มรูปแบบ ร่องรอยเครือข่าย HAR และบันทึกคอนโซลผ่าน executions เพื่อดีบักปัญหาที่เกิดขึ้นระหว่างรันไทม์

เอกสาร

Debugg AI — MCP Server

การทดสอบเบราว์เซอร์ที่ขับเคลื่อนด้วย AI ผ่าน Model Context Protocol ชี้ไปที่ URL ใดก็ได้ (หรือ localhost) และอธิบายสิ่งที่ต้องการทดสอบ — เอเจนต์ AI จะเรียกดูแอปของคุณและส่งคืนผลผ่าน/ไม่ผ่านพร้อมภาพหน้าจอ

การตั้งค่า

ต้องใช้ Node.js 20.20.0 หรือใหม่กว่า (ข้อกำหนดที่ส่งต่อมาจาก posthog-node@^5.26.0)

การทดสอบ URL http://localhost:... ต้องใช้ไบนารี caddy — check_app_in_browser, probe_page, และ trigger_crawl ทันเนลเป้าหมาย localhost ผ่านพร็อกซีรีเวิร์สของ Caddy ในเครื่อง สิ่งนี้ติดตั้งโดยอัตโนมัติ: การพึ่งพา npm ของ @radically-straightforward/caddy จะดาวน์โหลด Caddy รุ่นที่ระบุสำหรับแพลตฟอร์มของคุณระหว่าง npm install/npx — ไม่ต้องติดตั้งอะไรด้วยตัวเองใน กรณีปกติ ตอนนี้มันเป็นไบนารี เพียงตัวเดียว ที่แพ็คเกจนี้ดาวน์โหลด; ไคลเอ็นต์ทันเนลเองเป็น TypeScript บริสุทธิ์ — มันแทนที่แพ็คเกจ ngrok ซึ่งดึงเอเจนต์ ngrok หากการดาวน์โหลดนั้นไม่เคยทำงาน (npm install --ignore-scripts, การติดตั้งแบบออฟไลน์/แยกเครือข่าย) ให้ชี้ CADDY_BIN ไปที่ การติดตั้งของคุณเอง (brew install caddy / apt install caddy / ดู caddyserver.com/docs/install) — การขาดมันจะแสดงเป็น ข้อผิดพลาดที่ชัดเจนในการเรียก URL localhost ครั้งแรก ไม่ใช่การค้างเงียบ ๆ การเรียก URL สาธารณะ ทุก เครื่องมือที่ไม่ใช่เบราว์เซอร์ และ test_suite {action:"run"} (ซึ่งใช้ทันเนลเฉพาะของตัวเองและ บายพาส Caddy ทั้งหมด) ไม่ต้องการมันไม่ว่ากรณีใด

รับคีย์ 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

ขั้นตอน npm install ของ Dockerfile จะดึง caddy ด้วยวิธีอัตโนมัติเดียวกันกับการติดตั้งในเครื่อง ในหลักการ — แต่ ณ เวลาที่เขียนนี้ Dockerfile ไม่ได้ COPY หลายไดเรกทอรีที่ บิลด์ตอนนี้ต้องการ (handlers, tools, types, config) และยังอ้างอิงไดเรกทอรี tunnels/ ที่ไม่มีอยู่อีกต่อไป ดังนั้นบิลด์ใหม่จึงน่าจะล้มเหลวก่อนที่เรื่องนั้นจะสำคัญ นั่นเป็น ช่องว่างที่มีอยู่ก่อนแล้ว ไม่เกี่ยวข้องกับ Caddy อิมเมจ quinnosha/debugg-ai-mcp ที่เผยแพร่ในปัจจุบัน มีมาก่อนการพึ่งพา Caddy อยู่แล้ว — การเรียก URL localhost ไปที่ check_app_in_browser/probe_page/trigger_crawl จะล้มเหลวด้วย CaddyBinaryNotFoundError ภายในอิมเมจนั้นจนกว่าจะถูกบิลด์ใหม่ (แก้ไข Dockerfile) และเผยแพร่ใหม่ หรือ CADDY_BIN ชี้ไปที่ ตัวที่ฝังไว้แยกต่างหาก การเรียก URL สาธารณะ เครื่องมือที่ไม่ใช่เบราว์เซอร์ และ test_suite {action:"run"} ไม่ได้รับผลกระทบไม่ว่ากรณีใด

เครื่องมือ

เซิร์ฟเวอร์เปิดเผยเครื่องมือ 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 กับแอปของคุณ เอเจนต์จะนำทาง โต้ตอบ และรายงานกลับพร้อมภาพหน้าจอ URL localhost จะถูกทันเนลอัตโนมัติผ่านเซิร์ฟเวอร์ทันเนล debugg

พารามิเตอร์	ชนิด	คำอธิบาย
`description`	string จำเป็น	สิ่งที่ต้องการทดสอบ (ภาษาธรรมชาติ)
`url`	string จำเป็น	URL เป้าหมาย — `http://localhost:3000` ถูกทันเนลอัตโนมัติ
`environmentId`	string	UUID ของสภาพแวดล้อมเฉพาะ
`credentialId`	string	UUID ของข้อมูลประจำตัวเฉพาะ
`credentialRole`	string	เลือกข้อมูลประจำตัวตามบทบาท (เช่น `admin`, `guest`)
`username`	string	ชื่อผู้ใช้สำหรับเข้าสู่ระบบ (ชั่วคราว — ไม่ถูกบันทึก)
`password`	string	รหัสผ่านสำหรับเข้าสู่ระบบ (ชั่วคราว — ไม่ถูกบันทึก)
`loginCredentials`	array	บัญชีสำหรับการเข้าสู่ระบบที่เอเจนต์พบ ระหว่าง งาน — `[{username, password, label?}]`
`useEnvironmentCredentials`	boolean	ค่าเริ่มต้น `true` `false` ห้ามการกรอกอัตโนมัติของข้อมูลประจำตัวที่เก็บไว้ของสภาพแวดล้อม; หากไม่มีบัญชีที่ระบุหมายความว่า อย่าเข้าสู่ระบบเลย
`freshSession`	boolean	ค่าเริ่มต้น `false` `true` บังคับให้เข้าสู่ระบบจริงแทนการใช้เซสชันอุ่นที่เก็บไว้สำหรับบัญชีนั้น
`auth`	object	เงื่อนไขก่อนการตรวจสอบสิทธิ์ — `{precondition, entryUrl, deepUrl, environmentId, username, password}`
`repoName`	string	แทนที่ชื่อ repo 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 ของสภาพแวดล้อม (ดู environment)

กำลังตรวจสอบหน้าที่ไม่ต้องเข้าสู่ระบบเลย? ส่ง 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 },
  { "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 เป็นจริงเฉพาะเมื่อพิมพ์และส่งข้อมูลประจำตัวจริง ๆ; reason บอกสิ่งที่เกิดขึ้น (เช่น offscope_host, restored_session) และ detail เมื่อมี คือคำอธิบายที่มนุษย์อ่านได้ — สำหรับการปฏิเสธ offscope_host มันระบุโฮสต์และวิธีอนุญาต credentialWarning ปรากฏเฉพาะเมื่อคุณระบุบัญชีและค่าเริ่มต้นของสภาพแวดล้อมสำหรับบัญชี อื่น ถูกส่งจริง — ไม่เคยสำหรับการเข้าสู่ระบบที่ถูกปฏิเสธหรือข้าม loginError ปรากฏเมื่อบัญชีที่ระบุไม่สามารถแก้ไขได้และการรันปฏิเสธที่จะแทนที่ด้วยบัญชีอื่น

ทุกการรันที่สำเร็จส่งคืนบล็อก browserSession พร้อมภาพหน้าจอ — URL S3 ที่ลงนามล่วงหน้าสำหรับ HAR ที่จับได้ (ร่องรอยเครือข่ายเต็ม) และ บันทึกคอนโซล (ทุกข้อความคอนโซล JS) ใช้เพื่อตรวจจับลูป refetch ข้อผิดพลาด hydration และปัญหารันไทม์อื่น ๆ ที่ผ่านการตรวจสอบชนิดและเทสต์หน่วย:

"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.skipped === false ในการนำเข้าที่สำเร็จ crawlSummary และ knowledgeGraph มีเฉพาะคีย์ที่โหนดรวบรวม/นำเข้าของแบ็กเอนด์รายงาน — จำนวนที่หายไปจะไม่มี ไม่ใช่ 0 ที่เติมค่า บล็อก browserSession (URL HAR + บันทึกคอนโซล รูปแบบเดียวกับด้านบน) ก็มีอยู่ในการรวบรวมที่เสร็จสมบูรณ์

`probe_page`

การตรวจสอบหน้าแบบไม่ใช้ LLM ที่มีน้ำหนักเบาเป็นชุด ส่ง 1-20 URL; แต่ละรายการนำทาง รอให้เนื้อหาคงที่ (DOM เงียบ จำกัดเวลา — ไม่เคยรอความเงียบของเครือข่าย ซึ่งแอปสดไม่มีวันถึง) และส่งคืนสถานะที่เรนเดอร์ — ภาพหน้าจอ + เมตาดาต้าหน้า + ข้อผิดพลาดคอนโซลที่มีโครงสร้าง + สรุปเครือข่าย ไม่มีลูปเอเจนต์ ไม่มีค่าใช้จ่าย LLM ไม่มีการยืนยันสถานการณ์ ใช้สำหรับ "ฉันเพิ่งทำ /settings พังหรือเปล่า?", การสโมคหลายเส้นทางหลัง refactor, การกวาด CI ต่อ PR และการตรวจสอบว่าเว็บขึ้นหรือไม่ที่ลูปเอเจนต์ 60-150 วินาทีของ check_app_in_browser มากเกินไป

พารามิเตอร์	ชนิด	คำอธิบาย
`targets`	array จำเป็น	1-20 รายการ: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	string จำเป็น	URL สาธารณะหรือ localhost (ทันเนลอัตโนมัติ)
`targets[].waitForLoadState`	enum	`'domcontentloaded'` (ค่าเริ่มต้น + การรอเนื้อหาคงที่แบบจำกัด) / `'load'` (ยังบล็อก embeds ของบุคคลที่สาม) / `'networkidle'` (ยอมรับ ไม่เคยออก — เครือข่ายของเว็บสดไม่เคยว่าง)
`targets[].waitForSelector`	string	ตัวเลือก CSS selector ที่จะรอหลังการนำทาง
`targets[].timeoutMs`	number	หมดเวลาต่อ URL, 1000-30000 (ค่าเริ่มต้น 10000)
`includeHtml`	boolean	ส่งคืน HTML ดิบในแต่ละผลลัพธ์ (ค่าเริ่มต้น false)
`captureScreenshots`	boolean	ส่งคืน PNG หนึ่งรายการต่อเป้าหมาย (ค่าเริ่มต้น true)

ทุกเป้าหมายในชุดใช้ทันเนลเซสชันเดียวร่วมกัน แต่เฉพาะชุดพอร์ตเดียวกัน (หรือสาธารณะทั้งหมด) ที่ใช้การดำเนินการแบ็กเอนด์ เดียว ร่วมกัน — 5 URL บนพอร์ตเดียวในการเรียกเดียวเร็วกว่าการเรียก URL เดียว 5 รายการแบบขนานมาก ชุดที่ผสมพอร์ต local หลายพอร์ตจะแยกเป็นการดำเนินการแบ็กเอนด์แบบเรียงลำดับหนึ่งรายการต่อกลุ่มพอร์ต (ยังเป็นการเรียกเดียว ยังเป็น results[] ที่รวมกันเดียวในลำดับเดิมของคุณ แต่มีการไปกลับแบ็กเอนด์ N ครั้งแทนหนึ่งครั้ง — ช้ากว่า ไม่ถูกปฏิเสธ) ฟิลด์ error ต่อ URL รักษาความยืดหยุ่นของชุด: เป้าหมายที่ล้มเหลวหนึ่งรายการไม่ทำให้รายการอื่นล้มเหลว networkSummary คีย์การรวมกลุ่มคือ origin + pathname — ลูปการดึงข้อมูลซ้ำ (?n=0..4 เรียก endpoint เดิมซ้ำๆ) จะถูกยุบรวมเป็นรายการเดียวพร้อมจำนวนครั้ง ดังนั้น /api/poll ที่ปรากฏพร้อมกับ count: 47 จึงเป็นสัญญาณ "ลูปการดึงข้อมูลซ้ำไม่รู้จบ" ที่ผู้ใช้ต้องการในตอนแรก

งบประมาณด้านประสิทธิภาพ: <10 วินาทีสำหรับ 1 URL, <25 วินาทีสำหรับ 20 รายการ localhost ที่พอร์ตตายจะคืนค่า LocalServerUnreachable ใน <2 วินาทีโดยไม่เผาผลาญการทำงานของ workflow

`project`

การดำเนินการ	พารามิเตอร์	ผลลัพธ์
`get`	`{uuid}`	รายละเอียดโปรเจกต์ที่คัดสรร
`list`	`{q?, page?, pageSize?}`	สรุปแบบแบ่งหน้า
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	โปรเจกต์ที่สร้างแล้ว

ทีมและ repo จะถูกระบุด้วย 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 repo เมื่อละเว้น ความล้มเหลวต่อข้อมูลรับรองจะแสดงใน credentialWarnings[] โดยไม่บล็อกการดำเนินการสภาพแวดล้อม

authorizedCredentialHosts แสดงรายการโฮสต์ที่การรันอาจเข้าสู่ข้อมูลรับรองของสภาพแวดล้อมนี้นอกเหนือจากโฮสต์ของแอปเอง — สำหรับ SSO ข้ามโดเมน ให้เพิ่มโฮสต์ IdP ที่นี่ (เช่น ["auth.example.com"]) ระบุเฉพาะชื่อโฮสต์เท่านั้น: ไม่มี scheme, path, port หรือ wildcard (ซับโดเมนของโฮสต์แอปอยู่ในขอบเขตอยู่แล้ว) เมื่อ update จะแทนที่รายการ; [] จะล้างรายการ get/list จะคืนค่ารายการเมื่อเซิร์ฟเวอร์รองรับ การตอบสนองจะสะท้อนรายการที่บันทึกไว้; หากเซิร์ฟเวอร์ไม่ได้บันทึกไว้ (เซิร์ฟเวอร์รุ่นเก่าจะละเว้นฟิลด์นี้) ผลลัพธ์จะนำ authorizedCredentialHostsWarning: {requested, returned} แทนความสำเร็จแบบเงียบ

sessions / clearSessions จัดการเซสชันที่รับรองความถูกต้องแบบอุ่นที่ backend นำกลับมาใช้เพื่อข้ามการเข้าสู่ระบบ (ดู การนำเซสชันกลับมาใช้) เนื้อหาเซสชันจะไม่ถูกส่งคืน — คุกกี้เซสชันคือข้อมูลรับรองแบบ bearer clearSessions ทำเครื่องหมายเซสชันว่าไม่ถูกต้องแทนที่จะลบแถว ดังนั้นการนำกลับมาใช้จะหยุดทันทีในขณะที่ประวัติการบันทึกยังอ่านได้

`test_suite`

การดำเนินการ	พารามิเตอร์	ผลลัพธ์
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	ชุดทดสอบแบบแบ่งหน้าพร้อมสถานะ + อัตราผ่าน
`create`	`{name, description, projectUuid\|projectName}`	ชุดทดสอบที่สร้างแล้ว
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	เรียกใช้การทดสอบทั้งหมดแบบ async
`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) + artifacts สกรีนช็อต/gif
`list`	`{status?, projectUuid?, page?, pageSize?}`	สรุปแบบแบ่งหน้า

404 จาก backend จะแสดงเป็น 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 เพื่อให้ไคลเอนต์สามารถเรียกดูและ @-mention เป็นบริบทได้:

URI	สิ่งที่ให้
`debugg-ai://projects`	โปรเจกต์ทั้งหมด (หน้าแรก)
`debugg-ai://environments`	สภาพแวดล้อมสำหรับโปรเจกต์ที่ตรวจจับอัตโนมัติ
`debugg-ai://executions`	การทำงานล่าสุด (หน้าแรก)
`debugg-ai://project/{uuid}`	โปรเจกต์เดียว รายละเอียดเต็ม
`debugg-ai://environment/{uuid}`	สภาพแวดล้อมเดียว (ข้อมูลรับรองแบบอินไลน์ รหัสผ่านถูกปกปิด)
`debugg-ai://execution/{uuid}`	การทำงานเดียว รายละเอียดโหนดเต็ม + ลิงก์ artifact

การอ่านจะส่งไปยังตัวจัดการเดียวกันกับเครื่องมือ project / environment / executions ดังนั้นข้อมูลและการรับรองความถูกต้องจึงเหมือนกัน ทรัพยากรเป็นแบบเพิ่มเติม — ไคลเอนต์ที่ไม่รองรับทรัพยากรยังคงใช้เครื่องมือได้

หลักประกันด้านความปลอดภัย

รหัสผ่านเป็นแบบเขียนอย่างเดียว ไม่ปรากฏในเนื้อหาการตอบสนองใดๆ จากเครื่องมือใดๆ
URL อุโมงค์ (*.tunnel.debugg.ai และ *.ngrok.debugg.ai ที่เลิกใช้แล้วซึ่งการรันในอดีตยังอ้างอิง) จะถูกตัดออกจากการตอบสนองของ browser-agent ทั้งหมด รวมถึงข้อความที่ agent เขียน
404 จาก backend แสดงเป็น isError: true พร้อม {error: 'NotFound', ...} ไม่ใช่เป็น exception ที่ถูกโยน
DEBUGGAI_API_KEY ที่หายไปแสดงเป็นข้อผิดพลาดเครื่องมือแบบมีโครงสร้างในการเรียกครั้งแรก — เซิร์ฟเวอร์ยังคงลงทะเบียนและแสดงรายการเครื่องมือตามปกติ

การย้ายไปยัง v6.0.0 (คำตัดสินจาก backend ไม่มีข้อความที่ MCP เขียน)

คำตัดสินการรันคือ pass | fail | error โดย reason ของ backend จะถูกถ่ายทอดตามต้นฉบับ การรันที่ไม่เคยพยายามทดสอบจะอ่านว่า 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`	ถูกตัดออก — เป็นแบบ headless เสมอ

การดำเนินการ delete ตอนนี้ต้องยืนยัน (prompt การสอบถาม หรือ confirm: true) ไคลเอนต์จะรับพื้นผิวใหม่เมื่อรีสตาร์ท MCP

การย้ายจาก v1.x (การเปลี่ยนแปลงที่ทำลายใน v2.0.0)

v2 ยุบพื้นผิว 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: [...]})` seed หรือ `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`	ถูกตัดออก — การปิด backend เป็นอัตโนมัติ

การเปลี่ยนแปลงรูปร่างการตอบสนอง: ฟิลด์ count เปล่าบนการตอบสนองรายการหายไป — ใช้ pageInfo.totalCount

การกำหนดค่า

ตัวแปรสภาพแวดล้อม	จำเป็น	วัตถุประสงค์
`DEBUGGAI_API_KEY`	ใช่	คีย์ API ของ backend. ชื่ออื่น: `DEBUGGAI_API_TOKEN`, `DEBUGGAI_JWT_TOKEN`
`DEBUGGAI_API_URL`	ไม่	URL พื้นฐานของ backend. ค่าเริ่มต้นคือ `https://api.debugg.ai`
`DEBUGGAI_TOKEN_TYPE`	ไม่	`token` (ค่าเริ่มต้น) หรือ `bearer`
`DEBUGGAI_EVAL_TEMPLATE`	ไม่	แทนที่ slug ของ workflow การประเมินแอปที่ `check_app_in_browser` ส่งไป ค่าเริ่มต้นคือ `flow/e2es/app-eval` การส่งจะยึดกับ slug นี้เพื่อให้การเปลี่ยนชื่อเทมเพลต backend ไม่ทำให้เสียหาย
`LOG_LEVEL`	ไม่	`error` / `warn` / `info` (ค่าเริ่มต้น) / `debug`
`POSTHOG_API_KEY`	ไม่	แทนที่คีย์โปรเจกต์ telemetry ในตัว (เช่น fork ส่วนตัว)
`DEBUGGAI_TELEMETRY_DISABLED`	ไม่	ตั้งเป็น `1` / `true` / `yes` / `on` เพื่อปิด telemetry ทั้งหมด

DEBUGGAI_API_KEY=your_api_key

การขนส่ง Remote / HTTP (ไม่บังคับ)

โดยค่าเริ่มต้น เซิร์ฟเวอร์ใช้ stdio (npx ในเครื่อง) สามารถรันเป็น remote MCP แบบโฮสต์หลายผู้ใช้ผ่าน Streamable HTTP แบบไม่เก็บสถานะ + OAuth:

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

เป็น OAuth Resource Server: ทุก POST /mcp ต้องมี Authorization: Bearer <token>; โทเค็นที่หายไป/ไม่ถูกต้องจะได้รับ 401 พร้อม WWW-Authenticate ที่ชี้ไปยัง metadata RFC 9728 และไคลเอนต์จะรันโฟลว์ OAuth กับเซิร์ฟเวอร์อนุญาตที่โฆษณา bearer เป็นแบบขอบเขตคำขอ — api.debugg.ai ตรวจสอบความถูกต้อง

Endpoint	วัตถุประสงค์
`POST /mcp`	MCP Streamable HTTP (ป้องกันด้วย bearer)
`GET /.well-known/oauth-protected-resource`	metadata RFC 9728 (การค้นพบเซิร์ฟเวอร์อนุญาต)
`GET /health`	การตรวจสอบสุขภาพ load-balancer / 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 ไม่จำเป็นต้องใช้สิ่งเหล่านี้

การปรับใช้หลาย replica (go/no-go ก่อนเปิดตัว): สถานะอุโมงค์ (เซสชันอุโมงค์ อินสแตนซ์ Caddy และล็อกพอร์ต-route) อยู่ในกระบวนการ คีย์ต่อผู้เรียกโดยแฮชของ bearer token — ไม่มีการประสานงานข้ามกระบวนการ การรันหลาย replica หลัง load balancer แบบ round-robin ธรรมดาหมายความว่าการเรียกของผู้เรียกหนึ่งรายอาจไปยัง replica ต่างกันและสร้างอุโมงค์ หนึ่งรายต่อ replica ที่พวกเขาเข้าถึง แทนที่จะเป็นหนึ่งรายต่อเซสชันทั้งหมด (จำกัดด้วยจำนวน replica, รักษาตัวเองผ่านการปิดอัตโนมัติเมื่อไม่ใช้งาน 55 นาทีที่มีอยู่ — ไม่ใช่บั๊กความถูกต้องข้ามเซสชัน เนื่องจากการเรียกเครื่องมือใดๆ อยู่บน replica เดียวตลอดระยะเวลา) เพื่อให้ได้พฤติกรรม "หนึ่งอุโมงค์ต่อเซสชัน" ตามที่ตั้งใจบนการปรับใช้ HTTP หลาย replica ให้กำหนดค่า การกำหนดเส้นทางแบบ session-affine ที่ load balancer (sticky/consistent-hash คีย์บนข้อมูลประจำตัวเดียวกันที่ getSessionKey() ใช้ — ในทางปฏิบัติคือ bearer token Authorization ของผู้เรียก) ดู docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 สำหรับเหตุผลเต็มและเส้นทางการลดระดับอย่างตรงไปตรงมาหากไม่ได้กำหนดค่านี้

Telemetry

MCP server มาพร้อมกับระบบ telemetry ที่เปิดใช้งานตามค่าเริ่มต้น — คีย์ PostHog แบบ write-only ที่ฝังไว้ (phc_*) เพื่อให้ทีมสามารถสังเกตอัตราการ hit ของ cache, ความถี่ในการ poll, ความน่าเชื่อถือของ tunnel และเมตริกการดำเนินงานอื่น ๆ ทั่วทั้งฐานการติดตั้ง เหตุการณ์ที่ถูกบันทึก:

เหตุการณ์	เมื่อใด
`tool.executed` / `tool.failed`	ทุกครั้งที่มีการเรียกใช้ tool
`workflow.executed`	ทุกครั้งที่มีการทำงานของ browser-agent (มาพร้อมกับ `pollCount`, `durationMs`, `finalIntervalMs`)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	ทุกเหตุการณ์ในวงจรชีวิตของ tunnel
`template.lookup` / `project.lookup`	cache hit/miss พร้อมกับ `durationMs` เมื่อมีการเรียกแบบ cold-call

จุดยืนด้านความเป็นส่วนตัว:

distinct ID คือ SHA-256(api_key).slice(0, 16) — ไม่ใช่คีย์ดิบ และไม่มี PII
คีย์ phc_* เป็นแบบ write-only ตามหลักการของ PostHog ปลอดภัยที่จะฝังในซอร์สโค้ด
ตั้งค่า DEBUGGAI_TELEMETRY_DISABLED=1 เพื่อเลือกไม่ใช้ทั้งหมด (จะแปลงเป็น provider ที่ไม่ทำอะไรเลย ไม่มีเหตุการณ์ใดออกจากกระบวนการ)

โหมดที่ใช้งานอยู่จะถูกบันทึกเมื่อเริ่มระบบ:

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

ชุดทดสอบ eval จะสร้าง MCP server ที่ build แล้วเป็น subprocess ทดสอบทุก tool กับ backend จริง และเขียน artifacts ตามแต่ละ flow ไปยัง scripts/evals/artifacts/<timestamp>/ ดู scripts/evals/flows/ สำหรับสถานการณ์แต่ละรายการ

การลงทะเบียน MCP: `debugg-ai-local` เทียบกับ `debugg-ai`

Repo นี้มาพร้อมกับ .mcp.json ที่ลงทะเบียน server แบบ project-scoped ชื่อ debugg-ai-local ชี้ไปที่ node dist/index.js — โค้ดท้องถิ่นที่ build ใหม่ มันจะทำงานเฉพาะเมื่อ working directory ของ Claude Code อยู่ใน repo นี้

โปรเจกต์อื่น ๆ ของคุณควรใช้การลงทะเบียนแบบ user-scoped 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 (ซึ่งแค่ build ใหม่) เพื่อให้การเรียก debugg-ai-local ครั้งถัดไปรับการเปลี่ยนแปลงของคุณ

ลิงก์

Dashboard · Docs · Issues · Discord