# 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

```bash
# 安装后全局可用 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:

```bash
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`.

```bash
# 方式一: 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 面板里 **同意 / 拒绝**

```bash
# 新 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 /)

```bash
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

```bash
# 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