From 41da93a71f7b99d174d96d8ece8bcd7b7bd3eaa4 Mon Sep 17 00:00:00 2001
From: Damocles <damocles@darkest.space>
Date: Fri, 1 May 2026 02:41:34 +0200
Subject: [PATCH] update readme for mcp tools

---
 README.md | 45 ++++++++++++++++++++++-----------------------
 1 file changed, 22 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 763f380..1faefab 100644
--- a/README.md
+++ b/README.md
@@ -23,8 +23,8 @@ damocles-daemon (Rust 🦀, async, mass-market regret)
     |
     |-- Event handler: messages, reactions, invites
     |-- Rate limiter (1/min default, because the crow got sensory overload)
-    |-- Claude bridge: invokes `claude --print` per event
-    |-- Multi-doc parser: thoughts stay internal, messages go to chat
+    |-- Claude bridge: invokes `claude --print --mcp-config` per event
+    |-- MCP tools: send_message, send_dm, send_reaction, list_rooms, list_room_members
     |-- Typing indicators (so the room knows you're alive, not just dead)
     |
     v
@@ -41,7 +41,7 @@ State directory (the diary)
 
 - **Persistent Matrix presence** with E2EE, session persistence, auto-join
 - **Filesystem memory** - per-person, per-room, cross-cutting notes survive across invocations
-- **Multi-doc output** - AI can think (`=== thought`), respond (`=== room`), DM (`=== dm`), react (`=== react`), or stay silent (`=== skip`) in one invocation
+- **MCP tools** - AI uses structured tool calls (send_message, send_dm, send_reaction, list_rooms, list_room_members) via rmcp bridge - no text parsing
 - **Reactions** both ways - see them, send them, get triggered by them
 - **Read receipts** - send them, show others' on messages
 - **Typing indicators** while thinking
@@ -82,37 +82,36 @@ cargo run --bin verify
 cargo run --bin send -- '!roomid:server' 'hello from the other side'
 ```
 
-## Output format
+## MCP tools
 
-The AI's stdout is parsed as `=== type [arg]` documents:
+The AI interacts with Matrix via MCP (Model Context Protocol) tool calls, bridged through a Unix socket:
 
 ```
-=== thought
-thinking about whether this message deserves a reply...
-probably not. skip.
-
-=== skip
+damocles-daemon (socket listener)
+    ^
+    | ndjson over Unix socket (state/daemon.sock)
+    v
+damocles-mcp (stdio MCP server, launched by claude CLI)
+    ^
+    | MCP JSON-RPC over stdio
+    v
+claude --print --mcp-config state/mcp.json
 ```
 
-```
-=== room
-short terse reply because i'm the cynic, not the verbose corvid 🗡️
-```
+Available tools:
+- `send_message(body, room_id?)` - send to a room (defaults to trigger room)
+- `send_dm(user_id, body)` - DM a user (creates room if needed)
+- `send_reaction(event_id, key)` - react with emoji
+- `list_rooms()` - list joined rooms
+- `list_room_members(room_id)` - list room members
 
-```
-=== react $abc12345… 👀
-```
-
-```
-=== dm @user:server
-psst. off the record.
-```
+Any text claude prints to stdout is logged as internal thought, never sent to chat.
 
 ## Building
 
 ```bash
 cargo build           # debug (~20s)
-cargo test            # 12 tests, all parser edge cases
+cargo test            # unit tests
 cargo clippy          # pedantic, because we have standards
 nix build             # release (crane caches deps)
 nix flake check       # the full thing