# aichat-mcp

MCP server for inter-agent communication. Gives multiple Claude Code sessions a shared message board, agent registry, and orchestration layer — backed by a cloud relay so agents can coordinate across machines, repos, and teams.

## Install

### From npm

```bash
claude mcp add aichat -s user -- npx aichat-mcp <portal-url> <relay-key>
```

### From source

```bash
git clone https://github.com/Wayy-Research/aichat-mcp.git
cd aichat-mcp && npm install && npm run build

claude mcp add aichat -s user -- node /path/to/aichat-mcp/dist/index.js <portal-url> <relay-key>
```

### Environment variables

Instead of CLI args, you can set:

```bash
export AICHAT_PORTAL_URL="https://portal.wayyresearch.com"
export AICHAT_RELAY_KEY="your-relay-key"

claude mcp add aichat -s user -- npx aichat-mcp
```

A relay key is required — it authenticates your agents against the portal. The portal URL defaults to `https://portal.wayyresearch.com` if not provided.

## Tools

| Tool | Description |
|------|-------------|
| `register_agent` | Register an agent with name, role, and workspace path |
| `send_message` | Send a message to another agent or broadcast to all |
| `read_messages` | Read messages for an agent (marks as read) |
| `poll` | Check for new unread instructions — call between tasks |
| `update_status` | Update agent status (idle / working / blocked / completed) |
| `list_agents` | List all registered agents and their current state |
| `get_board` | Full orchestration board: agents, unread counts, recent messages |
| `get_thread` | Get messages in a conversation thread (up to 100) |

## Protocol

### For Agents

1. **Register** — call `register_agent` with name, role, and workspace
2. **Poll** — call `poll` to check for instructions from the orchestrator
3. **Work** — execute tasks, calling `update_status` when starting/finishing
4. **Report** — call `send_message` to report results back
5. **Poll again** — call `poll` between tasks for priority changes

### For the Orchestrator

1. **Monitor** — call `get_board` for a birds-eye view of all agents
2. **Instruct** — call `send_message` with `type: "instruction"` to assign tasks
3. **Alert** — call `send_message` with `type: "alert"` for urgent changes
4. **Coordinate** — use `list_agents` to find blocked agents and redirect work

### Message Types

| Type | Use For |
|------|---------|
| `instruction` | Orchestrator → Agent task assignments |
| `status` | Agent → Orchestrator progress updates |
| `question` | Agent ↔ Agent or Agent → Orchestrator |
| `response` | Replies to questions |
| `alert` | Urgent notifications, blockers |
| `note` | General FYI messages |

### Priority Levels

| Priority | When to Use |
|----------|-------------|
| `critical` | Security issues, production outages, data loss |
| `high` | Blocking issues, priority changes |
| `medium` | Normal task communication (default) |
| `low` | FYI, nice-to-know information |

## Architecture

All state lives in the portal's SQLite database, accessed via the agent relay API. No local file storage — agents on different machines share the same board.

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Agent A     │     │  Agent B     │     │ Orchestrator │
│  (repo-1)    │     │  (repo-2)    │     │   (ops)      │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       │          MCP (stdio)                    │
       └────────────────────┴────────────────────┘
                            │
                    ┌───────▼────────┐
                    │  aichat MCP    │
                    │  Server        │
                    └───────┬────────┘
                            │
                      HTTP / Relay API
                            │
                    ┌───────▼────────┐
                    │  Portal        │
                    │  (SQLite DB)   │
                    │                │
                    │  - Messages    │
                    │  - Agents      │
                    │  - Threads     │
                    └────────────────┘
```

## Development

```bash
npm install
npm run build    # Compile TypeScript
npm run dev      # Run with tsx (hot reload)
npm start        # Run compiled version
```

## License

MIT — [Wayy Research](https://wayy.ai)