@markmnl/fmsg-mcp 0.2.5 → 0.2.6

package/dist/tools/send.js

@@ -1,14 +1,18 @@
 import * as z from "zod/v4";
 import { resolveAddresses, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
-import { isoTime, participantsOf } from "../render.js";
-import { READ_ONLY, SENDS, idSchema, ok, resolverFor, withCaller } from "./common.js";
+import { attachmentType, isoTime, participantsOf } from "../render.js";
+import { SENDS, attachmentItem, idSchema, ok, resolverFor, withCaller } from "./common.js";
 const IMMUTABLE = "fmsg messages are immutable: once sent they cannot be edited or recalled. Send within the user's requested task or authorized automation.";
 const attachmentInput = z.object({
     filename: z.string().regex(/^[A-Za-z0-9._-]+$/u, "letters, digits, dot, underscore, hyphen only"),
     data_base64: z.string().min(1),
     content_type: z.string().optional(),
 });
+/** Sent attachments with the type each was given, or the one its filename implies. */
+function sentAttachments(sent, outbound) {
+    return sent.map((a, i) => ({ ...a, type: attachmentType(a.filename, outbound[i]?.contentType) }));
+}
 function decodeAttachments(items) {
     return (items ?? []).map((a) => {
         const data = Buffer.from(a.data_base64, "base64");
@@ -24,7 +28,7 @@ const sentOutput = z.object({
     to: z.array(z.string()),
     topic: z.string(),
     parent_id: z.string().nullable(),
-    attachments: z.array(z.object({ filename: z.string(), size: z.number() })),
+    attachments: z.array(attachmentItem),
     redactions: z.number().describe("secrets replaced with placeholders before sending"),
     warnings: z.array(z.string()),
 });
@@ -48,6 +52,7 @@ export const registerSendTools = (server, deps) => {
         annotations: SENDS,
     }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const recipients = resolveAddresses(to, resolverFor(deps, caller));
+        const outbound = decodeAttachments(attachments);
         const sent = await caller.client.send({
             to: recipients,
             topic,
@@ -55,7 +60,7 @@ export const registerSendTools = (server, deps) => {
             type,
             important,
             noReply: no_reply,
-            attachments: decodeAttachments(attachments),
+            attachments: outbound,
             signal,
         });
         const structured = {
@@ -65,7 +70,7 @@ export const registerSendTools = (server, deps) => {
             to: recipients,
             topic: sent.topic,
             parent_id: null,
-            attachments: sent.attachments,
+            attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
             warnings: [],
         };
@@ -105,6 +110,7 @@ export const registerSendTools = (server, deps) => {
             : participantsOf(parent).filter((a) => !sameAddress(a, caller.address));
         if (to.length === 0)
             return toolError(`message ${id} has no other participants to reply to; pass recipients`);
+        const outbound = decodeAttachments(attachments);
         const sent = await caller.client.send({
             to,
             pid: parent.id,
@@ -112,7 +118,7 @@ export const registerSendTools = (server, deps) => {
             type,
             important,
             noReply: no_reply,
-            attachments: decodeAttachments(attachments),
+            attachments: outbound,
             signal,
         });
         const structured = {
@@ -122,7 +128,7 @@ export const registerSendTools = (server, deps) => {
             to,
             topic: "",
             parent_id: parent.id,
-            attachments: sent.attachments,
+            attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
             warnings,
         };
@@ -135,16 +141,26 @@ export const registerSendTools = (server, deps) => {
         description: "Add recipients to a message that was already sent (one you sent or received as a primary recipient). " +
             "They receive the message and become participants of its thread. This cannot be undone. Fails on terminal messages.",
         inputSchema: z.object({
-            id: idSchema,
-            add_to: z.array(z.string()).min(1).describe("addresses or short names to add"),
+            id: idSchema.describe("the sent message to add recipients to"),
+            recipients: z.array(z.string()).min(1).optional().describe("addresses or short names to add"),
+            add_to: z.array(z.string()).min(1).optional().describe("deprecated alias of recipients; pass one or the other"),
+        }),
+        outputSchema: z.object({
+            id: z.string(),
+            added: z.number(),
+            recipients: z.array(z.string()),
+            add_to: z.array(z.string()).describe("deprecated copy of recipients"),
         }),
-        outputSchema: z.object({ id: z.string(), added: z.number(), add_to: z.array(z.string()) }),
         annotations: { ...SENDS, idempotentHint: true },
-    }, async ({ id, add_to }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
-        const addresses = resolveAddresses(add_to, resolverFor(deps, caller));
-        const result = await caller.client.addRecipients(id, addresses, signal);
-        return ok(`Added ${result.added} recipient(s) to message ${id}: ${addresses.join(", ")}`, { ...result, add_to: addresses });
-    }));
+    }, async ({ id, recipients, add_to }, ctx) => {
+        if ((recipients === undefined) === (add_to === undefined))
+            return toolError("pass recipients: the addresses to add (add_to is its deprecated alias; not both)");
+        return withCaller(deps, ctx, async (caller, signal) => {
+            const addresses = resolveAddresses((recipients ?? add_to), resolverFor(deps, caller));
+            const result = await caller.client.addRecipients(id, addresses, signal);
+            return ok(`Added ${result.added} recipient(s) to message ${id}: ${addresses.join(", ")}`, { ...result, recipients: addresses, add_to: addresses });
+        });
+    });
     server.registerTool("react", {
         title: "React to fmsg message",
         description: "Set or clear your emoji reaction on a message (one reaction per person; a new emoji replaces the previous). " +
@@ -161,6 +177,4 @@ export const registerSendTools = (server, deps) => {
         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);
     }));
-    // Kept read-only tools' annotation import in use for symmetry with other files.
-    void READ_ONLY;
 };

package/dist/tools/wait.js

@@ -3,7 +3,11 @@ import { resolveAddress } from "../address.js";
 import { assembleThread, renderThread } from "../thread.js";
 import { DATA_NOT_INSTRUCTIONS, fence, headerValue, messageData, messageLine } from "../render.js";
 import { waitForMessage } from "../wait.js";
-import { READ_ONLY, idSchema, messageItem, ok, resolverFor, toItem, withCaller } from "./common.js";
+import { READ_ONLY, UNTRUSTED, idSchema, messageItem, ok, resolverFor, toItem, untrustedNotice, withCaller } from "./common.js";
+/** Skipped reactions as one line each, for the data block. */
+function reactionLines(skipped) {
+    return skipped.filter((s) => s.emoji !== undefined).map((s) => `- ${s.id} from ${headerValue(s.from)}: ${s.emoji ? `reacted ${headerValue(s.emoji)}` : "cleared a reaction"}${s.reaction_to ? ` on message ${s.reaction_to}` : ""}`);
+}
 export const registerWaitTools = (server, deps) => {
     const maxWait = deps.config.waitMaxSeconds;
     server.registerTool("wait_for_message", {
@@ -11,10 +15,15 @@ export const registerWaitTools = (server, deps) => {
         description: "Block until the next inbound message arrives (pushed over the fmsg host's WebSocket) and return it with its " +
             "thread context so you can answer with reply. Use this when the user asks you to chat, converse, keep replying, " +
             "auto-reply, or respond to the next message. Loop: wait → reply → wait again passing the after_id from the " +
-            "previous result. On status \"timeout\" simply call again with the same arguments. Messages arriving on the " +
-            "same thread within settle_seconds are batched into ONE result; reply once, to the newest (reply_target_id). " +
-            "Your own messages, reactions and no-reply messages never qualify. Each call blocks at most " +
-            `timeout_seconds (max ${maxWait}); stop looping when the user interrupts or the limits they set are reached.`,
+            "previous result. On status \"timeout\" simply call again with the same arguments and the returned after_id, " +
+            "which is never older than the newest inbox message when the call started, so nothing is replayed (\"0\" means " +
+            "the inbox was empty and is safe to pass). Messages arriving on the same thread within settle_seconds are " +
+            "batched into ONE result; reply once, to the newest (reply_target_id); the result's next field says what to do. " +
+            "Your own messages, reactions and no-reply messages never qualify; they are listed in skipped. Each call blocks " +
+            `at most timeout_seconds (max ${maxWait}); stop looping when the user interrupts or the limits they set are reached. ` +
+            "In chat hosts each wait is a model turn: tell the user you are listening and for how long rather than " +
+            "looping silently for long periods. Status \"interrupted\" means the server is restarting: call again with the " +
+            "returned after_id; no messages are lost.",
         inputSchema: z.object({
             after_id: idSchema.optional().describe("only messages with a greater id qualify; pass the after_id from the previous result. Omit on the first call to wait for messages arriving from now on"),
             thread_of: idSchema.optional().describe("only accept messages in this message's thread"),
@@ -24,16 +33,25 @@ export const registerWaitTools = (server, deps) => {
             include_thread: z.boolean().default(true).describe("include the assembled thread context of the newest message"),
         }),
         outputSchema: z.object({
-            status: z.enum(["message", "timeout"]),
+            status: z.enum(["message", "timeout", "interrupted"]).describe("interrupted: the server is restarting; call again with after_id"),
             after_id: z.string().describe("pass this as after_id on the next call"),
             thread_root_id: z.string().nullable(),
+            thread_topic: z.string().nullable().describe("the thread root's topic (replies carry none); null when unknown"),
             reply_target_id: z.string().nullable().describe("newest message of the batch; reply to this one"),
             messages: z.array(messageItem.extend({ body: z.string().nullable() })),
             pending_other_threads: z.array(z.object({ id: z.string(), from: z.string(), root_id: z.string().nullable() })),
-            skipped: z.array(z.object({ id: z.string(), reason: z.enum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]) })).describe("messages deliberately passed over; after_id has advanced past them"),
+            skipped: z.array(z.object({
+                id: z.string(),
+                reason: z.enum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]),
+                from: z.string(),
+                emoji: z.string().optional().describe("for reactions: the emoji (\"\" clears a reaction)"),
+                reaction_to: z.string().nullable().optional().describe("for reactions: the message reacted to"),
+            })).describe("messages deliberately passed over; after_id has advanced past them"),
             unclassified: z.array(z.object({ id: z.string(), from: z.string(), error: z.string() })).describe("messages whose thread could not be determined; after_id is held before them, call again to retry"),
             transport: z.enum(["websocket", "poll"]),
             note: z.string().nullable(),
+            next: z.string().describe("what to do with this result"),
+            ...untrustedNotice,
         }),
         annotations: { ...READ_ONLY, idempotentHint: false },
     }, async ({ after_id, thread_of, from, timeout_seconds, settle_seconds, include_thread }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
@@ -42,6 +60,7 @@ export const registerWaitTools = (server, deps) => {
             ...(after_id !== undefined ? { afterId: after_id } : {}),
             ...(thread_of !== undefined ? { threadOf: thread_of } : {}),
             ...(from !== undefined ? { from: resolveAddress(from, resolverFor(deps, caller)).address } : {}),
+            ...(deps.shutdown ? { interrupt: deps.shutdown } : {}),
             timeoutMs: timeout_seconds * 1000,
             settleMs: settle_seconds * 1000,
             onTick: (elapsed) => {
@@ -57,10 +76,19 @@ export const registerWaitTools = (server, deps) => {
         }, signal);
         const messages = await Promise.all(result.messages.map(async (m) => ({ ...toItem(m, caller.address), body: await caller.client.getText(m, signal) })));
         const newest = result.messages[result.messages.length - 1];
+        const keepWaiting = `call wait_for_message with after_id "${result.after_id}"${thread_of !== undefined ? ` and thread_of "${thread_of}"` : ""} to keep listening`;
+        const next = result.status === "interrupted"
+            ? `The server is restarting; ${keepWaiting}. No messages are lost.`
+            : !newest
+                ? `No new message yet; ${keepWaiting}, unless the user's time limit is reached.`
+                : newest.terminal
+                    ? `Message ${newest.id} is terminal and cannot be replied to; ${keepWaiting}.`
+                    : `Reply to message ${newest.id} with the reply tool, then ${keepWaiting}.`;
         const structured = {
             status: result.status,
             after_id: result.after_id,
             thread_root_id: result.thread_root_id,
+            thread_topic: result.thread_topic,
             reply_target_id: newest?.id ?? null,
             messages,
             pending_other_threads: result.pending_other_threads,
@@ -68,14 +96,22 @@ export const registerWaitTools = (server, deps) => {
             unclassified: result.unclassified,
             transport: result.transport,
             note: result.note,
+            next,
+            ...UNTRUSTED,
         };
+        const reactions = reactionLines(result.skipped);
+        if (result.status === "interrupted")
+            return ok(`${next} (after_id ${result.after_id})`, structured);
         if (result.status === "timeout") {
-            return ok(`No qualifying message arrived within ${timeout_seconds}s (after_id ${result.after_id}, ${result.transport})${result.note ? `; ${result.note}` : ""}. Call again to keep waiting.`, structured);
+            const waited = `No qualifying message arrived within ${timeout_seconds}s (after_id ${result.after_id}, ${result.transport})${result.note ? `; ${result.note}` : ""}. Call again to keep waiting.`;
+            return ok(reactions.length ? `${waited}\n\nSkipped reactions:\n${messageData(reactions.join("\n"))}` : waited, structured);
         }
         const lines = [
             `${result.messages.length} new message${result.messages.length === 1 ? "" : "s"} (after_id ${result.after_id}, ${result.transport}):`,
             messageData(result.messages.map((m) => messageLine(m, caller.address)).join("\n")),
         ];
+        if (reactions.length)
+            lines.push(`Skipped reactions:\n${messageData(reactions.join("\n"))}`);
         if (result.pending_other_threads.length) {
             lines.push(`Also waiting on other threads: ${result.pending_other_threads.map((p) => p.id).join(", ")}`);
         }
@@ -90,7 +126,7 @@ export const registerWaitTools = (server, deps) => {
                 maxBodyBytesPerMessage: 16_384,
                 maxTotalBytes: 262_144,
             }, signal);
-            lines.push("", renderThread(thread));
+            lines.push("", renderThread(thread), "", next);
         }
         else if (newest) {
             lines.push("", DATA_NOT_INSTRUCTIONS);
@@ -98,7 +134,7 @@ export const registerWaitTools = (server, deps) => {
                 if (m.body !== null)
                     lines.push("", `--- message ${m.id} from ${headerValue(m.from)} ---`, fence(m.body));
             lines.push("", "End of message data.");
-            lines.push("", `Reply to message ${newest.id} with the reply tool.`);
+            lines.push("", next);
         }
         return ok(lines.join("\n"), structured);
     }));

package/dist/wait.d.ts

@@ -15,7 +15,10 @@ export type WaitOptions = {
     /** How long to wait for the WebSocket to open before falling back to polling. */
     wsOpenTimeoutMs?: number;
     onTick?: (elapsedMs: number) => void;
+    /** Server shutdown: end the wait early with status "interrupted" and a resumable cursor. */
+    interrupt?: AbortSignal;
 };
+export declare const INTERRUPTED_NOTE = "the server is restarting; call wait_for_message again with the after_id returned here; no messages are lost";
 export type Pending = {
     id: string;
     from: string;
@@ -25,6 +28,10 @@ export type SkipReason = "own" | "reaction" | "no_reply" | "from_mismatch" | "ot
 export type Skipped = {
     id: string;
     reason: SkipReason;
+    from: string;
+    /** For reactions: the emoji ("" clears) and the message reacted to. */
+    emoji?: string;
+    reaction_to?: string | null;
 };
 export type Unclassified = {
     id: string;
@@ -32,9 +39,12 @@ export type Unclassified = {
     error: string;
 };
 export type WaitResult = {
-    status: "message" | "timeout";
+    /** "interrupted": the server is shutting down; resume from after_id. */
+    status: "message" | "timeout" | "interrupted";
     after_id: string;
     thread_root_id: string | null;
+    /** The root's topic when the root was readable; replies carry no topic of their own. */
+    thread_topic: string | null;
     messages: FmsgMessage[];
     pending_other_threads: Pending[];
     /** Messages deliberately passed over (the cursor advances past these). */

package/dist/wait.js

@@ -4,6 +4,7 @@ import { compareMessageIds, maxMessageId, minMessageId } from "./client/message-
 import { safeErrorMessage } from "./client/redact.js";
 import { openFmsgWebSocket, parseWsEvent, webSocketTokenExpiresAt } from "./client/ws.js";
 import { OAuthRequestError } from "./oauth/errors.js";
+export const INTERRUPTED_NOTE = "the server is restarting; call wait_for_message again with the after_id returned here; no messages are lost";
 /**
  * Block until the next qualifying inbound message (plus any that arrive on the
  * same thread within the settle window), or until the deadline.
@@ -42,9 +43,15 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
         }
     };
     const rootCache = new Map();
+    /** Root topics seen while resolving roots, so results can name the thread without another request. */
+    const rootTopics = new Map();
     const lookupRoot = async (id) => {
         try {
-            return (await client.getThreadMessages(id, retrySignal)).root_id;
+            const thread = await client.getThreadMessages(id, retrySignal);
+            const root = thread.messages[0];
+            if (root?.visible && root.id === thread.root_id)
+                rootTopics.set(root.id, root.topic ?? "");
+            return thread.root_id;
         }
         catch (error) {
             if (authorizationFailure(error))
@@ -53,8 +60,10 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             let cur = id;
             for (let i = 0; i < 100; i++) {
                 const m = await client.getMessage(cur, retrySignal);
-                if (!m.pid)
+                if (!m.pid) {
+                    rootTopics.set(m.id, m.topic ?? "");
                     return m.id;
+                }
                 cur = m.pid;
             }
             throw error;
@@ -122,9 +131,11 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             clearInterval(pollTimer);
             clearInterval(tickTimer);
             signal?.removeEventListener("abort", onAbort);
+            options.interrupt?.removeEventListener("abort", onInterrupt);
             if (socket)
                 disposeSocket(socket);
         };
+        let interrupted = false;
         const finish = () => {
             if (finished)
                 return;
@@ -144,9 +155,10 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
                 note = note ? `${note}; ${held}` : held;
             }
             resolve({
-                status: batch.length ? "message" : "timeout",
+                status: batch.length ? "message" : interrupted ? "interrupted" : "timeout",
                 after_id: afterId,
                 thread_root_id: batchRoot,
+                thread_topic: batchRoot === null ? null : (rootTopics.get(batchRoot) ?? null),
                 messages: [...batch].sort((a, b) => compareMessageIds(a.id, b.id)),
                 pending_other_threads: pending,
                 skipped: [...skipped].sort((a, b) => compareMessageIds(a.id, b.id)),
@@ -165,6 +177,12 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             note = "cancelled";
             finish();
         };
+        // Messages already collected are still returned; their cursor covers them.
+        const onInterrupt = () => {
+            interrupted = true;
+            note = batch.length ? "the server is restarting, which cut the settle window short" : INTERRUPTED_NOTE;
+            finish();
+        };
         const deadlineTimer = setTimeout(() => {
             if (batch.length && settleTimer)
                 note = "the time limit cut the settle window short";
@@ -172,8 +190,11 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
         }, Math.max(0, deadline - Date.now()));
         const tickTimer = setInterval(() => options.onTick?.(Date.now() - start), 20_000);
         signal?.addEventListener("abort", onAbort, { once: true });
+        options.interrupt?.addEventListener("abort", onInterrupt, { once: true });
         if (signal?.aborted)
             return onAbort();
+        if (options.interrupt?.aborted)
+            return onInterrupt();
         const consider = async (m) => {
             if (finished || seen.has(m.id))
                 return;
@@ -184,7 +205,8 @@ export async function waitForMessage(client, self, options, signal, deps = {}) {
             if (compareMessageIds(m.id, floor) <= 0)
                 return;
             const skip = (reason) => {
-                skipped.push({ id: m.id, reason });
+                const reaction = typeof m.reaction === "string" ? { emoji: m.reaction, reaction_to: m.pid ?? null } : {};
+                skipped.push({ id: m.id, reason, from: m.from, ...reaction });
                 if (compareMessageIds(m.id, skippedMax) > 0)
                     skippedMax = m.id;
             };

package/docs/http-deployment.md

@@ -69,7 +69,9 @@ the public same-origin value, so explicitly listing that origin is optional.
 `https://mcp.example.com/mcp/attachments/123/report.pdf`. The host fetches it with an authenticated
 GET, using the same `Authorization: Bearer ...` header as its MCP connection. OAuth requires
 `fmsg:read`; the server exchanges the incoming token for a Web API token as usual. The Web API
-checks visibility on every download, even when a link was obtained earlier.
+checks visibility on every download, even when a link was obtained earlier. Hosts that cannot send
+the connection's Authorization header with an arbitrary GET (many chat hosts cannot) should use
+`download_attachment` instead; the tool's description and result say so.
 
 Set `FMSG_MCP_PUBLIC_URL` to the exact external MCP endpoint when using API keys. OAuth defaults
 to `FMSG_MCP_OAUTH_RESOURCE_URL`; if both are set, they must match. These URLs require HTTPS outside

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markmnl/fmsg-mcp",
   "mcpName": "io.github.markmnl/fmsg-mcp",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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": "0.2.5",
+  "version": "0.2.6",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@markmnl/fmsg-mcp",
-      "version": "0.2.5",
+      "version": "0.2.6",
       "transport": {
         "type": "stdio"
       },