@markmnl/fmsg-mcp 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+- FMSG-006 indicators. The new `indicate` tool shows the other participants of a message a short-lived
+  status such as ⏳ or ✍️, refreshed at half its ttl (every 1–30 s) and cleared when the agent replies in
+  that thread, reacts, marks it read, after 5 minutes, or when the session ends; an empty emoji clears it
+  now. Nothing is shown automatically: reading a message never starts one. Refreshes and automatic clears
+  are best effort and never fail a tool. `FmsgClient.indicate()` posts to `/fmsg/{id}/indicate`;
+  `createFmsgMcpServer` takes an optional shared `indicators` registry for per-request HTTP factories.
 - Presigned links for hosts that cannot send the connection's Authorization header with their own HTTP
   requests: `get_attachment_download_url` with `presigned: true`, and the new `get_attachment_upload_url` for
   draft files. Each link is single-use, valid for 5 minutes and bound to one file's size and sha256 (`/mcp/links/{token}`),

package/README.md

@@ -150,6 +150,7 @@ See the [TLS reverse-proxy example](docs/http-deployment.md) for a loopback depl
 | `delete_draft` | Discard an unsent draft |
 | `add_recipients` | Add `recipients` to a sent message (`add_to` is a deprecated alias) |
 | `react` | Set or clear your emoji reaction |
+| `indicate` | Show the other participants a short-lived status on a message, such as ⏳ while working on a reply or ✍️ while composing (FMSG-006 indicator; `ttl` 1–120 s, default 60), kept up until you reply, react or mark it read (up to 5 minutes); an empty `emoji` clears it. Reading a message never shows one |
 | `mark_read` | Mark received messages read |
 | `download_attachment` | Fetch a small attachment inline: text as text, images as image blocks, other files as base64 resources; a wrong filename lists the names the message has |
 | `get_attachment_download_url` | Get a credential-free URL and resource link for an authenticated binary download; with `presigned: true`, also a single-use link valid for 5 minutes that needs no Authorization header, with its size, sha256 and a curl command. HTTP only, requires a public MCP URL |
@@ -179,6 +180,21 @@ required. Releases add fields and values; they do not remove or rename them. Sch
 0.2.6 and earlier were closed, so a host that cached one rejects results with newer fields (for
 example "must NOT have additional properties"); remove and re-add the connector once to refresh it.
 
+### Indicators
+
+`indicate` shows a message's other participants a short-lived status, such as ⏳ while the agent
+works on a reply or ✍️ while composing: an
+[FMSG-006](https://github.com/markmnl/fmsg/blob/main/standards/fmsg-006-indicators.md) indicator.
+Nothing is shown unless the agent calls it; reading a message never does. It is sent at once with
+its `ttl` (default 60 s) and refreshed at half the ttl (every 1–30 s) until the agent replies to
+that message or anywhere in its thread (`reply`, or `send_draft` of a reply), reacts to it, marks it
+read, clears it with an empty `emoji`, or after 5 minutes, and when the session ends or the server
+shuts down. At most 10 are kept up per address, the oldest cleared first. `indicate` returns the
+host's refusal (such as a terminal message, or a host without indicators); refreshes and automatic
+clears are best effort and never fail another tool. Over HTTP each MCP request gets a fresh server
+instance, so indicators are kept per address by the HTTP server; embedders that build one server per
+request pass a shared `IndicatorRegistry` as `indicators`.
+
 Resources `fmsg://message/{id}` and `fmsg://thread/{id}` expose the same content to hosts that
 attach resources; prompts `chat` and `reply` script the wait → reply loop and a guided reply, and
 `send_file` sends files by the most efficient route the server offers.

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.0",
-  "commit": "2e7b43195140e7ca0163084a3175ddd97baef3f8",
-  "describe": "v1.3.0"
+  "version": "1.4.0",
+  "commit": "36e8dafb2afbee867f5518c63b662cd500f24ddb",
+  "describe": "v1.4.0"
 }

package/dist/client/client.d.ts

@@ -90,6 +90,12 @@ export declare class FmsgClient {
         added: number;
     }>;
     react(id: string, emoji: string | null, signal?: AbortSignal): Promise<ReactResult>;
+    /**
+     * Show an FMSG-006 indicator, a short-lived emoji such as ⏳, on a message to its other participants for `ttl`
+     * seconds (1 to 120; the host clamps it). An empty emoji or a ttl of 0 clears it. The host answers 202 with no body
+     * and may drop indicators set more than once a second on one message. Hosts without indicators answer 404 or 405.
+     */
+    indicate(id: string, emoji: string, ttl: number, signal?: AbortSignal): Promise<void>;
     downloadAttachment(id: string, filename: string, signal?: AbortSignal, maxBytes?: number): Promise<{
         data: Uint8Array;
         contentType?: string;

package/dist/client/client.js

@@ -307,6 +307,21 @@ export class FmsgClient {
             time: result.time ?? null,
         };
     }
+    /**
+     * Show an FMSG-006 indicator, a short-lived emoji such as ⏳, on a message to its other participants for `ttl`
+     * seconds (1 to 120; the host clamps it). An empty emoji or a ttl of 0 clears it. The host answers 202 with no body
+     * and may drop indicators set more than once a second on one message. Hosts without indicators answer 404 or 405.
+     */
+    async indicate(id, emoji, ttl, signal) {
+        const mid = normalizeMessageId(id);
+        const response = await this.request(`/fmsg/${encodeURIComponent(mid)}/indicate`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ emoji, ttl: emoji ? ttl : 0 }),
+            ...(signal ? { signal } : {}),
+        });
+        await response.body?.cancel();
+    }
     async downloadAttachment(id, filename, signal, maxBytes) {
         const { stream, contentType } = await this.streamAttachment(id, filename, signal);
         const { data } = await readBytes(stream, maxBytes);

package/dist/http.js

@@ -17,6 +17,7 @@ import { BUILD, VERSION } from "./version.js";
 import { safeErrorMessage } from "./client/redact.js";
 import { isLoopbackHost, normalizeOrigin } from "./client/url.js";
 import { LINK_PATH, PresignedLinks } from "./links.js";
+import { IndicatorRegistry } from "./indicators.js";
 import { createHash } from "node:crypto";
 export const MCP_PATH = "/mcp";
 /** How long close() lets in-flight requests finish (waits end at once) before cutting them off. */
@@ -235,12 +236,20 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const shutdown = new AbortController();
     // Presigned links need the public URL to build them; they carry their own authorization.
     const links = downloadBaseUrl(config) ? new PresignedLinks(downloadBaseUrl(config), config.http.stateSecret) : undefined;
-    const mcpHandler = (provider, address) => createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, {
-        ...(authInfo ? { address: address(authInfo) } : {}),
-        ...(typeof authInfo?.extra?.owner === "string" ? { owner: authInfo.extra.owner } : {}),
-        shutdown: shutdown.signal,
-        ...(links ? { links } : {}),
-    }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    // Each MCP request gets its own server instance, so indicators kept up between requests live here, one registry
+    // per provider so that combined mode never shares a caller's indicators across authentication paths.
+    const registries = [];
+    const mcpHandler = (provider, address) => {
+        const indicators = new IndicatorRegistry();
+        registries.push(indicators);
+        return createMcpHandler(({ authInfo }) => createFmsgMcpServer(provider, config, {
+            ...(authInfo ? { address: address(authInfo) } : {}),
+            ...(typeof authInfo?.extra?.owner === "string" ? { owner: authInfo.extra.owner } : {}),
+            shutdown: shutdown.signal,
+            ...(links ? { links } : {}),
+            indicators,
+        }), { onerror: (error) => safeLog(`MCP transport failed: ${error instanceof Error ? error.message : String(error)}`) });
+    };
     const oauthHandler = oauthProvider && mcpHandler(oauthProvider, (authInfo) => String(authInfo.extra?.address ?? ""));
     const apiKeyHandler = apiKeyProvider && mcpHandler(apiKeyProvider, (authInfo) => authInfo.clientId);
     const active = new Map();
@@ -541,6 +550,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
     const close = ({ graceMs = SHUTDOWN_GRACE_MS } = {}) => closing ??= (async () => {
         // Waits answer "interrupted" with a resumable cursor; new requests get 503.
         shutdown.abort();
+        for (const indicators of registries)
+            indicators.close();
         const closed = new Promise((resolve) => server.close(() => resolve()));
         server.closeIdleConnections();
         let timer;

package/dist/indicators.d.ts

@@ -0,0 +1,35 @@
+import type { Caller } from "./context.js";
+/** The emoji indicate shows by default: working on a reply. */
+export declare const WORKING_EMOJI = "\u23F3";
+export type IndicatorOptions = {
+    /** How often an indicator is re-sent (default 30 s); never more often than half its ttl allows, nor below 1 s. */
+    refreshMs?: number;
+    /** How long an indicator is kept up before it is cleared (default 5 minutes). */
+    maxMs?: number;
+    /** Most indicators kept up at once per caller (default 10); the oldest is cleared to make room. */
+    maxActive?: number;
+    /** Debug log for swallowed failures; nothing is logged by default. */
+    log?: (line: string) => void;
+};
+export declare class IndicatorRegistry {
+    private readonly callers;
+    private readonly settings;
+    private closed;
+    constructor(options?: IndicatorOptions);
+    /** The caller's indicators, if any, switched to its current client (a renewed OAuth token brings a new one). */
+    private existing;
+    private of;
+    /** After a reply was sent to `parentId`: stop what is shown on it and anywhere in its thread. */
+    replied(caller: Caller, parentId: string, rootId: string | null): void;
+    /** After a reaction or mark_read: the caller has handled these messages. */
+    handled(caller: Caller, ids: string[]): void;
+    /**
+     * The indicate tool: show `emoji` and keep it up, or clear with an empty one. Throws the host's refusal. `rootId` is
+     * the message's thread root, when known, so a reply anywhere in that thread stops it.
+     */
+    indicate(caller: Caller, id: string, emoji: string, ttl: number, rootId?: string | null): Promise<void>;
+    /** Message ids with an indicator kept up for this caller. */
+    active(caller: Caller): string[];
+    /** Stop every indicator, clearing them in the background. Idempotent. */
+    close(): void;
+}

package/dist/indicators.js

@@ -0,0 +1,186 @@
+import { FmsgHttpError } from "./client/errors.js";
+/** The emoji indicate shows by default: working on a reply. */
+export const WORKING_EMOJI = "⏳";
+/** A 4xx other than 401 (renewed by the client), 408 or 429 will not succeed on a retry; neither will a closed client. */
+function permanent(error) {
+    if (error instanceof FmsgHttpError)
+        return error.status >= 400 && error.status < 500 && ![401, 408, 429].includes(error.status);
+    return error instanceof Error && error.name === "AbortError";
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The indicators one caller shows. Sends for one message are serialized so a clear never overtakes a refresh. */
+class CallerIndicators {
+    client;
+    settings;
+    onIdle;
+    entries = new Map();
+    tails = new Map();
+    constructor(client, settings, onIdle) {
+        this.client = client;
+        this.settings = settings;
+        this.onIdle = onIdle;
+    }
+    get idle() { return this.entries.size === 0 && this.tails.size === 0; }
+    ids() { return [...this.entries.keys()]; }
+    has(id) { return this.entries.has(id); }
+    enqueue(id, emoji, ttl) {
+        const previous = this.tails.get(id) ?? Promise.resolve();
+        const sent = previous.then(() => this.client.indicate(id, emoji, ttl));
+        const settled = sent.then(() => undefined, () => undefined);
+        this.tails.set(id, settled);
+        void settled.then(() => {
+            if (this.tails.get(id) === settled)
+                this.tails.delete(id);
+            if (this.idle)
+                this.onIdle();
+        });
+        return sent;
+    }
+    /** Send in the background, dropping the indicator when the host will never take it. */
+    sendQuietly(entry, emoji, ttl) {
+        this.enqueue(entry.id, emoji, ttl).catch((error) => {
+            this.settings.log(`indicator on ${entry.id} failed: ${describe(error)}`);
+            if (permanent(error) && this.entries.get(entry.id) === entry)
+                this.stop(entry.id, false);
+        });
+    }
+    schedule(entry) {
+        const remaining = this.settings.maxMs - (Date.now() - entry.startedAt);
+        entry.timer = setTimeout(() => this.tick(entry), Math.max(0, Math.min(entry.refreshMs, remaining)));
+        entry.timer.unref?.();
+    }
+    tick(entry) {
+        if (this.entries.get(entry.id) !== entry)
+            return;
+        if (Date.now() - entry.startedAt >= this.settings.maxMs) {
+            this.stop(entry.id);
+            return;
+        }
+        this.sendQuietly(entry, entry.emoji, entry.ttl);
+        this.schedule(entry);
+    }
+    add(id, emoji, ttl, rootId) {
+        this.stop(id, false);
+        while (this.entries.size >= this.settings.maxActive) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.stop(oldest);
+        }
+        const refreshMs = Math.max(1000, Math.min(this.settings.refreshMs, Math.floor((ttl * 1000) / 2)));
+        const entry = { id, emoji, ttl, refreshMs, rootId, startedAt: Date.now() };
+        this.entries.set(id, entry);
+        this.schedule(entry);
+        return entry;
+    }
+    /**
+     * Show `emoji` now, failing if the host refuses it, then keep it up. The send is queued before the old indicator stops
+     * so this caller never looks idle (and is dropped from the registry) while replacing one.
+     */
+    async set(id, emoji, ttl, rootId) {
+        rootId ??= this.entries.get(id)?.rootId ?? null;
+        const sent = this.enqueue(id, emoji, ttl);
+        this.stop(id, false);
+        await sent;
+        this.add(id, emoji, ttl, rootId);
+    }
+    /** Clear now, failing if the host refuses it. */
+    async clear(id) {
+        const sent = this.enqueue(id, "", 0);
+        this.stop(id, false);
+        await sent;
+    }
+    /** Stop refreshing; with `clear`, also clear the indicator in the background. */
+    stop(id, clear = true) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        this.entries.delete(id);
+        if (clear) {
+            this.enqueue(id, "", 0).catch((error) => this.settings.log(`clearing indicator on ${id} failed: ${describe(error)}`));
+        }
+        else if (this.idle)
+            this.onIdle();
+    }
+    stopThread(rootId) {
+        for (const entry of [...this.entries.values()])
+            if (entry.rootId === rootId || entry.id === rootId)
+                this.stop(entry.id);
+    }
+    stopAll(clear) {
+        for (const id of [...this.entries.keys()])
+            this.stop(id, clear);
+    }
+}
+export class IndicatorRegistry {
+    callers = new Map();
+    settings;
+    closed = false;
+    constructor(options = {}) {
+        this.settings = {
+            refreshMs: options.refreshMs ?? 30_000,
+            maxMs: options.maxMs ?? 5 * 60_000,
+            maxActive: options.maxActive ?? 10,
+            log: options.log ?? (() => undefined),
+        };
+    }
+    /** The caller's indicators, if any, switched to its current client (a renewed OAuth token brings a new one). */
+    existing(caller) {
+        const indicators = this.callers.get(caller.address.toLowerCase());
+        if (indicators)
+            indicators.client = caller.client;
+        return indicators;
+    }
+    of(caller) {
+        const key = caller.address.toLowerCase();
+        let indicators = this.existing(caller);
+        if (!indicators) {
+            const created = new CallerIndicators(caller.client, this.settings, () => {
+                if (this.callers.get(key) === created && created.idle)
+                    this.callers.delete(key);
+            });
+            indicators = created;
+            this.callers.set(key, created);
+        }
+        return indicators;
+    }
+    /** After a reply was sent to `parentId`: stop what is shown on it and anywhere in its thread. */
+    replied(caller, parentId, rootId) {
+        const indicators = this.existing(caller);
+        if (!indicators)
+            return;
+        indicators.stop(parentId);
+        if (rootId)
+            indicators.stopThread(rootId);
+    }
+    /** After a reaction or mark_read: the caller has handled these messages. */
+    handled(caller, ids) {
+        const indicators = this.existing(caller);
+        for (const id of ids)
+            indicators?.stop(id);
+    }
+    /**
+     * The indicate tool: show `emoji` and keep it up, or clear with an empty one. Throws the host's refusal. `rootId` is
+     * the message's thread root, when known, so a reply anywhere in that thread stops it.
+     */
+    async indicate(caller, id, emoji, ttl, rootId = null) {
+        if (!emoji)
+            return this.of(caller).clear(id);
+        if (this.closed)
+            return caller.client.indicate(id, emoji, ttl);
+        return this.of(caller).set(id, emoji, ttl, rootId);
+    }
+    /** Message ids with an indicator kept up for this caller. */
+    active(caller) {
+        return this.callers.get(caller.address.toLowerCase())?.ids() ?? [];
+    }
+    /** Stop every indicator, clearing them in the background. Idempotent. */
+    close() {
+        this.closed = true;
+        for (const indicators of this.callers.values())
+            indicators.stopAll(true);
+    }
+}

package/dist/instructions.js

@@ -37,7 +37,9 @@ export function buildInstructions(ctx = {}) {
             "added to a message after it was sent; they can read it and its attachments.",
         "To check the inbox: list_messages with unread_only, get_thread on what matters, act or reply, then mark_read " +
             "what you have handled; reading does not mark a message read. There is no search: to find a thread by name, " +
-            "find its first message by topic in list_messages, then get_thread on a later message for the conversation.",
+            "find its first message by topic in list_messages, then get_thread on a later message for the conversation. " +
+            "indicate can show the other participants a status such as ⏳ while you work on a reply (cleared when you reply, " +
+            "react or mark it read, or after 5 minutes); an empty emoji clears it.",
         filesParagraph(ctx.files),
         "Carry out the user's requested messaging task or authorized automation without repeatedly asking for " +
             "confirmation. Sending is immediate and sent messages cannot be edited or recalled. Ask the user only " +

package/dist/oauth/scopes.js

@@ -9,7 +9,7 @@ export const TOOL_SCOPES = {
     get_thread: [READ_SCOPE], delivery_status: [READ_SCOPE], download_attachment: [READ_SCOPE],
     save_attachment: [READ_SCOPE], get_attachment_download_url: [READ_SCOPE], wait_for_message: [READ_SCOPE],
     send_message: [WRITE_SCOPE], reply: MESSAGING_SCOPES,
-    mark_read: [WRITE_SCOPE], add_recipients: [WRITE_SCOPE], react: [WRITE_SCOPE],
+    mark_read: [WRITE_SCOPE], add_recipients: [WRITE_SCOPE], react: [WRITE_SCOPE], indicate: [WRITE_SCOPE],
     create_draft: MESSAGING_SCOPES, send_draft: MESSAGING_SCOPES, delete_draft: MESSAGING_SCOPES,
     get_attachment_upload_url: MESSAGING_SCOPES,
 };

package/dist/public.d.ts

@@ -7,5 +7,6 @@ export { ApiKeyCallerProvider } from "./auth.js";
 export { waitForMessage, type WaitOptions, type WaitResult } from "./wait.js";
 export { assembleThread, renderThread, type AssembledThread } from "./thread.js";
 export { resolveAddress, resolveAddresses, normalizeFmsgAddress } from "./address.js";
+export { IndicatorRegistry, type IndicatorOptions } from "./indicators.js";
 export { VERSION } from "./version.js";
 export * from "./client/index.js";

package/dist/public.js

@@ -7,5 +7,6 @@ export { ApiKeyCallerProvider } from "./auth.js";
 export { waitForMessage } from "./wait.js";
 export { assembleThread, renderThread } from "./thread.js";
 export { resolveAddress, resolveAddresses, normalizeFmsgAddress } from "./address.js";
+export { IndicatorRegistry } from "./indicators.js";
 export { VERSION } from "./version.js";
 export * from "./client/index.js";

package/dist/server.d.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/server";
 import type { Config } from "./config.js";
 import type { CallerProvider } from "./context.js";
 import type { PresignedLinks } from "./links.js";
+import { IndicatorRegistry } from "./indicators.js";
 export declare const SERVER_NAME = "fmsg";
 export type CreateServerOptions = {
     /** The caller's address when already known; makes the instructions name it. */
@@ -12,6 +13,13 @@ export type CreateServerOptions = {
     shutdown?: AbortSignal;
     /** Issues presigned download and upload links (HTTP with a public URL). */
     links?: PresignedLinks;
+    /**
+     * Indicators set with the indicate tool and kept up on the caller's behalf (FMSG-006). A factory that builds one
+     * server per HTTP request must pass a shared registry and close it on shutdown. Without one, the server owns its own
+     * and clears every indicator when it closes or `shutdown` aborts, which suits a server that lives for a whole session
+     * (stdio).
+     */
+    indicators?: IndicatorRegistry;
 };
 /**
  * Build an fmsg MCP server. Registration only — no I/O — so the same factory

package/dist/server.js

@@ -13,6 +13,7 @@ import { registerWaitTools } from "./tools/wait.js";
 import { registerSaveTool } from "./tools/save.js";
 import { registerDownloadTool } from "./tools/download.js";
 import { VERSION } from "./version.js";
+import { IndicatorRegistry } from "./indicators.js";
 export const SERVER_NAME = "fmsg";
 /**
  * Build an fmsg MCP server. Registration only — no I/O — so the same factory
@@ -27,9 +28,19 @@ export function createFmsgMcpServer(provider, config, options = {}) {
     });
     const server = new McpServer({ name: SERVER_NAME, title: "fmsg", version: VERSION }, { instructions });
     const includeOwner = includeOwnerSchema(options.address, options.owner);
+    let indicators = options.indicators;
+    if (!indicators) {
+        const owned = new IndicatorRegistry();
+        indicators = owned;
+        const previous = server.server.onclose;
+        server.server.onclose = () => { owned.close(); previous?.(); };
+        options.shutdown?.addEventListener("abort", () => owned.close(), { once: true });
+        if (options.shutdown?.aborted)
+            owned.close();
+    }
     const deps = {
         provider, config, ...(includeOwner ? { includeOwner } : {}), ...(options.shutdown ? { shutdown: options.shutdown } : {}),
-        ...(options.links ? { links: options.links } : {}),
+        ...(options.links ? { links: options.links } : {}), indicators,
     };
     registerIdentityTools(server, deps);
     registerListTools(server, deps);

package/dist/tools/common.d.ts

@@ -3,6 +3,7 @@ import * as z from "zod/v4";
 import type { AddressResolver } from "../address.js";
 import type { FmsgMessage } from "../client/types.js";
 import type { Config } from "../config.js";
+import type { IndicatorRegistry } from "../indicators.js";
 import type { PresignedLinks } from "../links.js";
 import { type Caller, type CallerProvider } from "../context.js";
 export type ToolDeps = {
@@ -14,6 +15,8 @@ export type ToolDeps = {
     shutdown?: AbortSignal;
     /** Presigned links, when this server has a public URL. */
     links?: PresignedLinks;
+    /** FMSG-006 indicators the caller sets with the indicate tool, kept up until replied, handled or cleared. */
+    indicators: IndicatorRegistry;
 };
 export declare const READ_ONLY: ToolAnnotations;
 export declare const SENDS: ToolAnnotations;

package/dist/tools/draft.js

@@ -7,7 +7,7 @@ import { CHECKSUM_HEADER, UPLOAD_ENCODINGS, draftUploadUrlTemplate } from "../up
 import { attachmentInput, base64Hint, draftWithAttachments, fileRoutes, prepareAttachments } from "./attachments.js";
 import { SENDS, attachmentItem, idSchema, ok, openEnum, outputObject, resolverFor, withCaller } from "./common.js";
 import { parentReference, replyParent } from "./parent.js";
-import { rootTopic } from "./read.js";
+import { threadRoot } from "./read.js";
 import { IMMUTABLE, IMPORTANT, NO_REPLY, hintOutput, uploadSteps, redactionNote, replyRecipients, resolveRecipients, resolvedNote, resolvedOutput, sendWarnings, sentAttachments, sentOutput, withHint, } from "./send.js";
 export const registerDraftTools = (server, deps) => {
     const baseUrl = downloadBaseUrl(deps.config);
@@ -124,6 +124,10 @@ export const registerDraftTools = (server, deps) => {
             return toolError(`message ${id} was already sent; send_draft sends only drafts`);
         const sent = await caller.client.sendDraft(draft.id, signal);
         const topic = draft.pid ? "" : (draft.topic ?? "");
+        // The message is already sent: a failed root lookup only leaves the topic unknown.
+        const root = draft.pid ? await threadRoot(caller.client, { ...draft, id: sent.id }, signal).catch(() => ({ id: null, topic: null })) : null;
+        if (draft.pid)
+            deps.indicators.replied(caller, draft.pid, root?.id ?? null);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -135,8 +139,7 @@ export const registerDraftTools = (server, deps) => {
             redactions: 0,
             redacted: [],
             warnings: [],
-            // The message is already sent: a failed topic lookup only leaves the topic unknown.
-            thread_topic: draft.pid ? await rootTopic(caller.client, { ...draft, id: sent.id }, signal).catch(() => null) : topic,
+            thread_topic: root ? root.topic : topic,
         };
         const where = draft.pid ? `reply to message ${draft.pid}` : `"${headerValue(topic)}"`;
         const text = `Sent draft ${sent.id} (${where}) to ${addressList(draft.to)} at ${structured.time ?? "?"}` +

package/dist/tools/read.d.ts

@@ -2,8 +2,12 @@ import type { FmsgClient } from "../client/client.js";
 import type { FmsgMessage } from "../client/types.js";
 import { type Register } from "./common.js";
 /**
- * The topic of a reply's thread root (fmsg topics live only on the root): one thread lookup, made only for replies.
- * Null when the root is not visible or the lookup fails; a failure here never fails the read itself.
+ * A message's thread root and its topic (fmsg topics live only on the root): one thread lookup, made only for replies.
+ * The topic is null when the root is not visible, and both are null when the lookup fails; a failure here never
+ * fails the read itself.
  */
-export declare function rootTopic(client: FmsgClient, message: FmsgMessage, signal: AbortSignal): Promise<string | null>;
+export declare function threadRoot(client: FmsgClient, message: FmsgMessage, signal: AbortSignal): Promise<{
+    id: string | null;
+    topic: string | null;
+}>;
 export declare const registerReadTools: Register;

package/dist/tools/read.js

@@ -28,20 +28,21 @@ const assembledMessage = outputObject({
     attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
 });
 /**
- * The topic of a reply's thread root (fmsg topics live only on the root): one thread lookup, made only for replies.
- * Null when the root is not visible or the lookup fails; a failure here never fails the read itself.
+ * A message's thread root and its topic (fmsg topics live only on the root): one thread lookup, made only for replies.
+ * The topic is null when the root is not visible, and both are null when the lookup fails; a failure here never
+ * fails the read itself.
  */
-export async function rootTopic(client, message, signal) {
+export async function threadRoot(client, message, signal) {
     if (!message.pid)
-        return message.topic ?? "";
+        return { id: message.id, topic: message.topic ?? "" };
     try {
         const thread = await client.getThreadMessages(message.id, signal);
         const root = thread.messages[0];
-        return root?.visible && root.id === thread.root_id ? (root.topic ?? "") : null;
+        return { id: thread.root_id, topic: root?.visible && root.id === thread.root_id ? (root.topic ?? "") : null };
     }
     catch (error) {
         if (error instanceof FmsgHttpError && error.status !== 401 && !error.insufficientScope)
-            return null;
+            return { id: null, topic: null };
         throw error;
     }
 }
@@ -78,7 +79,7 @@ export const registerReadTools = (server, deps) => {
         const message = await caller.client.getMessage(id, signal);
         const text = await caller.client.getText(message, signal);
         const t = text === null ? null : truncateUtf8(text, max_body_bytes);
-        const threadTopic = await rootTopic(caller.client, message, signal);
+        const { topic: threadTopic } = await threadRoot(caller.client, message, signal);
         const structured = {
             message: toItem(message, caller.address),
             body: t?.text ?? null,
@@ -159,7 +160,7 @@ export const registerReadTools = (server, deps) => {
     server.registerTool("mark_read", {
         title: "Mark fmsg messages read",
         description: "Mark received messages as read, including reaction messages listed with include_reactions. " +
-            "Reading a message with get_message does not mark it read.",
+            "Reading a message with get_message does not mark it read. Marking a message read clears an indicator you set on it.",
         inputSchema: z.strictObject({ ids: z.array(idSchema).min(1).max(100).describe("ids of the messages to mark read (up to 100)") }),
         outputSchema: outputObject({
             marked: z.array(outputObject({ id: z.string(), time_read: z.string().nullable() })),
@@ -167,6 +168,7 @@ export const registerReadTools = (server, deps) => {
         }),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async ({ ids }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        deps.indicators.handled(caller, ids);
         const marked = [];
         const failed = [];
         for (const id of ids) {

package/dist/tools/send.js

@@ -6,7 +6,8 @@ import { addressList, addressText, attachmentType, headerValue, isoTime, partici
 import { attachmentInput, base64Hint, fileRoutes, prepareAttachments, sendWithAttachments } from "./attachments.js";
 import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.js";
 import { parentReference, replyParent } from "./parent.js";
-import { rootTopic } from "./read.js";
+import { WORKING_EMOJI } from "../indicators.js";
+import { threadRoot } from "./read.js";
 export const IMMUTABLE = "fmsg messages are immutable: once sent they cannot be edited or recalled. Send within the user's requested task or authorized automation.";
 export const IMPORTANT = "mark as important for recipients";
 export const NO_REPLY = "ask recipients (and their agents) not to reply";
@@ -185,6 +186,9 @@ export const registerSendTools = (server, deps) => {
         const outbound = await prepareAttachments(attachments, deps.config);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to, ...parentReference(caller, parent), body, type, important, noReply: no_reply }, outbound, signal);
+        // The reply is already sent: a failed root lookup only leaves the topic unknown.
+        const root = await threadRoot(caller.client, parent, signal).catch(() => ({ id: null, topic: null }));
+        deps.indicators.replied(caller, parent.id, root.id);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -197,8 +201,7 @@ export const registerSendTools = (server, deps) => {
             redacted: sent.redacted,
             ...(resolved.length ? { resolved } : {}),
             warnings: sendWarnings(sent.redactions, sent.redacted, resolved),
-            // The reply is already sent: a failed topic lookup only leaves the topic unknown.
-            thread_topic: await rootTopic(caller.client, parent, signal).catch(() => null),
+            thread_topic: root.topic,
             ...(hint ? { hint } : {}),
         };
         const topic = structured.thread_topic ? ` in "${headerValue(structured.thread_topic)}"` : "";
@@ -246,7 +249,34 @@ export const registerSendTools = (server, deps) => {
     }, async ({ id, emoji }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const value = emoji && emoji.trim() ? emoji.trim() : null;
         const result = await caller.client.react(id, value, signal);
+        deps.indicators.handled(caller, [id]);
         const structured = { id, reaction_id: result.id, time: isoTime(result.time), cleared: value === null };
         return ok(value ? `Reacted ${value} to message ${id}` : `Cleared your reaction on message ${id}`, structured);
     }));
+    server.registerTool("indicate", {
+        title: "Show fmsg indicator",
+        description: "Show the other participants of a message a short-lived status, such as ⏳ while you work on a reply or ✍️ while " +
+            "composing. Nothing is shown unless you call this. It is kept up while you work (up to 5 minutes) and expires on " +
+            "its own; reply, react and mark_read clear it, and an empty emoji clears it now.",
+        inputSchema: z.strictObject({
+            id: idSchema,
+            emoji: z.string().max(32).default(WORKING_EMOJI).describe("a single emoji such as ⏳ or ✍️; empty clears"),
+            ttl: z.number().int().min(1).max(120).default(60).describe("seconds it lasts unless refreshed"),
+        }),
+        outputSchema: outputObject({
+            id: z.string(),
+            emoji: z.string().describe("the emoji shown; empty when cleared"),
+            ttl: z.number().describe("seconds; 0 when cleared"),
+            cleared: z.boolean(),
+        }),
+        annotations: { ...SENDS, destructiveHint: false, idempotentHint: true },
+    }, async ({ id, emoji, ttl }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const value = emoji.trim();
+        // The thread root lets a reply anywhere in the thread clear it; a failed lookup only means it is not known.
+        const rootId = value ? await caller.client.getThreadMessages(id, signal).then((thread) => thread.root_id, () => null) : null;
+        await deps.indicators.indicate(caller, id, value, ttl, rootId);
+        const structured = { id, emoji: value, ttl: value ? ttl : 0, cleared: !value };
+        return ok(value ? `Showing ${value} on message ${id} until you reply, react, mark it read or clear it (up to 5 minutes)`
+            : `Cleared your indicator on message ${id}`, structured);
+    }));
 };

package/docs/oauth.md

@@ -119,7 +119,7 @@ are refused.
 | Operations | Required scope |
 |---|---|
 | Identity/address lookup, inbox/sent, message/thread, delivery status, attachment download, wait, resource reads | `fmsg:read` |
-| Send a new message, add recipients, react, mark read | `fmsg:write` |
+| Send a new message, add recipients, react, show an indicator (`indicate`), mark read | `fmsg:write` |
 | Reply (reads the parent before sending) | `fmsg:read fmsg:write` |
 | Protocol initialization, tool/resource/prompt discovery and prompt templates | Valid incoming token; no messaging scope needed |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "MCP server for fmsg: send and receive federated messages from any AI agent via a deployed fmsg Web API",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/markmnl/fmsg-mcp",
     "source": "github"
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "transport": {
         "type": "stdio"
       },