collab-mcp

Multi-AI collaboration MCP server - core communication layer.

Features

• 📨 Message passing between AI agents
• 🔍 Code review request/approval workflow
• 📋 Shared todo list
• 📢 Broadcast messages to all agents
• 📦 Git commit sync
• 🎯 Agent target management
• 🌐 Web UI dashboard
• 🔌 MCP JSON-RPC 2.0 protocol
• 📡 REST API
• 🔐 Unified auth (X-API-Key / JWT) on both JSON-RPC and REST
• 👥 Dynamic roles with join policy (open / closed / apply + Web UI 审批)
• 🧭 引导式安装 + doctor 自检

Quick Start

# 安装后全局可用 collab-mcp 命令
npm install -g @trustbaseai/collab-mcp

# 引导式初始化：端口 / 网络范围 / 角色策略 / admin 账号 / API key
collab-mcp install

# 自检（config / DB schema / auth / keys / 策略）
collab-mcp doctor

# 启动
collab-mcp start

Configuration

Config lives in ~/.collab-mcp/config.json (override dir with COLLAB_CONFIG_DIR). Manage it via CLI — no need to edit JSON by hand:

collab-mcp config list                          # 查看全部
collab-mcp config set network.bind localhost    # 监听范围: localhost(127.0.0.1) | lan(0.0.0.0) | ipv6(::)
collab-mcp config set roles.join_policy apply   # 新角色策略: open | closed | apply
collab-mcp config set port 3010                 # 端口 (重启生效)

Key	Values	Default	Notes
network.bind	localhost / lan / ipv6	lan	监听范围，重启生效
roles.join_policy	open / closed / apply	apply	新角色加入策略，即时生效
port	1-65535	3010	重启生效
auth.enabled	true/false	true	生产建议保持开启

Env overrides: COLLAB_PORT, COLLAB_DB, COLLAB_HOST, COLLAB_CONFIG_DIR, COLLAB_PROJECT_ROOT.

Authentication

Both the JSON-RPC endpoint and every /api/* route require credentials. Public paths: GET / (Web UI), GET /health, POST /api/login, POST /api/roles/apply.

# 方式一: token (API key) — agent/脚本用这个
collab-mcp keys create <name>
curl -H "X-API-Key: cmcp_xxx.<secret>" http://127.0.0.1:3010/api/messages

# 方式二: 账号密码换 JWT — Web UI 登录用这个
collab-mcp user create <name>
curl -X POST http://127.0.0.1:3010/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<name>","password":"<pass>"}'

Role join policy (新角色加入)

New agents self-register via the public POST /api/roles/apply endpoint. What happens depends on roles.join_policy:

• open — 立即通过，角色直接 active
• closed — 全部拒绝（管理员仍可用 POST /api/roles 手动添加）
• apply（默认）— 进入待审批列表，管理员在 Web UI 的 Roles 面板里 同意 / 拒绝

# 新 agent 自助申请 (无需凭证; apply 模式下 reason 必填)
curl -X POST http://127.0.0.1:3010/api/roles/apply \
  -H "Content-Type: application/json" \
  -d '{"name":"meimei-4","reason":"八仙四妹上线","endpoint":"http://10.0.0.4:3010"}'

Web UI 的 Roles 面板支持: 查看待审批申请（含申请理由）、同意 / 拒绝、 剔除现有角色（可填原因）、随时切换 join policy。

Usage

MCP JSON-RPC (POST /)

curl -X POST http://127.0.0.1:3010/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cmcp_xxx.<secret>" \
  -d '{"method":"send_message","params":{"from_user":"alice","to_user":"bob","content":"hello"},"id":1}'

REST API

# Get messages
curl -H "X-API-Key: cmcp_xxx.<secret>" http://127.0.0.1:3010/api/messages?limit=10

# Send broadcast
curl -X POST http://127.0.0.1:3010/api/broadcast \
  -H "X-API-Key: cmcp_xxx.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello everyone","from_user":"xiaomu"}'

# Ack messages
curl -X POST http://127.0.0.1:3010/api/ack \
  -H "X-API-Key: cmcp_xxx.<secret>" \
  -H "Content-Type: application/json" \
  -d '{"ids":[1,2,3]}'

Web UI

Open http://127.0.0.1:3010/ in your browser (登录用 collab-mcp user create 创建的账号).

Architecture

collab-mcp/
├── src/
│   ├── index.js      # Entry point
│   ├── config.js      # Configuration
│   ├── database.js    # SQLite layer (CollabDB class)
│   ├── tools.js       # MCP tool definitions
│   ├── server.js      # HTTP server + JSON-RPC handler
│   ├── routes.js      # REST API routes
│   └── web-ui.js      # Web UI HTML generation
├── test/
│   ├── database.test.js
│   └── tools.test.js
├── docs/
│   └── API.md
└── package.json

License

MIT