From d7399948864c6e71ebad2a8bbcf13751827a0588 Mon Sep 17 00:00:00 2001 From: Thomas Petersen Date: Thu, 9 Apr 2026 15:06:16 +0200 Subject: [PATCH] docs: clarify parent_event_id threading contract --- README.md | 2 ++ docs/mcp-threading.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 docs/mcp-threading.md diff --git a/README.md b/README.md index eff96927d..ff60dd63e 100644 --- a/README.md +++ b/README.md @@ -259,6 +259,8 @@ Copy `.env.example` to `.env` and adjust as needed. All defaults work out of the ## MCP Tools +Threading behavior for `parent_event_id` is documented in [`docs/mcp-threading.md`](docs/mcp-threading.md). + The `sprout-mcp` server exposes tools over stdio, organized into toolsets: `default` (25 tools active out of the box), `channel_admin`, `dms`, `canvas`, `workflow_admin`, `identity`, and `forums`. Set `SPROUT_TOOLSETS=all` to enable every tool. Agents discover available tools diff --git a/docs/mcp-threading.md b/docs/mcp-threading.md new file mode 100644 index 000000000..896ab90d8 --- /dev/null +++ b/docs/mcp-threading.md @@ -0,0 +1,29 @@ +# MCP threading (`parent_event_id`) contract + +This document describes how Sprout interprets `parent_event_id` for the MCP tools: + +- `send_message` +- `send_diff_message` + +## Overview + +`parent_event_id` is a *threading hint*. + +Sprout will attempt to post the new event as a reply in the same thread as the parent. If Sprout +cannot establish a valid NIP-10 thread context from the parent, the hint is ignored and the message +is posted as a top-level channel message. + +## Stream messages and diffs (channel timeline) + +For `send_message` / `send_diff_message` messages posted to a channel timeline, `parent_event_id` is +only honored if the **parent event already contains NIP-10 `e` tags with a `root` or `reply` marker**. + +If the parent event does **not** include NIP-10 `e` tags marked `root`/`reply`, Sprout ignores +`parent_event_id` and posts the message as a new top-level event. + +## Forums (kind `45003` comments) + +Forum comment behavior is unchanged. + +When posting a forum comment (kind `45003`), `parent_event_id` continues to behave as the required +identifier of the post/comment being replied to.