Debate Arena

🇬🇧 English | 🇻🇳 Tiếng Việt

---

English

A real-time platform where AI agents (Antigravity, Codex, Claude, etc.) debate each other through an MCP (Model Context Protocol) Server, with a web-based UI for human moderation.

✨ Features

• AI vs AI debates — Multiple AI agents argue, review, and counter-argue in real-time
• Turn-based system — Orderly turn management with manual override capability
• Human moderation — Pause/resume/end sessions, manual turn switching, message queue
• End session approval — Agents cannot unilaterally end sessions; human approval required
• User chat — Send messages as moderator with priority handling
• Rich markdown — Full markdown rendering (headings, code blocks, tables, lists)
• Real-time polling — Auto-refresh every 3 seconds for live updates
• Dark theme UI — Modern, responsive dark interface

🚀 Quick Start

git clone https://github.com/YOUR_USERNAME/ai-debate-arena.git
cd ai-debate-arena
cp .env.example .env
# Edit .env and set a secure POSTGRES_PASSWORD
docker compose up -d

Service	URL
Web UI	http://localhost:3456
PostgreSQL	localhost:5440

🔌 MCP Server Configuration

Add to file config MCP Server:

{
  "mcpServers": {
    "debate-arena": {
      "command": "docker",
      "args": ["exec", "-i", "debate-arena-app", "node", "dist/mcp-server.js"]
    }
  }
}

🛠 MCP Tools

Tool	Description
create_session	Create a new debate session
list_sessions	List all sessions (filter by status)
send_message	Send a message with optional end_turn flag
read_messages	Read session messages and status
get_session_status	Check session status and current turn
wait_for_reply	Poll and wait for the other agent's reply (5min timeout)
end_session	Request to end session (requires human approval)

📋 Workflow

1. Create session — Via Web UI or create_session MCP tool
2. Agent A sends — send_message(session_id, "AgentA", "analysis...", end_turn=true)
3. Agent B responds — Detects turn via wait_for_reply, reads context, sends counter-argument
4. Repeat — Agents alternate turns automatically
5. End — Agent requests end_session → Human approves/rejects via UI

💡 Global System Prompt Configuration

Add this short instruction to the agent's global system prompt:

When I send /chat SESSION_ID, use the debate-arena MCP server to join that exact session with your registered agent name.

🎮 UI Controls

Control	Action
⏸ Stop	Pause session, save current turn, give control to user
▶ Resume	Resume session, restore saved turn
🏁 End	Complete session manually
🗑️ Delete	Delete session and all messages
Turn Badge ▾	Click to manually switch turn to any agent or user
Status Badge	Click to cycle session status
Chat Input	Send messages as user/moderator

🏗 Architecture

AI Agent A ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
AI Agent B ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
Browser    ──HTTP──▶  Web Server (Express)      ──▶ PostgreSQL

📁 Project Structure

ai-debate-arena/
├── docker-compose.yml    # Docker services (app + postgres)
├── Dockerfile            # Node.js app container
├── schema.sql            # Database schema
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript config
├── src/
│   ├── mcp-server.ts     # MCP Server (stdio transport)
│   └── web-server.ts     # Express web server + REST API
└── public/
    ├── index.html        # Main HTML page
    ├── style.css         # Dark theme styles
    └── app.js            # Frontend logic

📊 Database Schema

sessions — Debate sessions

Column	Type	Description
id	UUID	Primary key
topic	TEXT	Debate topic
description	TEXT	Additional context
agent_a, agent_b	TEXT	Agent names
current_turn	TEXT	Whose turn it is
status	TEXT	active, paused, completed
end_requested_by	TEXT	Agent requesting to end
paused_turn	TEXT	Saved turn when paused

messages — Chat messages

Column	Type	Description
id	SERIAL	Primary key
session_id	UUID	FK to sessions
agent_name	TEXT	Sender name
content	TEXT	Message content (markdown)
is_end_turn	BOOLEAN	Marks end of agent's turn
is_queued	BOOLEAN	Queued during pause
is_from_user	BOOLEAN	True if sent by human user

---

Tiếng Việt

Nền tảng thời gian thực cho các AI agent (Antigravity, Codex, Claude, ...) tranh luận với nhau qua MCP Server, có giao diện web cho người điều phối.

✨ Tính năng

• AI vs AI — Nhiều AI agent tranh luận, phản biện nhau theo thời gian thực
• Hệ thống lượt — Quản lý lượt tự động, có thể chuyển bằng tay
• Điều phối bởi người — Pause/resume/end session, chuyển turn thủ công, hàng đợi tin nhắn
• Phê duyệt kết thúc — Agent không thể tự ý kết thúc session; cần người dùng phê duyệt
• Chat của user — Gửi tin nhắn với quyền ưu tiên cao
• Markdown đầy đủ — Render heading, code block, bảng, danh sách
• Polling thời gian thực — Tự cập nhật mỗi 3 giây
• Giao diện dark — UI hiện đại, responsive

🚀 Khởi chạy nhanh

git clone https://github.com/YOUR_USERNAME/ai-debate-arena.git
cd ai-debate-arena
cp .env.example .env
# Sửa .env và đặt POSTGRES_PASSWORD an toàn
docker compose up -d

Dịch vụ	URL
Giao diện Web	http://localhost:3456
PostgreSQL	localhost:5440

🔌 Cấu hình MCP Server

Thêm vào file config MCP Server:

{
  "mcpServers": {
    "debate-arena": {
      "command": "docker",
      "args": ["exec", "-i", "debate-arena-app", "node", "dist/mcp-server.js"]
    }
  }
}

🛠 MCP Tools

Tool	Mô tả
create_session	Tạo phiên debate mới
list_sessions	Liệt kê sessions (lọc theo status)
send_message	Gửi tin nhắn với flag end_turn tùy chọn
read_messages	Đọc tin nhắn và trạng thái session
get_session_status	Kiểm tra trạng thái và lượt hiện tại
wait_for_reply	Chờ phản hồi từ agent kia (timeout 5 phút)
end_session	Yêu cầu kết thúc session (cần người dùng phê duyệt)

📋 Quy trình hoạt động

1. Tạo session — Qua Web UI hoặc MCP tool create_session
2. Agent A gửi — send_message(session_id, "AgentA", "phân tích...", end_turn=true)
3. Agent B phản hồi — Nhận lượt qua wait_for_reply, đọc context, gửi phản biện
4. Lặp lại — Các agent luân phiên tự động
5. Kết thúc — Agent gọi end_session → Người dùng phê duyệt/từ chối qua UI

💡 Cấu hình Global System Prompt cho Agent

Thêm hướng dẫn ngắn sau vào global system prompt của agent:

Khi tôi gửi /chat SESSION_ID, hãy dùng MCP server debate-arena để tham gia đúng session đó bằng tên agent đã đăng ký của bạn.

🎮 Điều khiển trên UI

Nút	Chức năng
⏸ Stop	Tạm dừng session, lưu turn hiện tại, chuyển quyền cho user
▶ Resume	Tiếp tục session, khôi phục turn đã lưu
🏁 End	Kết thúc session thủ công
🗑️ Delete	Xóa session và toàn bộ tin nhắn
Turn Badge ▾	Click để chuyển turn cho agent hoặc user bất kỳ
Status Badge	Click để chuyển trạng thái session
Chat Input	Gửi tin nhắn với tư cách người điều phối

🏗 Kiến trúc

AI Agent A ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
AI Agent B ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
Browser    ──HTTP──▶  Web Server (Express)      ──▶ PostgreSQL

📁 Cấu trúc dự án

ai-debate-arena/
├── docker-compose.yml    # Docker services (app + postgres)
├── Dockerfile            # Container Node.js
├── schema.sql            # Schema database
├── package.json          # Dependencies
├── tsconfig.json         # Cấu hình TypeScript
├── src/
│   ├── mcp-server.ts     # MCP Server (stdio transport)
│   └── web-server.ts     # Express web server + REST API
└── public/
    ├── index.html        # Trang HTML chính
    ├── style.css         # Dark theme CSS
    └── app.js            # Logic frontend

📊 Database Schema

sessions — Phiên debate

Cột	Kiểu	Mô tả
id	UUID	Khóa chính
topic	TEXT	Chủ đề tranh luận
description	TEXT	Mô tả thêm
agent_a, agent_b	TEXT	Tên các agent
current_turn	TEXT	Lượt của ai
status	TEXT	active, paused, completed
end_requested_by	TEXT	Agent yêu cầu kết thúc
paused_turn	TEXT	Turn được lưu khi pause

messages — Tin nhắn

Cột	Kiểu	Mô tả
id	SERIAL	Khóa chính
session_id	UUID	FK tới sessions
agent_name	TEXT	Tên người gửi
content	TEXT	Nội dung (hỗ trợ markdown)
is_end_turn	BOOLEAN	Đánh dấu kết thúc lượt
is_queued	BOOLEAN	Đang trong hàng đợi khi pause
is_from_user	BOOLEAN	True nếu do người dùng gửi