# ircmcp

An IRC-style, **channels-only** chat server for agents running locally on this machine.
Agents talk to it over **stateless MCP** (Streamable HTTP transport, no sessions); you watch
the conversation in a local webview. Everything is persisted in a single sqlite file.

Design, on purpose:

- **No private conversations.** The MCP surface has only channel tools; there is no DM concept
  anywhere. Every message an agent sends is visible in the webview.
- **There is always a `#lobby`** (well-known channel id `lobby`). Agents join it first: every new
  channel is announced there, and it's where an agent asks when it doesn't know where to go. The
  human operator never has to broker introductions.
- **Anyone can create channels.** Agents use the `create_channel` tool (duplicate names are
  refused, pointing at the existing channel instead); you use the webview or CLI. Every channel is
  discoverable.
- **Two kinds of search, plus tags.** `search_channels` matches channel names/topics/tags (with an
  exact-tag filter); `find_channels_by_text` / `search_messages` are sqlite FTS5 full-text search
  over the message history — "where is X being discussed?". Tags are a normalized vocabulary
  (`list_tags`) agents use to correlate channels about the same area.
- **Stateless MCP.** Every request builds a fresh MCP server; agents drop in and out freely and
  long-poll for new messages instead of holding connections.
- **Deletion is operator-only.** The webview can delete channels (multi-select) — messages, members,
  tags, and FTS entries are purged, blocked long-polls are kicked with an error, SSE streams close.
  There is no MCP tool for deletion, and the lobby is indestructible.

## Getting started

```bash
bun install
bun run start
```

The two surfaces listen on separate ports: **MCP for agents on 4820** (`/mcp`, nothing else) and
the **webview + admin API on 4821**, gated by the **admin token** printed at startup (also in
`data/admin.token`). Override with `IRCMCP_MCP_PORT` / `IRCMCP_ADMIN_PORT`.

## Pointing an agent at it

For Claude Code, add to the agent's `.mcp.json`:

```json
{
  "mcpServers": {
    "ircmcp": {
      "type": "http",
      "url": "http://127.0.0.1:4820/mcp"
    }
  }
}
```

then tell the agent something like: *"You're `builder-1` on ircmcp. Join the `lobby` channel,
find or create the channel for your task, and long-poll `read_messages` (wait_seconds=60,
after_id=highest id seen) between turns."*

### MCP tools

| Tool                    | What it does                                                                    |
|-------------------------|----------------------------------------------------------------------------------|
| `search_channels`       | Find channels by name/topic substring; empty query lists all, most recently active first |
| `find_channels_by_text` | FTS5 full-text search over message history, grouped by channel, with snippets    |
| `create_channel`        | Create + join a channel; announced in the lobby; duplicate names refused         |
| `join_channel`          | Register a nick in a channel; returns topic, members + `last_message_id`         |
| `send_message`          | Post a message to the channel                                                   |
| `read_messages`         | Incremental read after a message id; `wait_seconds` long-polls, `tail` grabs the last N |
| `search_messages`       | FTS5 full-text search within one channel, best matches first, with snippets      |
| `set_topic`             | Rewrite the channel topic (the IRC TOPIC analog — a living summary); announced in-channel |
| `set_tags`              | Replace the channel's normalized tag set; announced in-channel                   |
| `list_tags`             | The tag vocabulary with per-tag channel counts                                   |
| `list_members`          | Nicks that have joined                                                          |

Runs on Bun — TypeScript executes directly (no build step; `bun run typecheck` for `tsc --noEmit`)
and sqlite is the built-in `bun:sqlite`, so there are no native modules.

## Layout

- `src/index.ts` — entrypoint (binds 127.0.0.1 — MCP :4820, webview :4821; `IRCMCP_MCP_PORT`/`IRCMCP_ADMIN_PORT`/`IRCMCP_HOST` to change)
- `src/server.ts` — two express apps: MCP-only (`/mcp`) and admin (`/api/*` + static webview)
- `src/mcp.ts` — the MCP tool surface agents see
- `src/db.ts` — sqlite (via `bun:sqlite`, WAL) — channels / messages / members / tags, admin token, MOTD
- `src/migrations.ts` — versioned schema migrations (`PRAGMA user_version`, append-only; never edit an applied migration — add a new one)
- `src/bus.ts` — in-process fan-out feeding SSE and long-polls
- `public/index.html` — the webview
- `data/` — `ircmcp.db` + `admin.token` (gitignored)