ต่อ DormBix ผ่าน MCP & OAuth

DormBix เป็น MCP server แบบ HTTP (JSON-RPC 2.0) — ประกาศเฉพาะ tools (ไม่มี resources/prompts/sampling) method ที่รองรับ: initialize, tools/list, tools/call, ping

Protocol version ที่รองรับ (ใหม่→เก่า):

2025-06-18   2025-03-26   2024-11-05

ต่อจาก Claude Code / Claude Desktop:

claude mcp add --transport http dormbix \
  https://www.dormbix.com/api/mcp \
  --header "Authorization: Bearer <TOKEN>"

เรียกตรงด้วย initialize:

curl -s https://www.dormbix.com/api/mcp \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18"}}'

tools/list คืนเฉพาะ tool ที่ scope ของ token นั้นเรียกได้จริง — เมื่อ DormBix เพิ่ม tool ใหม่ ให้ลบแล้วเพิ่ม connector ใหม่เพื่อดึงรายการล่าสุด

ยิงไม่มี token → /api/mcp ตอบ 401 พร้อม header WWW-Authenticate ที่ชี้ไป resource metadata client อ่าน metadata แล้วเดิน OAuth ต่อ

Discovery endpoint:

GET /.well-known/oauth-protected-resource     (RFC 9728)
GET /.well-known/oauth-authorization-server   (RFC 8414)

กรณีล็อกอิน DormBix คนละเบราว์เซอร์ (เช่นผ่าน LINE) แอป AI จะโชว์รหัส 6 หลัก — เจ้าของหอเปิด /connect บนเครื่องที่ล็อกอินอยู่แล้วกรอกรหัสเพื่ออนุมัติ

ผู้ใช้ติ๊กเลือก scope ตอน consent (ค่าเริ่มต้น = ดูอย่างเดียว) DormBix บังคับ สองชั้น: scope ต้องอยู่ใน token และ role ของบัญชีต้องมีสิทธิ์นั้นจริง — ติ๊ก scope เกินสิทธิ์ role ก็ยังทำไม่ได้

ตารางนี้คือคำศัพท์ scope ทั้งหมด — จะขอสิทธิ์ได้จริงเฉพาะ scope ที่มี tool รองรับแล้ว (write.tenants / write.payment / send.line ยังไม่เปิดให้ AI ทำ — งานแตะเงิน/ข้อความหาผู้เช่า ตั้งใจกันไว้ให้ทำในระบบเอง) ตารางนี้สร้างจาก registry ของจริง รายการสด ๆ ดูที่ /.well-known/agent-card.json หรือ get_capabilities

56 tool แบ่งเป็น ดู · วิเคราะห์ · สั่งงาน — ตารางนี้สร้างจาก registry ของจริง จึงตรงกับที่เซิร์ฟเวอร์ประกาศเสมอ · ที่มีป้าย ต้องยืนยัน ต้องผ่าน plan→execute (ดูหัวข้อถัดไป) รายการที่ token ของคุณเรียกได้จริงดูสด ๆ ที่ get_capabilities

tool ชื่อ plan_* ไม่แก้ข้อมูล — มันคืน พรีวิว: plan_id, จำนวนที่กระทบ, ยอดรวม, คำเตือน และเวลาหมดอายุ ต้องเอาสรุปให้ผู้ใช้ยืนยันก่อน แล้วจึงเรียก execute_plan พร้อม plan_id นั้น

คุณสั่ง → plan_*  →  พรีวิว (plan_id, กระทบกี่รายการ, คำเตือน)
        → ผู้ใช้ยืนยัน → execute_plan(plan_id) → บันทึกจริง + log

• แผน หมดอายุได้ — execute หลังหมดอายุจะถูกปฏิเสธ
• execute ครั้งเดียว: ต่อให้ยิงซ้อนกัน มีแค่คำขอเดียวที่ได้ผล (plan_id เป็น idempotency key ในตัว)
• งานเขียนหนัก (เช่นออกบิลทั้งหอ) เข้าคิวแบบ idempotent — ไม่ทำซ้ำแม้ retry
• ยกเลิกก่อนลงมือได้ด้วย cancel_plan

แยก 2 แบบ: protocol พัง → คืน JSON-RPC error (LLM แก้ไม่ได้) ส่วน tool ทำงานแล้วไม่สำเร็จ (เช่น input ผิด) → คืน result ที่มี isError: true พร้อมข้อความไทย + hint เพื่อให้ LLM ปรับ input แล้วลองใหม่ได้

จำกัดต่อ token ต่อวัน (รีเซ็ตเที่ยงคืน) — เกินแล้วตอบว่าเต็มโควตาพร้อมเวลารีเซ็ต:

• 1 token ผูก 1 หอ ทุกคิวรีตั้ง app.dorm_id — ข้ามไปหออื่นไม่ได้
• ไม่ส่งข้อมูลอ่อนไหวออก: เลขบัตรประชาชน รูปบัตร ที่อยู่ วันเกิด เลขบัญชีธนาคาร
• ทุก action ลง audit log ของหอ (ใคร ผ่าน AI ตัวไหน ทำอะไร เมื่อไหร่)
• Kill switch หลายระดับ: ทั้งแพลตฟอร์ม, รายหอ (opt-in ค่าเริ่มต้นปิด), รายโทเคน
• เพิกถอน token ได้ทุกเมื่อ — งานที่แก้ข้อมูลต้องผ่านการยืนยันเสมอ

หมายเหตุ: ตอนนี้ ยังไม่มี webhooks สาธารณะ สำหรับให้ agent รับ event — การเข้าถึงเป็นแบบ request/response ผ่าน MCP เท่านั้น

นอกจากฝั่งบริหาร DormBix มี API ค้นหาหอพักสาธารณะสำหรับผู้เช่า — อ่านอย่างเดียว ไม่ต้องยืนยันตัวตน เป็นคนละ surface กับ MCP:

GET /openapi.json                    (OpenAPI 3.1 spec)
GET /api/public/ai/search            ค้นหาหอ (จังหวัด/แลนด์มาร์ก/คีย์เวิร์ด)
GET /api/public/ai/availability      เช็กห้องว่างแบบเรียลไทม์

คำถามเชิงเทคนิค: [email protected] · ภาพรวมสำหรับ AI: /ai · คู่มือต่อแอป AI: /docs/ai-connector