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: ทำงานแบบขนาน

ใช้ broker-coordinator agent สำหรับงานที่ต้องกระจาย:

> "ใช้ broker-coordinator รีวิว 3 ไฟล์นี้แบบขนาน:
   src/auth.ts, src/api.ts, src/db.ts"

Coordinator จะ:

1. ลงทะเบียนตัวเองเป็น supervisor
2. สร้าง worker agents 3 ตัว
3. แจก 1 ไฟล์ให้แต่ละ worker รีวิว
4. รวมผลรีวิวกลับมาเป็นสรุป

Agent Profiles: spawn จากโปรไฟล์

กำหนด agent ไว้ล่วงหน้าใน profiles.yml แล้ว spawn ได้ทันที:

> "ดูโปรไฟล์ที่มี"
# Claude เรียก: list_profiles()
# → [{name: "reviewer", model: "sonnet", is_running: false},
#    {name: "tester", model: "haiku", is_running: false}]

> "spawn reviewer มารีวิว src/auth.ts"
# Claude เรียก: spawn_agent(profile: "reviewer", task: "Review src/auth.ts for security issues")
# → {name: "reviewer", pid: 45678, status: "spawned"}
# reviewer ลงทะเบียนอัตโนมัติ ทำงานแบบ non-interactive แล้วจบเอง

> "spawn tester มาเขียน test ให้ src/utils.ts"
# Claude เรียก: spawn_agent(profile: "tester", task: "Write tests for src/utils.ts")
# → {name: "tester", pid: 45679, status: "spawned"}

ถ้าต้องการหยุด agent ก่อนทำเสร็จ:

> "หยุด reviewer"
# Claude เรียก: stop_agent(name: "reviewer")
# → {name: "reviewer", stopped: true}

ค้นหา: ใครออนไลน์อยู่?

> "แสดง agent ที่ออนไลน์ทั้งหมด"
# Claude เรียก: list_peers()
# → [{name: "alice", role: "peer", status: "idle", online: true}, ...]

> "แสดงเฉพาะ worker"
# Claude เรียก: list_peers(role: "worker")

list_peers ไม่ต้องลงทะเบียนก่อนก็ใช้ได้ — เหมาะสำหรับ monitoring

ตัวอย่างการใช้งาน

1. รีวิวโค้ดแบบขนาน

สถานการณ์: มี PR ใหญ่ ต้องรีวิวหลายไฟล์

> "ใช้ broker-coordinator รีวิว PR #123 แบ่งตาม directory:
   - src/api/ (REST endpoints)
   - src/services/ (business logic)
   - src/models/ (data layer)"

Coordinator สร้าง worker 3 ตัว แต่ละตัวโฟกัสคนละ layer รวมผลกลับเป็นรีวิวรวม

2. งานระยะยาวข้าม Session

สถานการณ์: งานที่ใช้เวลานาน ต้องส่งต่อระหว่าง session

Session 1 (ผู้มอบหมาย):

> "ลงทะเบียนชื่อ 'pipeline' แล้วโพสต์งานเหล่านี้ไปที่ #jobs:
   1. ย้ายโครงสร้างฐานข้อมูล
   2. อัปเดต API endpoints
   3. เขียน integration tests"

Session 2 (ผู้รับงาน — อาจเปิดทีหลัง):

> "ลงทะเบียนชื่อ 'worker-1' เข้าร่วม #jobs แล้วรับงานถัดไป"
# Worker poll #jobs เห็นงาน เริ่มทำ
# ทำเสร็จแล้วโพสต์ผลกลับไป #jobs

ข้อความเก็บใน SQLite — ไม่หายแม้ session เดิมจะปิดไปแล้ว

3. ประสานงานข้ามโปรเจกต์

สถานการณ์: ทำงาน 2 โปรเจกต์ที่เกี่ยวข้องกัน (เช่น frontend + backend)

Terminal 1 (~/frontend):

> "ลงทะเบียนชื่อ 'frontend-dev'
   ถ้า API contract เปลี่ยน ส่งข้อความบอก endpoint ใหม่ด้วย"

Terminal 2 (~/backend):

> "ลงทะเบียนชื่อ 'backend-dev' เพิ่งเพิ่ม POST /api/tasks
   ส่งถึง frontend-dev: 'endpoint ใหม่ POST /api/tasks
   request body: {title: string, priority: number}'"

ทั้ง 2 โปรเจกต์ใช้ broker.db เดียวกัน — คุยกันข้ามโปรเจกต์ได้

4. รูปแบบ Supervisor + Workers

สถานการณ์: ต้องการ 1 agent คอย monitor และจัดการ worker หลายตัว

> "ลงทะเบียนชื่อ 'supervisor' ด้วย role supervisor
   สร้าง channel #status
   คอย poll #status — ถ้า worker ไหนรายงาน 'failed' ให้มอบหมายงานใหม่"

Worker รายงานสถานะเข้า #status:

> "ลงทะเบียนชื่อ 'worker-1' ด้วย role worker
   เข้าร่วม #status โพสต์สถานะขณะทำงาน
   ทำเสร็จแล้วส่งถึง supervisor: 'task-A เสร็จแล้ว'"

5. ระดมสมองหลายมุมมอง

สถานการณ์: ต้องการหลายมุมมองสำหรับตัดสินใจเรื่องการออกแบบ

> "ใช้ broker-coordinator ระดมสมองเรื่องออกแบบฐานข้อมูล
   สร้าง 3 agent ที่มีมุมมองต่างกัน:
   - Agent 1: เน้นประสิทธิภาพการอ่าน
   - Agent 2: เน้นปริมาณการเขียน
   - Agent 3: เน้นความเรียบง่ายและดูแลง่าย
   รวบรวมข้อเสนอทั้งหมดแล้วสังเคราะห์แนวทางที่ดีที่สุด"

6. รันชุดทดสอบหลายสภาพแวดล้อม

สถานการณ์: รันทดสอบหลาย environment พร้อมกัน

> "ใช้ broker-coordinator รันชุดทดสอบในหลายการตั้งค่า:
   - Node 20 + PostgreSQL 15
   - Node 22 + PostgreSQL 16
   - Bun + SQLite
   รายงานว่าชุดค่าไหนผ่าน/ไม่ผ่าน"

7. Spawn agent จากโปรไฟล์ — รีวิว + ทดสอบอัตโนมัติ

สถานการณ์: มีโปรไฟล์ reviewer และ tester ตั้งไว้แล้ว อยาก spawn ทั้งคู่ทำงานพร้อมกัน

> "ลงทะเบียนชื่อ 'lead' เป็น supervisor
   spawn reviewer มารีวิว src/api/ ทั้ง directory
   spawn tester มาเขียน test ให้ src/services/"

# Claude เรียก: register(name: "lead", role: "supervisor")
# Claude เรียก: spawn_agent(profile: "reviewer", task: "Review all files in src/api/")
# Claude เรียก: spawn_agent(profile: "tester", task: "Write tests for src/services/")

# reviewer และ tester ลงทะเบียนอัตโนมัติ ทำงานแบบ non-interactive
# lead สามารถ poll_messages() เพื่อดูผลเมื่อเสร็จ
# ถ้า agent ไหน crash จะได้รับ DM แจ้งอัตโนมัติ

8. Spawn agent ตาม role เฉพาะทาง

สถานการณ์: ตั้งโปรไฟล์หลายตัวไว้ใช้ตามงาน — security audit, performance check, docs writer

# profiles.yml
profiles:
  security-auditor:
    system_prompt: |
      You are a security specialist.
      Scan for vulnerabilities: injection, XSS, auth bypass, secrets in code.
    model: opus
    max_budget_usd: 3.00
    allowed_tools: [Read, Grep, Glob, Bash]
    role: worker

  docs-writer:
    system_prompt: |
      You are a technical writer.
      Write clear, concise documentation for the given code.
    model: haiku
    max_budget_usd: 1.00
    allowed_tools: [Read, Write, Edit, Grep, Glob]
    role: worker

> "spawn security-auditor มาตรวจ src/auth/ ทั้งหมด"
# Claude เรียก: spawn_agent(profile: "security-auditor", task: "Full security audit of src/auth/")

> "spawn docs-writer มาเขียน docs ให้ src/api/"
# Claude เรียก: spawn_agent(profile: "docs-writer", task: "Write API documentation for src/api/")

ใช้ list_profiles() เพื่อดูว่า agent ไหนกำลังทำงานอยู่ และ stop_agent() เพื่อหยุดก่อนเวลา

Agent Profiles & Spawner

กำหนดโปรไฟล์ agent ไว้ล่วงหน้าใน YAML แล้วให้ broker spawn Claude Code instance ให้อัตโนมัติ — ไม่ต้องเขียน prompt เองทุกครั้ง

ตั้งค่าโปรไฟล์

สร้างไฟล์ ~/.claude/mcp-broker/profiles.yml (ดูตัวอย่างใน profiles.example.yml):

profiles:
  reviewer:
    system_prompt: |
      You are an expert code reviewer.
      Check for code quality, security, and performance.
    model: sonnet
    max_budget_usd: 1.00
    allowed_tools:
      - Read
      - Grep
      - Glob
      - Bash
    additional_instructions: |
      ## Review Guidelines
      - Check OWASP Top 10
      - Report only, do not modify code
    role: worker
    permission_mode: auto

  tester:
    system_prompt: |
      You are a test engineer.
      Write comprehensive tests covering edge cases.
    model: haiku
    max_budget_usd: 2.00
    allowed_tools:
      - Read
      - Write
      - Edit
      - Bash
    role: worker

ฟิลด์โปรไฟล์

วิธีใช้

> "ดูโปรไฟล์ที่มีทั้งหมด"
# Claude เรียก: list_profiles()
# → [{name: "reviewer", model: "sonnet", is_running: false}, ...]

> "spawn reviewer มารีวิวไฟล์ src/auth.ts"
# Claude เรียก: spawn_agent(profile: "reviewer", task: "Review src/auth.ts")
# → {name: "reviewer", pid: 12345, status: "spawned"}

> "หยุด reviewer"
# Claude เรียก: stop_agent(name: "reviewer")
# → {name: "reviewer", stopped: true}

คุณสมบัติ

• Singleton — 1 โปรไฟล์ = 1 instance (ป้องกัน spawn ซ้ำ)
• Auto-register — agent ลงทะเบียนกับ broker อัตโนมัติ สื่อสารผ่าน message ได้ทันที
• Crash detection — ถ้า agent crash จะแจ้ง coordinator ผ่าน DM อัตโนมัติ
• Graceful shutdown — SIGTERM → รอ 10 วิ → SIGKILL
• Cleanup — ปิด broker แล้ว agent ทั้งหมดถูก cleanup อัตโนมัติ

เครื่องมือ (Tools)

ลงทะเบียนและติดตามสถานะ

ส่งข้อความ

Channel

ค้นหาและประวัติ

โปรไฟล์และ Spawner

การตั้งค่า

ตั้งค่าทั้งหมดผ่านตัวแปร environment:

ฟีเจอร์ Plugin

คำสั่ง Slash

Coordinator Agent

ใช้ broker-coordinator สำหรับประสานงานหลาย agent:

• กระจายงานให้ worker agent หลายตัวทำพร้อมกัน
• คิวงานพร้อมลองใหม่อัตโนมัติเมื่อล้มเหลว
• ติดตามความคืบหน้าและรวบรวมผลลัพธ์

Session Hooks

• เริ่ม Session — ลงทะเบียน agent อัตโนมัติเมื่อเปิด session
• จบ Session — ยกเลิกการลงทะเบียนอัตโนมัติเมื่อปิด

โครงสร้างโปรเจกต์

.claude-plugin/
  plugin.json       ไฟล์ manifest ของ plugin
  marketplace.json  รายการสำหรับ GitHub marketplace
.mcp.json           การตั้งค่า MCP server (ตั้งค่าอัตโนมัติโดย plugin)
skills/
  status/SKILL.md   /broker:status
  reset/SKILL.md    /broker:reset
  setup/SKILL.md    /broker:setup
agents/
  broker-coordinator.md   agent ประสานงานหลายตัว
hooks/
  hooks.json        ลงทะเบียนอัตโนมัติเมื่อเริ่ม/จบ session
profiles.example.yml  ตัวอย่างไฟล์โปรไฟล์ agent
src/
  index.ts          จุดเริ่มต้น MCP server — ลงทะเบียน 15 tools
  config.ts         การตั้งค่าจาก environment พร้อมค่าเริ่มต้น
  errors.ts         คลาส BrokerError สำหรับจัดการ error
  db.ts             สร้างโครงสร้าง SQLite (WAL mode, foreign keys, migration)
  state.ts          สถานะ session ในหน่วยความจำ (agent ปัจจุบัน + spawned processes)
  presence.ts       heartbeat, ตรวจสอบออนไลน์, ตัด agent หมดอายุ
  types.ts          interface หลัก (Agent, Channel, Message, Profile, SpawnedProcess)
  validators.ts     ตรวจสอบข้อมูลนำเข้า (ชื่อ, channel, role, เนื้อหา)
  profiles.ts       โหลดและตรวจสอบโปรไฟล์ agent จาก YAML
  spawner.ts        spawn/stop Claude CLI, จัดการ process, MCP config generation
  tools/
    register.ts     register, heartbeat, unregister
    messaging.ts    send_message, poll_messages
    channels.ts     create_channel, join_channel, leave_channel, list_channels
    peers.ts        list_peers
    history.ts      get_history, purge_history
    spawn.ts        spawn_agent, stop_agent, list_profiles
tests/
  helpers.ts        เครื่องมือทดสอบ SQLite ในหน่วยความจำ
  *.test.ts         ทดสอบครบทุกโมดูล

การพัฒนา

สิ่งที่ต้องมี

• Bun v1.0+
• Git

ตั้งค่า

git clone https://github.com/krittinkhaneung/mcp-broker.git
cd mcp-broker
bun install

คำสั่งที่ใช้บ่อย

bun test              # รันทดสอบทั้งหมด (SQLite ในหน่วยความจำ)
bun test --watch      # รันทดสอบแบบ watch mode
bun run build         # คอมไพล์ TypeScript ไปที่ dist/
bun run dev           # คอมไพล์แบบ --watch
bun src/index.ts      # เริ่ม MCP server ตรง (stdio)

การรันทดสอบ

ใช้ SQLite ในหน่วยความจำ — ไม่ต้องตั้งค่าฐานข้อมูล:

$ bun test
bun test v1.x.x

 ✓ tests/db.test.ts
 ✓ tests/register.test.ts
 ✓ tests/messaging.test.ts
 ✓ tests/channels.test.ts
 ✓ tests/peers.test.ts
 ✓ tests/history.test.ts
 ✓ tests/wrapHandler.test.ts

เพิ่ม Tool ใหม่

1. สร้าง handler ใน src/tools/ (ดูตัวอย่างจาก peers.ts)
2. เพิ่มไฟล์ทดสอบใน tests/
3. ลงทะเบียน tool ใน src/index.ts ด้วย server.registerTool()
4. อัปเดตตาราง tools ใน README

สถาปัตยกรรมโปรเจกต์

MCP Client (Claude) ──stdio──▶ index.ts (MCP Server)
                                  │
                                  ├─ tools/register.ts   ──▶ state.ts (สถานะ session)
                                  ├─ tools/messaging.ts  ──▶ presence.ts (heartbeat)
                                  ├─ tools/channels.ts   ──▶ validators.ts (ตรวจสอบข้อมูล)
                                  ├─ tools/peers.ts      ──▶ errors.ts (BrokerError)
                                  ├─ tools/history.ts    ──▶ db.ts (SQLite)
                                  └─ tools/spawn.ts      ──▶ profiles.ts (YAML config)
                                       │                 ──▶ spawner.ts (process mgmt)
                                       │                        │
                                       ▼                        ▼
                                  claude CLI ◀──────── profiles.yml
                                  (spawned)                  │
                                                             ▼
                                                         broker.db

เทคโนโลยีที่ใช้

Dependencies

Runtime:

• @modelcontextprotocol/sdk — MCP server framework
• uuid — สร้าง ID ที่ไม่ซ้ำ
• zod — ตรวจสอบ schema
• yaml — อ่านไฟล์โปรไฟล์ agent

Dev:

• typescript — ตรวจสอบ type และคอมไพล์
• bun-types — type definitions สำหรับ Bun API
• @types/uuid — type definitions สำหรับ UUID

สัญญาอนุญาต

MIT