mcp-broker

mcp-broker

ระบบ broker สำหรับสื่อสารระหว่าง agent หลายตัว ทำงานผ่าน MCP server ช่วยให้ AI agent หลายตัว (เช่น Claude หลาย instance) ค้นหากัน ส่งข้อความ และประสานงานผ่าน channel ร่วมกัน — ข้อมูลทั้งหมดเก็บใน SQLite

สารบัญ

• ทำไมต้อง mcp-broker? — เทียบกับ Agent/Subagent/Teams ของ Claude Code
• หลักการทำงาน — ภาพรวมสถาปัตยกรรม
• สิ่งที่ต้องติดตั้งก่อน — Bun, Claude Code
• วิธีติดตั้ง — ติดตั้งแบบ plugin หรือ manual
• วิธีใช้งาน — ลงทะเบียน, แชท, channel, broadcast, coordinator
• ตัวอย่างการใช้งาน — 8 กรณีใช้งานจริง
• Agent Profiles & Spawner — กำหนดโปรไฟล์ agent แล้ว spawn อัตโนมัติ
• เครื่องมือ (Tools) — รายละเอียด 15 MCP tools
• การตั้งค่า — ตัวแปร environment
• ฟีเจอร์ Plugin — skills, coordinator agent, hooks
• โครงสร้างโปรเจกต์ — ผังไฟล์
• การพัฒนา — ตั้งค่า dev, ทดสอบ, สถาปัตยกรรม, เพิ่ม tool ใหม่
• สัญญาอนุญาต

ทำไมต้อง mcp-broker?

Claude Code มี Agent tool, subagents, และ teams อยู่แล้ว — แล้วทำไมต้องมี broker อีก?

ปัญหา

ระบบ multi-agent ในตัวของ Claude Code มีข้อจำกัด:

• Agent/Subagent — parent สร้าง child, child ทำงานเสร็จแล้วส่งผลกลับ จบ ไม่มีการสื่อสารต่อเนื่องระหว่าง agent
• Teams (SendMessage) — agent คุยกันได้ แต่เป็นแบบ synchronous ไม่มีประวัติข้อความ ไม่มี channel ไม่มีการติดตามสถานะออนไลน์
• ทุก session เป็นเกาะแยก — agent A ไม่รู้ว่า agent B มีอยู่ ถ้าไม่ได้ถูกสร้างจาก parent เดียวกัน

สิ่งที่ mcp-broker เพิ่มเติม

ความสามารถ	Agent/Subagent	Teams	mcp-broker
ค้นหา agent (ใครออนไลน์อยู่?)	-	-	✓
ส่งข้อความแบบ async (ฝากไว้ อีกฝั่งมาอ่านทีหลัง)	-	-	✓
Channel (สื่อสารแบบกลุ่ม)	-	-	✓
ประวัติข้อความและการเก็บข้อมูลถาวร	-	-	✓
ส่งตาม role (ส่งถึง worker ทั้งหมด)	-	-	✓
Broadcast (ประกาศทุกคน)	-	✓	✓
สื่อสารข้าม session	-	-	✓
ติดตามสถานะออนไลน์ (heartbeat)	-	-	✓

เมื่อไหร่ใช้อะไร

• ถ้าแค่ต้องการมอบหมายงานแล้วรอผล → ใช้ Agent/Subagent ของ Claude Code เลย
• ถ้าต้องการ agent หลายตัวคุยกัน, ค้นหากัน, ส่งงานแบบ async, หรือเก็บประวัติข้อความ → ใช้ mcp-broker

หลักการทำงาน

Agent A ──stdio──▶ ┌─────────────┐ ◀──stdio── Agent B
                   │  mcp-broker │
Agent C ──stdio──▶ │  (SQLite)   │ ◀──stdio── Agent D
                   └─────────────┘

แต่ละ agent เชื่อมต่อผ่าน stdio และใช้ MCP tools เพื่อ:

1. ลงทะเบียน ตัวเองด้วยชื่อและ role
2. ค้นหา agent ที่ออนไลน์อยู่
3. ส่งข้อความ — แบบตรง, broadcast, ตาม role, หรือผ่าน channel
4. รับข้อความ ใหม่ (ใช้ cursor ไม่ซ้ำ)
5. จัดการ channel สำหรับสื่อสารตามหัวข้อ

สิ่งที่ต้องติดตั้งก่อน

• Bun v1.0+ — runtime (รัน TypeScript ได้ตรง ไม่ต้อง build)
• Claude Code — CLI agent ของ Anthropic (ต้องรองรับระบบ plugin)

# ติดตั้ง Bun (macOS / Linux)
curl -fsSL https://bun.sh/install | bash

# ตรวจสอบเวอร์ชัน
bun --version

วิธีติดตั้ง

แบบ Plugin (แนะนำ)

# เพิ่ม marketplace
/plugin marketplace add krittinkhaneung/mcp-broker

# ติดตั้ง plugin
/plugin install broker

ได้ MCP server (15 tools), คำสั่ง slash, coordinator agent, และ hooks ทั้งหมด — ตั้งค่าให้อัตโนมัติ

แบบ Manual

# โคลนและติดตั้ง
git clone https://github.com/krittinkhaneung/mcp-broker.git
bun install

# เพิ่มเข้า Claude Code
claude mcp add --transport stdio broker -- bun /path/to/mcp-broker/src/index.ts

# รันทดสอบ
bun test

วิธีใช้งาน

พื้นฐาน: ลงทะเบียนและแชท

เปิด 2 Claude Code sessions ในเครื่องเดียวกัน:

Session A:

> "ลงทะเบียนชื่อ 'alice' แล้วส่งข้อความถึง bob ว่า 'พร้อมเริ่มแล้ว'"

# Claude เรียก: register(name: "alice", role: "peer")
# Claude เรียก: send_message(to: "bob", content: "พร้อมเริ่มแล้ว")

Session B:

> "ลงทะเบียนชื่อ 'bob' แล้วเช็คข้อความ"

# Claude เรียก: register(name: "bob", role: "peer")
# Claude เรียก: poll_messages()
# → ได้รับ: {from: "alice", content: "พร้อมเริ่มแล้ว"}

Channel: สื่อสารแบบกลุ่ม

> "สร้าง channel #code-review สำหรับทีม"
# Claude เรียก: create_channel(name: "#code-review", purpose: "รีวิว PR")

> "ส่งไปที่ #code-review: PR #42 ต้องการรีวิว"
# Claude เรียก: send_message(to: "channel:#code-review", content: "PR #42 ต้องการรีวิว")

ทุก agent ที่ join channel จะเห็นข้อความเมื่อ poll

Broadcast: ประกาศถึงทุกคน

> "ประกาศทุก agent: จะ deploy ใน 5 นาที"
# Claude เรียก: send_message(to: "all", content: "จะ deploy ใน 5 นาที")

ทุก agent ที่ออนไลน์จะได้รับข้อความ

ส่งข้อความตาม Role

> "ส่งถึง worker ทุกตัว: มีงานใหม่ใน #task-queue"
# Claude เรียก: send_message(to: "role:worker", content: "มีงานใหม่ใน #task-queue")

เฉพาะ agent ที่ลงทะเบียนด้วย role worker เท่านั้นที่จะได้รับ

Coordinator: ทำงานแบบขนาน