76040407b6
The matrix wake body description said '[matrix] <sender> in <room>: <first-100c>...' (old single-line teaser). After feat(#1137) it's now a richer format: - Single room, 1 message: terse one-liner with sender + body - Single room, N messages: count + room name - Multi-room: bulleted list with per-room summaries Also note that the same breakdown appears in get_loose_ends via the UnreadMatrix entry.
83 lines
3.3 KiB
Markdown
83 lines
3.3 KiB
Markdown
# Matrix MCP tools and extra MCP servers
|
|
|
|
## Built-in matrix MCP (`mcp__matrix__*`)
|
|
|
|
When `hyperhive.matrix.enable = true` and the host-level matrix
|
|
tuwunel is configured, the harness auto-injects `hive-matrix-mcp` as
|
|
a second stdio MCP server. Tools land as `mcp__matrix__<name>`:
|
|
|
|
### Messaging
|
|
|
|
- `send_message(room, body)` — send a markdown message; `room`
|
|
accepts `!id:server` or `#alias:server`, daemon resolves either
|
|
- `send_dm(user_id, body)` — send a direct message to a matrix user
|
|
- `send_reply(room, event_id, body)` — threaded reply to a specific
|
|
event
|
|
- `send_reaction(room, event_id, key)` — react to a message with an
|
|
emoji key
|
|
|
|
### Reading
|
|
|
|
- `read_room(room, limit?)` — recent timeline events
|
|
- `list_rooms()` — enumerate joined rooms
|
|
(`{ id, canonical_alias, name, member_count }` per room)
|
|
- `list_room_members(room)` — members of a room
|
|
|
|
### Room membership
|
|
|
|
- `invite_user(room, user_id)` — invite `@user:server` into a room
|
|
you're already in; you must have a high enough power level.
|
|
The invitee sees a pending invite and accepts via `join_room`.
|
|
- `join_room(room)` — join a room by id or alias, or accept a
|
|
pending invite.
|
|
- `list_invites()` — rooms this agent has been invited to but not
|
|
yet joined (`{ id, canonical_alias, name }` per room).
|
|
|
|
### Receipts
|
|
|
|
- `mark_read(room, event_id)` — advance the read receipt
|
|
|
|
## Architecture
|
|
|
|
The daemon (`hive-matrix-daemon`) holds the long-running matrix-sdk
|
|
`Client` + sync loop; the stdio bridge (`hive-matrix-mcp`) is spawned
|
|
per turn and forwards tool calls over `/run/hive-matrix.sock`. Both
|
|
silently exit when `<state>/matrix-token` is absent (account not yet
|
|
provisioned).
|
|
|
|
Incoming room events wake the agent via `AgentRequest::Wake` with
|
|
`from: "matrix"`. The wake body format depends on the unread state:
|
|
|
|
- **Single room, one message**: `[matrix] <sender> in <room>: <body> —
|
|
use read_room to view, mark_read to clear`
|
|
- **Single room, multiple messages**: `[matrix] N unread in <room> —
|
|
use read_room to view, mark_read to clear`
|
|
- **Multiple rooms**: `[matrix] unread messages:` followed by a
|
|
bulleted list (`- <room>: <sender>: <body>` or `- <room>: N unread`
|
|
per room)
|
|
|
|
The same per-room breakdown is included in the `UnreadMatrix` entry
|
|
returned by `get_loose_ends` so unread rooms surface in the
|
|
loose-ends list between turns.
|
|
|
|
See [`docs/matrix.md`](../matrix.md) for the homeserver setup,
|
|
provisioning flow, and federation config.
|
|
|
|
## Extra MCP servers (per-agent)
|
|
|
|
Each agent's NixOS config can declare additional MCP servers via
|
|
`hyperhive.extraMcpServers.<key> = { command, args, env,
|
|
allowedTools }`. The module writes the map to
|
|
`/etc/hyperhive/extra-mcp.json`; the harness reads it at boot and
|
|
merges every entry into `--mcp-config` (under `mcpServers.<key>`)
|
|
and `--allowedTools` (as `mcp__<key>__<pattern>`).
|
|
|
|
The agent's `flake.nix` forwards every flake input to `agent.nix` as
|
|
the `flakeInputs` module arg, so external MCP-server flakes are pulled
|
|
in by adding them to `inputs.*` and referenced as
|
|
`flakeInputs.<name>.packages.${pkgs.system}.default` — the resolved
|
|
sha lands in the agent's own `flake.lock` and rolls up to meta's.
|
|
|
|
`allowedTools` defaults to `["*"]`, which expands to
|
|
`mcp__<key>__*` (every tool from that server auto-approved). Restrict
|
|
to specific tool names when you want finer control.
|