Debugg AI

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 เช่นเดียวกับที่โปรเจกต์นี้ ทำกับไบนารี 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 client ของคุณ:

{
  "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 หลายไดเรกทอรีที่ การ build ต้องการตอนนี้ (handlers, tools, types, config) และยังอ้างอิงไดเรกทอรี tunnels/ ที่ไม่มีอยู่อีกต่อไป ดังนั้นการ build ใหม่จึงอาจล้มเหลวก่อนที่เรื่องนั้นจะสำคัญ นั่นคือ ช่องว่างที่มีอยู่ก่อนแล้ว ไม่เกี่ยวข้องกับ Caddy อิมเมจ quinnosha/debugg-ai-mcp ที่ เผยแพร่ในปัจจุบัน มีมาก่อนการพึ่งพา Caddy ไม่ว่าจะกรณีใด — การเรียก URL localhost ไปยัง check_app_in_browser/probe_page/trigger_crawl จะล้มเหลวด้วย CaddyBinaryNotFoundError ภายในอิมเมจนั้นจนกว่าจะ build ใหม่ (แก้ไข 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 จะถูกทันเนลอัตโนมัติผ่าน ngrok

พารามิเตอร์	ชนิด	คำอธิบาย
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 เมื่อการถอยกลับเงียบไปยังผู้ใช้ทดสอบเริ่มต้นจะทำให้การตรวจสอบไม่ถูกต้อง

กำลังตรวจสอบหน้าที่ไม่ต้องเข้าสู่ระบบเลยหรือ? ส่ง 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 พร้อมกับภาพหน้าจอ — URL S3 ที่ลงนามล่วงหน้าสำหรับ HAR ที่จับได้ (ร่องรอยเครือข่ายเต็ม) และ บันทึกคอนโซล (ทุกข้อความ JS console) ใช้เพื่อตรวจจับลูปการดึงข้อมูลซ้ำ ข้อผิดพลาด 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.imported === true ในการรับข้อมูลที่สำเร็จ บล็อก browserSession (URL HAR + บันทึกคอนโซล รูปแบบเดียวกับด้านบน) ก็มีอยู่ในการรวบรวมข้อมูลที่เสร็จสมบูรณ์

probe_page

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

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?}	สภาพแวดล้อมที่สร้างขึ้น (สามารถเริ่มข้อมูลประจำตัวได้)
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 จัดการเซสชันที่รับรองความถูกต้องแบบอุ่นที่แบ็กเอนด์นำกลับมาใช้ใหม่เพื่อข้ามการเข้าสู่ระบบ (ดู การนำเซสชันกลับมาใช้ใหม่) เนื้อหาเซสชันจะไม่ถูกส่งคืน — คุกกี้เซสชันคือข้อมูลประจำตัวแบบ bearer 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	ถูกลบ — เป็นแบบ headless เสมอ

การดำเนินการ delete ต้องยืนยันแล้ว (พรอมต์การสอบถาม หรือ 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	ถูกลบ — การปิดแบ็กเอนด์เป็นอัตโนมัติ

การเปลี่ยนแปลงรูปแบบการตอบสนอง: ฟิลด์ 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	ไม่	แทนที่ slug เวิร์กโฟลว์ App Evaluation ที่ check_app_in_browser ส่งไป ค่าเริ่มต้นคือ flow/e2es/app-eval การส่งจะยึดกับ slug นี้เพื่อให้การเปลี่ยนชื่อเทมเพลตแบ็กเอนด์ไม่ทำให้เสียหาย
LOG_LEVEL	ไม่	error / warn / info (ค่าเริ่มต้น) / debug
POSTHOG_API_KEY	ไม่	แทนที่คีย์โปรเจกต์เทเลเมทรีที่ฝังไว้ (เช่น fork ส่วนตัว)
DEBUGGAI_TELEMETRY_DISABLED	ไม่	ตั้งเป็น 1 / true / yes / on เพื่อปิดเทเลเมทรีทั้งหมด

DEBUGGAI_API_KEY=your_api_key

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

โดยค่าเริ่มต้น เซิร์ฟเวอร์พูด stdio (npx ในเครื่อง) สามารถรันเป็น 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 ชี้ไปที่เมตาดาต้า RFC 9728 และไคลเอนต์รันโฟลว์ OAuth กับเซิร์ฟเวอร์อนุญาตที่โฆษณา bearer เป็นแบบขอบเขตคำขอ — api.debugg.ai ตรวจสอบ

ปลายทาง	วัตถุประสงค์
POST /mcp	MCP Streamable HTTP (ป้องกันด้วย bearer)
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 ไม่จำเป็นต้องใช้สิ่งเหล่านี้

การปรับใช้หลายเรพลิกา (go/no-go ก่อนเปิดตัว): สถานะอุโมงค์ (เซสชันอุโมงค์ ngrok, อินสแตนซ์ Caddy และล็อกพอร์ต-รูท) อยู่ในกระบวนการ คีย์ต่อผู้เรียกโดยแฮชของ โทเค็น bearer — ไม่มีการประสานงานข้ามกระบวนการ การรันหลายเรพลิกาหลังโหลดบาลานเซอร์ แบบ round-robin ธรรมดาหมายความว่าการเรียกของผู้เรียกหนึ่งรายอาจไปยังเรพลิกาต่างกันและสร้างอุโมงค์ ต่อเรพลิกาที่พวกเขาเข้าถึง แทนที่จะเป็นหนึ่งสำหรับทั้งเซสชัน (ค่าใช้จ่าย ngrok เพิ่มเติม จำกัดด้วย จำนวนเรพลิกา รักษาตัวเองผ่านการปิดอัตโนมัติเมื่อไม่ได้ใช้งาน 55 นาที — ไม่เคยเป็นบั๊กความถูกต้อง ข้ามเซสชัน เนื่องจากการเรียกเครื่องมือใด ๆ อยู่บนเรพลิกาเดียวตลอดระยะเวลา) เพื่อให้ได้ พฤติกรรม "หนึ่งอุโมงค์ต่อเซสชัน" ที่ตั้งใจไว้บนการปรับใช้ HTTP หลายเรพลิกา กำหนดค่า การกำหนดเส้นทางแบบยึดเซสชัน ที่โหลดบาลานเซอร์ (sticky/consistent-hash คีย์บนข้อมูลประจำตัวเดียวกัน ที่ getSessionKey() อนุมาน — ในทางปฏิบัติ โทเค็น bearer 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 เทียบกับ 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 ครั้งถัดไปรับการเปลี่ยนแปลงของคุณ

ลิงก์

Dashboard · Docs · Issues · Discord

---

สัญญาอนุญาต Apache-2.0 © 2025 DebuggAI