GitLab

สรุปงาน (Summary)

พัฒนาและขยาย MCP Tool Catalogue ใน packages/qa-mcp และเชื่อมต่อ Ports ปลายทางใน apps/web/src/server/mcp-ports.ts ให้รองรับ 3 เครื่องมือหลักของ QA Brain: happyqa_brain_query, happyqa_brain_get_entry, และ happyqa_brain_record_gotcha พร้อมรองรับ Typed Evidence Verification (RUN_RESULT), Duplicate Advisory Warnings, Authorship Metadata (authorType, agentName), และ includeDeprecated

อ้างอิงข้อกำหนดสถาปัตยกรรม: RFC v4.1 (Section 5.1–5.4)
ลำดับการทำงาน (Dependency): ขึ้นต่อกับ T1, T2, T3, T4

---

ขอบเขตและงานที่ต้องทำ (Scope of Work)

1. ประกาศและลงทะเบียน Tools ใน packages/qa-mcp

• เพิ่มคำจำกัดความเครื่องมือใน Catalogue:
  1. happyqa_brain_query: ค้นหาบทเรียนสถานะ VERIFIED ตามขอบเขตสิทธิ์ (รองรับ includeDraft และ includeDeprecated: boolean)
  2. happyqa_brain_get_entry: ดึงข้อมูลบทเรียนรายตัวฉบับเต็ม พร้อมประวัติ Revision และ Authorship
  3. happyqa_brain_record_gotcha: จดบทเรียนใหม่เป็น DRAFT พร้อมระบุ Authorship (authorType, agentName), ตรวจ Typed Evidence และรับ advisoryWarnings
• กำหนด JSON Schema อย่างเข้มงวด (Closed Schemas, additionalProperties: false) สำหรับ Input และ Output ของทุกเครื่องมือ
• อัปเดต Checksum / Catalogue Hash ใหม่ให้สอดคล้องกับมาตรฐานของแพ็กเกจ

2. พัฒนา Ports ใน apps/web/src/server/mcp-ports.ts

เชื่อมโยงคำสั่งจาก MCP Client เข้าสู่ Domain Services:

• Authentication & Authorization:
  • รองรับทั้ง Delegated User Token และ Machine Key (qa.brain.read, qa.brain.write)
  • ตรวจสอบสิทธิ์ใน Workspace และ Project
• brain.query:
  • กรองขอบเขตโปรเจกต์ (Pre-query scope filter)
  • ค้นหาผ่าน title, what, tags, และ evidenceRef
  • รองรับ includeDeprecated สำหรับเรียกดู Gotcha ที่ถูกยกเลิกแล้ว
• brain.get_entry:
  • กรองสิทธิ์ หากเป็น DRAFT โดยไม่มีสิทธิ์ Editor ตอบกลับ NOT_FOUND
• brain.record_gotcha:
  • Typed Evidence Validation: หาก evidenceType === 'RUN_RESULT' ให้ตรวจว่า evidenceRef (Run ID) มีอยู่จริงในตาราง QaTestRun ของโปรเจกต์นั้นหรือไม่ หากไม่ใช่ ให้ปฏิเสธด้วย VALIDATION_FAILED
  • Duplicate Advisory Scan: ค้นหา Gotcha เดิมที่อาจซ้ำซ้อนในขอบเขตสิทธิ์ของผู้เรียก และแนบคำเตือนใน advisoryWarnings: string[] (ห้ามตรวจหรือคายข้อมูลจากโปรเจกต์อื่น)
  • นำข้อมูลผ่าน Pre-Ingress Sanitizer $\rightarrow$ คำนวณ Fingerprint จาก Sanitized Payload $\rightarrow$ ตรวจ Idempotency Engine $\rightarrow$ บันทึกลงตาราง QaBrainGotcha (สถานะ DRAFT) $\rightarrow$ บันทึก appendAudit (operation: "brain.record_gotcha")

---

เกณฑ์การตรวจรับ (Acceptance Criteria)

• เครื่องมือใหม่ทั้ง 3 ตัวปรากฏในรายชื่อ Tools ของ MCP Client พร้อม Closed Schema ถูกต้อง
• บันทึก Gotcha ด้วย evidenceType = RUN_RESULT ที่เป็นของโปรเจกต์อื่น ถูกปฏิเสธด้วย VALIDATION_FAILED
• Duplicate Advisory ทำงานและส่งคำเตือนเมื่อจดเรื่องซ้ำในโปรเจกต์ตนเอง แต่ไม่แสดงข้อมูลจากโปรเจกต์อื่น
• เมื่อส่ง includeDeprecated = true ใน happyqa_brain_query ผลลัพธ์แสดงบทเรียนที่ถูก deprecate
• ทุกครั้งที่จด Gotcha สำเร็จ มีการบันทึก Audit Event ลงใน qa_audit_event