# mcp-comms

MCP server for multi-agent communication. Multiple AI agents (Claude Code, Codex, etc.) working on the same codebase can coordinate via a shared SQLite-backed message log.

## How it works

Each agent spawns its own `server.py` process over STDIO. All processes in a workspace share a single SQLite database, giving every agent a shared message bus with directed messages, broadcasts, and session discovery.

```
Agent A (claude-1) ──spawns──> server.py --name claude-1 ──┐
Agent B (codex-1)  ──spawns──> server.py --name codex-1  ──┼──> <workspace>/.agent-comms/comms.db
Agent C (codex-2)  ──spawns──> server.py --name codex-2  ──┘
```

The DB path defaults to `.agent-comms/comms.db` relative to CWD, so each project gets its own message log.

## Setup

Requires [uv](https://docs.astral.sh/uv/). No install step — `uv run --script` handles dependencies automatically via PEP 723 inline metadata.

### Claude Code

Add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "comms": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/mcp-comms/server.py", "--name", "claude-1"]
    }
  }
}
```

### Codex

Add to `.codex/config.toml` in your project:

```toml
[mcp_servers.comms]
command = "uv"
args = ["run", "--script", "/path/to/mcp-comms/server.py", "--name", "codex-1"]
```

Replace `/path/to/mcp-comms` with the actual path where you cloned this repo. Give each agent a unique `--name`.

## MCP Tools

| Tool | Description |
|------|-------------|
| `send_message(to, content)` | Send a directed message to a named session |
| `broadcast(content)` | Message all other sessions |
| `read_messages(limit, unread_only)` | Check inbox (marks messages as read) |
| `list_sessions()` | Discover other agents |
| `check_unread_count()` | Lightweight unread count (doesn't mark as read) |
| `get_conversation(with_session, limit)` | Bidirectional history with another agent |
| `read_all_messages(limit)` | Global message log (doesn't mark as read) |

## CLI Options

```
uv run --script server.py --name <session-name> [--db-path <path>]
```

- `--name` (required): unique session name for this agent
- `--db-path` (optional): path to SQLite database (default: `.agent-comms/comms.db`)

## Running Tests

```bash
uv run pytest tests/
```

## Design Notes

- **SQLite WAL mode** for concurrent reads/writes across multiple agent processes
- **Thread-safe** connections via `threading.local()`
- **Heartbeat tracking** — every tool call updates `last_heartbeat`, so agents can detect stale sessions
- **Read tracking** — messages are marked read per-session via a JSON array, so each agent gets its own unread state
- Broadcasts reach everyone except the sender
- `send_message` fails fast with a helpful error listing known sessions if the target doesn't exist
- Delete `.agent-comms/comms.db` to reset all state