@markmnl/fmsg-mcp 0.2.6 → 0.2.8

package/dist/tools/send.js

@@ -1,17 +1,17 @@
 import * as z from "zod/v4";
 import { resolveAddresses, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
-import { attachmentType, isoTime, participantsOf } from "../render.js";
-import { SENDS, attachmentItem, idSchema, ok, resolverFor, withCaller } from "./common.js";
+import { addressList, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.js";
+import { SENDS, attachmentItem, idSchema, ok, outputObject, 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. */
+/** Sent attachments with the type each was given, or the one its filename implies, in the order every tool lists them. */
 function sentAttachments(sent, outbound) {
-    return sent.map((a, i) => ({ ...a, type: attachmentType(a.filename, outbound[i]?.contentType) }));
+    return sortAttachments(sent.map((a, i) => ({ ...a, type: attachmentType(a.filename, outbound[i]?.contentType) })));
 }
 function decodeAttachments(items) {
     return (items ?? []).map((a) => {
@@ -21,16 +21,17 @@ function decodeAttachments(items) {
         return { filename: a.filename, data: new Uint8Array(data), ...(a.content_type ? { contentType: a.content_type } : {}) };
     });
 }
-const sentOutput = z.object({
+const sentOutput = outputObject({
     id: z.string(),
     time: z.string().nullable(),
     from: z.string(),
     to: z.array(z.string()),
     topic: z.string(),
     parent_id: z.string().nullable(),
-    attachments: z.array(attachmentItem),
+    attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
     redactions: z.number().describe("secrets replaced with placeholders before sending"),
     warnings: z.array(z.string()),
+    thread_topic: z.string().nullable().optional().describe("the thread's topic: the topic sent for a new message; for a reply, the parent's topic when the parent is the thread root, otherwise null (get_thread reports it)"),
 });
 export const registerSendTools = (server, deps) => {
     server.registerTool("send_message", {
@@ -73,9 +74,10 @@ export const registerSendTools = (server, deps) => {
             attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
             warnings: [],
+            thread_topic: sent.topic,
         };
-        const text = `Sent message ${sent.id} "${sent.topic}" to ${recipients.join(", ")} at ${structured.time ?? "?"}` +
-            (sent.attachments.length ? ` with ${sent.attachments.map((a) => a.filename).join(", ")}` : "") +
+        const text = `Sent message ${sent.id} "${sent.topic}" to ${addressList(recipients)} at ${structured.time ?? "?"}` +
+            (structured.attachments.length ? ` with ${structured.attachments.map((a) => a.filename).join(", ")}` : "") +
             (structured.redactions ? `. ${structured.redactions} secret(s) were redacted before sending.` : ".");
         return ok(text, structured);
     }));
@@ -131,8 +133,11 @@ export const registerSendTools = (server, deps) => {
             attachments: sentAttachments(sent.attachments, outbound),
             redactions: sent.redactions,
             warnings,
+            // Topics live only on a thread's root; a deeper parent would need another lookup.
+            thread_topic: parent.pid ? null : (parent.topic ?? ""),
         };
-        const text = `Sent reply ${sent.id} to message ${parent.id} for ${to.join(", ")} at ${structured.time ?? "?"}` +
+        const topic = structured.thread_topic ? ` in "${headerValue(structured.thread_topic)}"` : "";
+        const text = `Sent reply ${sent.id} to message ${parent.id}${topic} for ${addressList(to)} at ${structured.time ?? "?"}` +
             (structured.redactions ? `. ${structured.redactions} secret(s) were redacted before sending.` : ".");
         return ok(text, structured);
     }));
@@ -145,10 +150,10 @@ export const registerSendTools = (server, deps) => {
             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({
+        outputSchema: outputObject({
             id: z.string(),
             added: z.number(),
-            recipients: z.array(z.string()),
+            recipients: z.array(z.string()).optional().describe("the resolved addresses that were added"),
             add_to: z.array(z.string()).describe("deprecated copy of recipients"),
         }),
         annotations: { ...SENDS, idempotentHint: true },
@@ -158,7 +163,7 @@ export const registerSendTools = (server, deps) => {
         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 });
+            return ok(`Added ${result.added} recipient(s) to message ${id}: ${addressList(addresses)}`, { ...result, recipients: addresses, add_to: addresses });
         });
     });
     server.registerTool("react", {
@@ -169,7 +174,7 @@ export const registerSendTools = (server, deps) => {
             id: idSchema,
             emoji: z.string().max(32).nullable().describe("a single emoji; null or empty clears your reaction"),
         }),
-        outputSchema: z.object({ id: z.string(), reaction_id: z.string().nullable(), time: z.string().nullable(), cleared: z.boolean() }),
+        outputSchema: outputObject({ id: z.string(), reaction_id: z.string().nullable(), time: z.string().nullable(), cleared: z.boolean() }),
         annotations: { ...SENDS, destructiveHint: false, idempotentHint: true },
     }, async ({ id, emoji }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const value = emoji && emoji.trim() ? emoji.trim() : null;

package/dist/tools/wait.js

@@ -1,12 +1,30 @@
 import * as z from "zod/v4";
+import { compareMessageIds } from "../client/message-id.js";
 import { resolveAddress } from "../address.js";
 import { assembleThread, renderThread } from "../thread.js";
-import { DATA_NOT_INSTRUCTIONS, fence, headerValue, messageData, messageLine } from "../render.js";
+import { DATA_NOT_INSTRUCTIONS, addressText, fence, headerValue, messageData, messageLine } from "../render.js";
 import { waitForMessage } from "../wait.js";
-import { READ_ONLY, UNTRUSTED, idSchema, messageItem, ok, resolverFor, toItem, untrustedNotice, withCaller } from "./common.js";
+import { READ_ONLY, UNTRUSTED, idSchema, messageItem, ok, openEnum, outputObject, 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}` : ""}`);
+    return skipped.filter((s) => s.emoji !== undefined).map((s) => `- ${s.id} from ${addressText(s.from)}: ${s.emoji ? `reacted ${headerValue(s.emoji)}` : "cleared a reaction"}${s.reaction_to ? ` on message ${s.reaction_to}` : ""}`);
+}
+/**
+ * Messages that arrived on other threads (or beyond the batch limit) during the settle window. They are not
+ * returned and after_id moves past them, so the next step must name each one; otherwise a model following `next`
+ * never sees them.
+ */
+function pendingStep(pending, batchRoot) {
+    if (!pending.length)
+        return "";
+    const described = pending.map((p) => {
+        const where = p.root_id === null ? "" : p.root_id === batchRoot ? " in this thread (beyond the batch limit)" : ` in another thread (root ${p.root_id})`;
+        return `message ${p.id}${where}`;
+    });
+    const many = pending.length > 1;
+    return `Also new and not included here: ${described.join(", ")}. after_id has moved past ${many ? "them" : "it"}, so ` +
+        `the next wait will not return ${many ? "them" : "it"}: read ${many ? "each" : "it"} with get_thread (or get_message) ` +
+        `${pending.map((p) => `"${p.id}"`).join(", ")} and reply if appropriate before waiting again.`;
 }
 export const registerWaitTools = (server, deps) => {
     const maxWait = deps.config.waitMaxSeconds;
@@ -19,6 +37,9 @@ export const registerWaitTools = (server, deps) => {
             "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. " +
+            "Messages on other threads that arrive during that window are not returned: they are listed in " +
+            "pending_other_threads and pending_ids, after_id moves past them, and next says to read them with get_thread " +
+            "or get_message before waiting again (a later wait will not return them). " +
             "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 " +
@@ -32,25 +53,26 @@ export const registerWaitTools = (server, deps) => {
             settle_seconds: z.number().int().min(0).max(30).default(3).describe("after the first message, keep collecting same-thread messages for this long"),
             include_thread: z.boolean().default(true).describe("include the assembled thread context of the newest message"),
         }),
-        outputSchema: z.object({
-            status: z.enum(["message", "timeout", "interrupted"]).describe("interrupted: the server is restarting; call again with after_id"),
+        outputSchema: outputObject({
+            status: openEnum(["message", "timeout", "interrupted"], "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"),
+            thread_topic: z.string().nullable().optional().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({
+            pending_other_threads: z.array(outputObject({ id: z.string(), from: z.string(), root_id: z.string().nullable() })).describe("new messages not returned here (other threads, or beyond the batch limit); after_id has moved past them, so read each with get_thread or get_message"),
+            pending_ids: z.array(z.string()).optional().describe("ids of pending_other_threads, oldest first: read these before waiting again"),
+            skipped: z.array(outputObject({
                 id: z.string(),
-                reason: z.enum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]),
-                from: z.string(),
+                reason: openEnum(["own", "reaction", "no_reply", "from_mismatch", "other_thread"]),
+                from: z.string().optional(),
                 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"]),
+            unclassified: z.array(outputObject({ 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: openEnum(["websocket", "poll"]),
             note: z.string().nullable(),
-            next: z.string().describe("what to do with this result"),
+            next: z.string().optional().describe("what to do with this result"),
             ...untrustedNotice,
         }),
         annotations: { ...READ_ONLY, idempotentHint: false },
@@ -77,13 +99,16 @@ export const registerWaitTools = (server, deps) => {
         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 pending = [...result.pending_other_threads].sort((a, b) => compareMessageIds(a.id, b.id));
+        const alsoNew = pendingStep(pending, result.thread_root_id);
+        const thenWait = alsoNew ? `${alsoNew} Then ${keepWaiting}.` : "";
         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}.`;
+                    ? `Message ${newest.id} is terminal and cannot be replied to.${thenWait ? ` ${thenWait}` : ` Next, ${keepWaiting}.`}`
+                    : `Reply to message ${newest.id} with the reply tool.${thenWait ? ` ${thenWait}` : ` Then ${keepWaiting}.`}`;
         const structured = {
             status: result.status,
             after_id: result.after_id,
@@ -91,7 +116,8 @@ export const registerWaitTools = (server, deps) => {
             thread_topic: result.thread_topic,
             reply_target_id: newest?.id ?? null,
             messages,
-            pending_other_threads: result.pending_other_threads,
+            pending_other_threads: pending,
+            pending_ids: pending.map((p) => p.id),
             skipped: result.skipped,
             unclassified: result.unclassified,
             transport: result.transport,
@@ -112,9 +138,6 @@ export const registerWaitTools = (server, deps) => {
         ];
         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(", ")}`);
-        }
         if (result.unclassified.length) {
             lines.push(`Could not classify ${result.unclassified.map((u) => u.id).join(", ")}; after_id is held before them, call again to retry.`);
         }
@@ -132,7 +155,7 @@ export const registerWaitTools = (server, deps) => {
             lines.push("", DATA_NOT_INSTRUCTIONS);
             for (const m of messages)
                 if (m.body !== null)
-                    lines.push("", `--- message ${m.id} from ${headerValue(m.from)} ---`, fence(m.body));
+                    lines.push("", `--- message ${m.id} from ${addressText(m.from)} ---`, fence(m.body));
             lines.push("", "End of message data.");
             lines.push("", next);
         }

package/docs/http-deployment.md

@@ -63,6 +63,14 @@ The metadata routes are public in `oauth` and `oauth+api-key` modes and must rea
 MCP authorization discovery. In API-key mode they return 404. When OAuth is configured, its resource URL supplies
 the public same-origin value, so explicitly listing that origin is optional.
 
+## Upgrades and cached tool schemas
+
+Chat hosts may cache each tool's `outputSchema` from when the connector was added and validate
+results against it. Output schemas are open and additive (see "Output schema compatibility" in the
+README), so later upgrades keep validating. Schemas published by 0.2.6 and earlier were closed: after
+upgrading from those releases, users whose host reports that structured content does not match the
+tool's output schema must reconnect (remove and re-add) the connector once.
+
 ## Binary attachment downloads
 
 `get_attachment_download_url` returns a resource link such as

package/package.json

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