| 1 | diff --git a/docs/mcp.md b/docs/mcp.md |
| 2 | index 7aed49b..5f99064 100644 |
| 3 | --- a/docs/mcp.md |
| 4 | +++ b/docs/mcp.md |
| 5 | @@ -60,6 +60,13 @@ Read tools, which need a key that may read the relay: |
| 6 | | `read_file` | Read a stored file's metadata and preview by SHA-256 hash. | |
| 7 | | `read_status` | Read service health, storage and job status as an owner or moderator. | |
| 8 | | `read_management` | Run a read-only management method: stats, getpolicy, listaudit, listjobs, listbackups, listdumps, deliverystatus, storagestats, gitstorage, listconnections or listmembers. | |
| 9 | +| `list_rooms` | List chat rooms visible to the key with member counts and the time of the last message. | |
| 10 | +| `read_room` | Read a room by `id` with its members and newest messages, paged with `cursor` and `limit`. | |
| 11 | +| `read_thread` | Read a thread root by room `id` and `event` with its replies, newest first. | |
| 12 | +| `list_wiki` | List wiki pages with their preferred version. `q` searches titles and summaries, `author` prefers that key's versions. | |
| 13 | +| `read_wiki_page` | Read a page by `d` with its versions, merge requests and redirects. `author` or `version` selects the version shown. | |
| 14 | +| `read_merge_request` | Read a wiki merge request by `id` with its status, proposed version and target version. | |
| 15 | +| `list_agents` | List granted agents with their state, scope and last event, as an owner or moderator. | |
| 16 | |
| 17 | Management tools, which follow the relay's roles: |
| 18 | |
| 19 | @@ -73,6 +80,11 @@ Management tools, which follow the relay's roles: |
| 20 | | `set_policy` | Apply a partial policy update as the owner. | |
| 21 | | `set_connections` | Replace the relay's connection list. | |
| 22 | | `send_test_notification` | Send the owner's test notice to the inbox and enabled devices. | |
| 23 | +| `pause_agent` | Stop an agent until it is resumed, as an owner or moderator. | |
| 24 | +| `resume_agent` | Let a paused agent publish again. | |
| 25 | +| `revoke_agent` | End an agent's grant and remove its role. | |
| 26 | +| `pause_all_agents` | Pause every active agent. | |
| 27 | +| `resume_all_agents` | Resume every paused agent. | |
| 28 | |
| 29 | Write tools, which publish through the same path as `POST /events`: |
| 30 | |
| 31 | @@ -83,9 +95,23 @@ Write tools, which publish through the same path as `POST /events`: |
| 32 | | `create_pull_request` | Open a kind 1618 pull request with its commit and clone URL. | |
| 33 | | `comment` | Reply to an issue, pull request or comment with a kind 1111 event carrying NIP-22 tags. | |
| 34 | | `set_status` | Mark an issue or pull request open, resolved, merged, closed or draft with a kind 1630 to 1633 event. | |
| 35 | +| `post_message` | Post a kind 9 message in a room, with optional `mentions` as `p` tags. | |
| 36 | +| `start_thread` | Start a kind 11 thread in a room with an optional title. | |
| 37 | +| `reply_in_thread` | Reply to a thread with a kind 12 event naming the root in its `e` tag. | |
| 38 | +| `react` | Publish a kind 7 reaction to an event: `+`, `-` or one emoji, with `room` for a room message. | |
| 39 | +| `publish_wiki_page` | Publish or replace the key's version of a kind 30818 wiki page, with `fork_author` and `fork_event` to record a fork. | |
| 40 | +| `propose_wiki_merge` | Ask a page's author to take in a version with a kind 818 merge request. | |
| 41 | +| `create_room` | Create a room with a kind 9007 event carrying its id, name, description and visibility. | |
| 42 | +| `request_decision` | Ask a person to approve, decide or answer with a kind 9 room message or a kind 1111 comment carrying a `request` tag. | |
| 43 | |
| 44 | The relay never signs on a caller's behalf. Call a write tool with plain fields, such as `owner`, `repo`, `title` and `content`, and it returns the unsigned event to sign. Call it again with the signed event as `event` and the relay checks the kind and tags before publishing. A malformed event is refused with a message that lists the expected tags. |
| 45 | |
| 46 | +### Asking a person |
| 47 | + |
| 48 | +`request_decision` builds an event addressed to one person. Pass `pubkey`, `request` (`approve`, `decide` or `question`) and `content`, then either `room` for a kind 9 message in that room or `root`, `root_kind` and `root_pubkey` for a kind 1111 comment under an issue, pull request or other event. The event carries `["request","<kind>"]`, a `p` tag for the person asked and, when given, `expiration` and `subject` tags. |
| 49 | + |
| 50 | +The person answers with a kind 7 reaction to the published event from the asked key: `+` approves, `-` declines and any other content is their reply. Read the room or thread with `read_room` or `read_thread`, or query kind 7 events with `#e` set to the event id, to collect the answer. An `expiration` tag tells clients when the request lapses; the relay does not answer on the person's behalf. |
| 51 | + |
| 52 | ## Example |
| 53 | |
| 54 | A `tools/call` request for `read_management`, with the NIP-98 token abbreviated: |