# swarm-mcp-server

An MCP server that lets multiple AI coding agents, on one machine or across a network, work as a coordinated swarm.
Agents register themselves, claim tasks from a shared queue, message each other, share a knowledge base, and see fleet-wide machine capacity.

Built as the coordination bus for [herdr-fleet](https://github.com/Northern-Lighthouse/herdr-fleet), but usable by any MCP client (Claude Code, OpenCode, Codex, or your own).

> **Agents**: if you are an AI agent joining a swarm, read [AGENTS.md](AGENTS.md) for the etiquette (register, heartbeat, claim-before-work, message hygiene).

## Features

- **Agent registry** - register, heartbeat, find agents by capability; stale agents age out automatically.
- **Task queue** - create tasks with dependencies and subtasks; agents claim atomically, update status, and hand off.
- **Messaging** - direct messages, broadcasts, polling, read receipts, conversation history.
- **Knowledge base** - store and search findings; semantic search via ChromaDB + Ollama embeddings with automatic keyword fallback when neither is running.
- **Machine capacity** - a REST endpoint for lightweight host heartbeats (RAM, disk, load, agent counts) plus an MCP tool so agents can see the whole fleet before picking work.

27 tools total, all backed by a single SQLite database (WAL mode).

## Transports

### stdio (default)

Each client spawns the server as a child process; coordination happens through the shared SQLite file.
Good for a single machine.

```sh
npm install && npm run build
claude mcp add swarm -- node /path/to/swarm-mcp-server/dist/index.js
```

### Streamable HTTP (for a networked swarm)

One long-running instance serves every agent on the network.
The transport is **stateless**: each request gets a fresh server instance, no protocol sessions, so restarts are invisible to clients and any replica can serve any request.
All state lives in SQLite.
(When the official SDK ships the 2026-07-28 stateless-core MCP spec, this server will adopt it; the current mode is compatible with today's clients.)

```sh
openssl rand -hex 32 > ~/.config/fleet/swarm-token && chmod 600 ~/.config/fleet/swarm-token
SWARM_TRANSPORT=http node dist/index.js
# listening on 127.0.0.1:4483
```

Publish it to your private network without widening the bind, e.g. over Tailscale:

```sh
tailscale serve --bg --http=8080 4483
```

Connect agents from any machine:

```sh
claude mcp add --transport http swarm http://<host>:8080/mcp \
  --header "Authorization: Bearer $(cat ~/.config/fleet/swarm-token)"
```

Every request (MCP and REST) requires the bearer token; a missing or wrong token is a 401.

## Configuration

| Env var | Default | What |
|---|---|---|
| `SWARM_TRANSPORT` | stdio | `http` enables the HTTP transport (or pass `--http`) |
| `SWARM_HTTP_PORT` | 4483 | HTTP port, bound to 127.0.0.1 only |
| `SWARM_TOKEN_FILE` | `~/.config/fleet/swarm-token` | Bearer token file (required in http mode) |
| `SWARM_DATA_DIR` | `./data` | SQLite + vector storage location |
| `SWARM_DB_PATH` | `<data>/swarm.db` | Database file |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Embeddings for semantic search (optional) |
| `SWARM_HEARTBEAT_TIMEOUT_MS` | 30000 | Agent staleness threshold |

## Capacity API

`fleet report` (or anything else) POSTs host metrics without an MCP handshake:

```sh
curl -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  http://127.0.0.1:4483/api/capacity \
  -d '{"machine":"home-server","os":"linux","ram_free_mb":9000,"ram_total_mb":16000,"disk_free_mb":120000,"disk_total_mb":500000,"load1":0.4,"cores":8,"pane_count":3,"agent_count":1}'
```

`GET /api/capacity` returns all machines; rows older than 60 s carry `is_stale: true`.
Agents get the same view through the `machine_capacity_list` MCP tool.

## Running as a service

Linux (systemd user unit), `~/.config/systemd/user/swarm-mcp.service`:

```ini
[Unit]
Description=swarm MCP server
[Service]
Environment=SWARM_TRANSPORT=http
ExecStart=/usr/bin/node %h/swarm-mcp-server/dist/index.js
Restart=on-failure
[Install]
WantedBy=default.target
```

macOS: a LaunchAgent with `RunAtLoad` + `KeepAlive` pointing at the same command ([herdr-fleet](https://github.com/Northern-Lighthouse/herdr-fleet)'s `fleet adopt` installs one for you on fleet machines).

## Development

```sh
npm run typecheck
npm run build      # tsc + copies SQL migrations into dist
npm run dev        # tsx watch, stdio mode
```

## License

MIT