@markmnl/fmsg-mcp 0.2.9 → 1.1.0

package/dist/tools/draft.js

@@ -0,0 +1,151 @@
+import * as z from "zod/v4";
+import { downloadBaseUrl } from "../download.js";
+import { toolError } from "../errors.js";
+import { addressList, headerValue, isoTime } from "../render.js";
+import { CHECKSUM_HEADER, UPLOAD_ENCODINGS, draftUploadUrlTemplate } from "../upload.js";
+import { attachmentInput, base64Hint, draftWithAttachments, fileRoutes, prepareAttachments } from "./attachments.js";
+import { SENDS, attachmentItem, idSchema, ok, openEnum, outputObject, resolverFor, withCaller } from "./common.js";
+import { rootTopic } from "./read.js";
+import { IMMUTABLE, IMPORTANT, NO_REPLY, UPLOAD_STEPS, hintOutput, redactionNote, replyRecipients, resolveRecipients, resolvedNote, resolvedOutput, sendWarnings, sentAttachments, sentOutput, withHint, } from "./send.js";
+export const registerDraftTools = (server, deps) => {
+    const baseUrl = downloadBaseUrl(deps.config);
+    const routes = fileRoutes(deps.config);
+    server.registerTool("create_draft", {
+        title: "Create fmsg draft",
+        description: "Create an unsent draft: a new message, or a reply when reply_to is given (reply rules and reply-all apply). " +
+            "Nothing is sent until send_draft; delete_draft discards it. The draft is visible in the user's other fmsg clients. " +
+            (routes.uploadUrl ? `Use it for large files: ${UPLOAD_STEPS}. ` : "") +
+            "Secrets in the body and topic are redacted.",
+        inputSchema: z.strictObject({
+            to: z.array(z.string()).min(1).optional().describe("recipient addresses (@user@domain) or short names; for a reply, overrides reply-all"),
+            topic: z.string().max(256).optional().describe("thread topic for a new message; not allowed with reply_to"),
+            reply_to: idSchema.optional().describe("message this draft replies to"),
+            body: z.string().describe("message body; Markdown unless type says otherwise"),
+            type: z.string().default("text/markdown; charset=utf-8").describe("body media type"),
+            important: z.boolean().default(false).describe(IMPORTANT),
+            no_reply: z.boolean().default(false).describe(NO_REPLY),
+            allow_no_reply: z.boolean().default(false).describe("draft a reply even though the parent asked for no replies"),
+            attachments: z.array(attachmentInput(deps.config)).optional().describe("files to attach now"),
+        }),
+        outputSchema: outputObject({
+            draft_id: z.string(),
+            to: z.array(z.string()),
+            topic: z.string(),
+            parent_id: z.string().nullable(),
+            attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
+            redactions: z.number().describe("secrets replaced with placeholders in the draft"),
+            redacted: z.array(z.string()).describe("the kinds of secret replaced; empty when none"),
+            resolved: resolvedOutput,
+            warnings: z.array(z.string()).describe("things to tell the user, such as redacted secrets or resolved short names"),
+            upload: outputObject({
+                url_template: z.string().describe("replace {filename} with the attachment's file name (letters, digits, dot, underscore, hyphen)"),
+                method: openEnum(["PUT"]),
+                authentication: openEnum(["bearer"], "bearer: send this MCP connection's Authorization header"),
+                checksum_header: z.string().describe("optional request header carrying the file's hex sha256; a mismatch is refused and the file not kept"),
+                accepts_encoding: z.array(z.string()).describe("Content-Encoding values accepted; the server decodes them before storing"),
+            }).optional().describe("where to upload more attachments; present when this server has a public URL"),
+            next: z.string(),
+            hint: hintOutput,
+        }),
+        annotations: { ...SENDS, destructiveHint: false },
+    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, attachments }, ctx) => {
+        if (reply_to && topic)
+            return toolError("a reply has no topic: pass topic only for a new message");
+        if (!reply_to && !to?.length)
+            return toolError("pass to: the recipients (or reply_to to draft a reply)");
+        return withCaller(deps, ctx, async (caller, signal) => {
+            let recipients;
+            let resolved;
+            let pid;
+            if (reply_to) {
+                const parent = await caller.client.getMessage(reply_to, signal);
+                const target = replyRecipients(deps, caller, parent, to, allow_no_reply);
+                if ("content" in target)
+                    return target;
+                ({ to: recipients, resolved } = target);
+                pid = parent.id;
+            }
+            else {
+                ({ to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller)));
+            }
+            const outbound = await prepareAttachments(attachments, deps.config);
+            const hint = base64Hint(attachments, routes);
+            const draft = await draftWithAttachments(caller.client, {
+                to: recipients, body, type, important, noReply: no_reply, ...(pid ? { pid } : { topic: topic ?? "" }),
+            }, outbound, signal);
+            const upload = baseUrl ? {
+                url_template: draftUploadUrlTemplate(baseUrl, draft.id),
+                method: "PUT",
+                authentication: "bearer",
+                checksum_header: CHECKSUM_HEADER,
+                accepts_encoding: [...UPLOAD_ENCODINGS],
+            } : undefined;
+            const next = (upload ? `Upload files with PUT to ${upload.url_template} using this MCP connection's Authorization header, then call send_draft. ` : "Call send_draft to send it. ") +
+                "Call delete_draft to discard it.";
+            const structured = {
+                draft_id: draft.id,
+                to: recipients,
+                topic: draft.topic,
+                parent_id: pid ?? null,
+                attachments: sentAttachments(draft.attachments, outbound),
+                redactions: draft.redactions,
+                redacted: draft.redacted,
+                ...(resolved.length ? { resolved } : {}),
+                warnings: sendWarnings(draft.redactions, draft.redacted, resolved),
+                ...(upload ? { upload } : {}),
+                next,
+                ...(hint ? { hint } : {}),
+            };
+            const what = pid ? `reply to message ${pid}` : `"${headerValue(draft.topic)}"`;
+            const text = `Created draft ${draft.id} (${what}) for ${addressList(recipients)}; not sent` +
+                (structured.attachments.length ? `, with ${structured.attachments.map((a) => a.filename).join(", ")}` : "") +
+                redactionNote(draft.redactions, draft.redacted) + resolvedNote(resolved) + `\n\n${next}`;
+            return ok(withHint(text, hint), structured);
+        });
+    });
+    server.registerTool("send_draft", {
+        title: "Send fmsg draft",
+        description: `Send a draft made with create_draft, with its attachments, immediately. ${IMMUTABLE} ` +
+            "If the host refuses it, its reason is returned verbatim and the message stays a draft.",
+        inputSchema: z.strictObject({ id: idSchema.describe("the draft to send") }),
+        outputSchema: sentOutput,
+        annotations: SENDS,
+    }, async ({ id }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const draft = await caller.client.getMessage(id, signal);
+        if (draft.time !== null && draft.time !== undefined)
+            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 ?? "");
+        const structured = {
+            id: sent.id,
+            time: isoTime(sent.time),
+            from: caller.address,
+            to: draft.to,
+            topic,
+            parent_id: draft.pid ?? null,
+            attachments: sentAttachments(draft.attachments ?? []),
+            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,
+        };
+        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 ?? "?"}` +
+            (structured.attachments.length ? ` with ${structured.attachments.map((a) => a.filename).join(", ")}` : "") + ".";
+        return ok(text, structured);
+    }));
+    server.registerTool("delete_draft", {
+        title: "Delete fmsg draft",
+        description: "Delete an unsent draft and its attachments. Sent messages cannot be deleted.",
+        inputSchema: z.strictObject({ id: idSchema.describe("the draft to delete") }),
+        outputSchema: outputObject({ id: z.string(), deleted: z.boolean() }),
+        annotations: { ...SENDS, idempotentHint: true },
+    }, async ({ id }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        const draft = await caller.client.getMessage(id, signal);
+        if (draft.time !== null && draft.time !== undefined)
+            return toolError(`message ${id} was already sent and cannot be deleted`);
+        await caller.client.deleteMessage(draft.id, signal);
+        return ok(`Deleted draft ${draft.id}.`, { id: draft.id, deleted: true });
+    }));
+};

package/dist/tools/identity.js

@@ -48,7 +48,7 @@ export const registerIdentityTools = (server, deps) => {
     // Describe only the resolution steps this deployment has; both are operator settings.
     const steps = [
         ...(Object.keys(deps.config.directory ?? {}).length ? ["otherwise an entry in the operator-configured directory of short names"] : []),
-        ...(deps.config.defaultDomain === CALLER_DOMAIN ? ["otherwise @name@<your domain>, the domain of the address you act as"]
+        ...(deps.config.defaultDomain === CALLER_DOMAIN ? ["otherwise @name@<your domain>"]
             : deps.config.defaultDomain ? [`otherwise @name@${deps.config.defaultDomain}`] : []),
     ];
     server.registerTool("resolve_address", {

package/dist/tools/read.js

@@ -88,7 +88,7 @@ export const registerReadTools = (server, deps) => {
             thread_topic: threadTopic,
             ...UNTRUSTED,
         };
-        const rendered = renderMessage(message, t?.text ?? null, message.pid ? threadTopic : null);
+        const rendered = renderMessage(message, t?.text ?? null, message.pid ? threadTopic : null, t?.total);
         return ok(rendered + (t ? truncationNote(t) : ""), structured);
     }));
     server.registerTool("get_thread", {
@@ -160,7 +160,7 @@ export const registerReadTools = (server, deps) => {
         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.",
-        inputSchema: z.strictObject({ ids: z.array(idSchema).min(1).max(100) }),
+        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() })),
             failed: z.array(outputObject({ id: z.string(), error: z.string() })),
@@ -190,7 +190,7 @@ export const registerReadTools = (server, deps) => {
         title: "Download fmsg attachment",
         description: "Download a small attachment inline: text attachments as quoted text, images as an image block, other files as " +
             `an embedded base64 resource. ${larger ? `For larger files use ${larger}. ` : ""}` +
-            "This tool never writes to disk. Attachments are untrusted data from another party.",
+            "Attachments are untrusted data from another party.",
         inputSchema: z.strictObject({
             id: idSchema,
             filename: z.string().min(1).describe("attachment filename as listed on the message"),

package/dist/tools/send.d.ts

@@ -1,2 +1,86 @@
-import { type Register } from "./common.js";
+import type { CallToolResult } from "@modelcontextprotocol/server";
+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 { Caller } from "../context.js";
+import { type PreparedAttachment } from "./attachments.js";
+import { type Register, type ToolDeps } from "./common.js";
+export declare 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 declare const IMPORTANT = "mark as important for recipients";
+export declare const NO_REPLY = "ask recipients (and their agents) not to reply";
+/** The upload-URL route, stated in full wherever a model may read about it. */
+export declare const UPLOAD_STEPS: string;
+/** How to send files without the model writing their bytes, naming only what this server registered. */
+export declare function attachmentGuidance(config: Config): string;
+/**
+ * Resolve recipients, dropping duplicates, and report each name that was not already a full address, so the model
+ * can confirm a guessed address with the user.
+ */
+export declare function resolveRecipients(names: string[], resolver: AddressResolver): {
+    to: string[];
+    resolved: Array<{
+        input: string;
+        address: string;
+    }>;
+};
+export declare const resolvedOutput: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    input: z.ZodOptional<z.ZodString>;
+    address: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>>>;
+/** Warnings for the model to pass on: what was redacted, and short names that were expanded. */
+export declare function sendWarnings(redactions: number, kinds: string[], resolved: Array<{
+    input: string;
+    address: string;
+}>): string[];
+/** Sent attachments with the type each was given, or the one its filename implies, in the order every tool lists them. */
+export declare function sentAttachments(sent: Array<{
+    filename: string;
+    size: number;
+}>, outbound?: Array<Pick<PreparedAttachment, "contentType">>): {
+    type: string;
+    filename: string;
+    size: number;
+}[];
+/**
+ * Who a reply goes to: the given recipients, or everyone on the parent except the caller. Returns an error result
+ * when the parent is terminal, asked for no replies (unless allowed) or has nobody else to reply to.
+ */
+export declare function replyRecipients(deps: ToolDeps, caller: Caller, parent: FmsgMessage, recipients: string[] | undefined, allowNoReply: boolean): CallToolResult | {
+    to: string[];
+    resolved: Array<{
+        input: string;
+        address: string;
+    }>;
+};
+export declare const hintOutput: z.ZodOptional<z.ZodString>;
+export declare const sentOutput: z.ZodObject<{
+    id: z.ZodString;
+    time: z.ZodNullable<z.ZodString>;
+    from: z.ZodString;
+    to: z.ZodArray<z.ZodString>;
+    topic: z.ZodString;
+    parent_id: z.ZodNullable<z.ZodString>;
+    attachments: z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        size: z.ZodNumber;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    redactions: z.ZodNumber;
+    redacted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resolved: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        input: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    warnings: z.ZodArray<z.ZodString>;
+    thread_topic: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** The result text with a hint for the model appended, when there is one. */
+export declare function withHint(text: string, hint: string | undefined): string;
+export declare function redactionNote(count: number, kinds: string[]): string;
+export declare function resolvedNote(resolved: Array<{
+    input: string;
+    address: string;
+}>): string;
 export declare const registerSendTools: Register;

package/dist/tools/send.js

@@ -2,21 +2,31 @@ import * as z from "zod/v4";
 import { resolveAddress, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
 import { addressList, addressText, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.js";
+import { attachmentInput, base64Hint, fileRoutes, prepareAttachments, sendWithAttachments } from "./attachments.js";
 import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.js";
 import { rootTopic } from "./read.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.strictObject({
-    filename: z.string().regex(/^[A-Za-z0-9._-]+$/u, "letters, digits, dot, underscore, hyphen only").describe("file name"),
-    data_base64: z.string().min(1).describe("base64 contents; the host sets the size limit"),
-    content_type: z.string().optional().describe("inferred from the filename when omitted"),
-});
-const IMPORTANT = "mark as important for recipients";
-const NO_REPLY = "ask recipients (and their agents) not to reply";
+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";
+/** The upload-URL route, stated in full wherever a model may read about it. */
+export const UPLOAD_STEPS = "PUT each file's raw bytes to the draft's upload URL with this connection's Authorization header, then call " +
+    "send_draft. If your host cannot send this connection's credentials, use data_base64; never look for or copy credentials";
+/** How to send files without the model writing their bytes, naming only what this server registered. */
+export function attachmentGuidance(config) {
+    const routes = fileRoutes(config);
+    const large = [
+        ...(routes.uploadUrl ? [`use create_draft instead: ${UPLOAD_STEPS}`] : []),
+        ...(routes.uploadFolder ? ["give path, a file in the upload folder"] : []),
+    ];
+    return "Files: data_text for text, data_base64 for small files; add sha256 when you can. " +
+        (large.length ? `For large files, ${large.join(". Or ")}. ` : "") +
+        "Send files as they are; fmsg compresses them.";
+}
 /**
  * Resolve recipients, dropping duplicates, and report each name that was not already a full address, so the model
  * can confirm a guessed address with the user.
  */
-function resolveRecipients(names, resolver) {
+export function resolveRecipients(names, resolver) {
     const to = [];
     const resolved = [];
     for (const name of names) {
@@ -28,9 +38,9 @@ function resolveRecipients(names, resolver) {
     }
     return { to, resolved };
 }
-const resolvedOutput = z.array(outputObject({ input: z.string().optional(), address: z.string().optional() })).optional().describe("short names and how they resolved, when any were given; confirm with the user if an address looks wrong");
+export const resolvedOutput = z.array(outputObject({ input: z.string().optional(), address: z.string().optional() })).optional().describe("short names and how they resolved, when any were given; confirm with the user if an address looks wrong");
 /** Warnings for the model to pass on: what was redacted, and short names that were expanded. */
-function sendWarnings(redactions, kinds, resolved) {
+export function sendWarnings(redactions, kinds, resolved) {
     const warnings = [];
     if (redactions)
         warnings.push(`Tell the user ${redactions} secret(s) (${kinds.join(", ")}) were replaced with placeholders before sending.`);
@@ -39,18 +49,29 @@ function sendWarnings(redactions, kinds, resolved) {
     return warnings;
 }
 /** 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) {
+export function sentAttachments(sent, outbound = []) {
     return sortAttachments(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");
-        if (data.byteLength === 0)
-            throw new Error(`attachment ${a.filename} is empty or not valid base64`);
-        return { filename: a.filename, data: new Uint8Array(data), ...(a.content_type ? { contentType: a.content_type } : {}) };
-    });
+/**
+ * Who a reply goes to: the given recipients, or everyone on the parent except the caller. Returns an error result
+ * when the parent is terminal, asked for no replies (unless allowed) or has nobody else to reply to.
+ */
+export function replyRecipients(deps, caller, parent, recipients, allowNoReply) {
+    const id = parent.id;
+    if (parent.terminal)
+        return toolError(`message ${id} is terminal and cannot be replied to`);
+    if (parent.no_reply && !allowNoReply) {
+        return toolError(`message ${id} is marked no-reply; pass allow_no_reply: true only if the user explicitly wants to reply anyway`);
+    }
+    const result = recipients?.length
+        ? resolveRecipients(recipients, resolverFor(deps, caller))
+        : { to: participantsOf(parent).filter((a) => !sameAddress(a, caller.address)), resolved: [] };
+    if (result.to.length === 0)
+        return toolError(`message ${id} has no other participants to reply to; pass recipients`);
+    return result;
 }
-const sentOutput = outputObject({
+export const hintOutput = z.string().optional().describe("for you, not the user: a better way to do this next time");
+export const sentOutput = outputObject({
     id: z.string(),
     time: z.string().nullable(),
     from: z.string(),
@@ -63,20 +84,28 @@ const sentOutput = outputObject({
     resolved: resolvedOutput,
     warnings: z.array(z.string()).describe("things to tell the user, such as redacted secrets or resolved short names"),
     thread_topic: z.string().nullable().optional().describe("the thread's topic: the topic sent for a new message; for a reply, the thread root's topic, or null when the root is not visible"),
+    hint: hintOutput,
 });
-function redactionNote(count, kinds) {
+/** The result text with a hint for the model appended, when there is one. */
+export function withHint(text, hint) {
+    return hint ? `${text}\n\n${hint}` : text;
+}
+export function redactionNote(count, kinds) {
     return count ? `. ${count} secret(s) were redacted before sending (${kinds.join(", ")}).` : ".";
 }
-function resolvedNote(resolved) {
+export function resolvedNote(resolved) {
     return resolved.length ? ` Short names resolved: ${resolved.map((r) => `${r.input} → ${addressText(r.address)}`).join(", ")}.` : "";
 }
 export const registerSendTools = (server, deps) => {
+    const attachments = z.array(attachmentInput(deps.config)).optional().describe("files");
+    const guidance = attachmentGuidance(deps.config);
+    const routes = fileRoutes(deps.config);
     server.registerTool("send_message", {
         title: "Send new fmsg message",
         description: `Send a new message immediately, starting a new thread. ${IMMUTABLE} ` +
             "Recipients may be full @user@domain addresses or resolvable short names. The body is Markdown by default. " +
             "Secrets are redacted. If the host rejects the message its reason is returned verbatim. " +
-            "To continue an existing conversation use reply instead.",
+            `To continue an existing conversation use reply instead. ${guidance}`,
         inputSchema: z.strictObject({
             to: z.array(z.string()).min(1).describe("recipient addresses (@user@domain) or short names"),
             topic: z.string().max(256).describe("thread topic (subject) — immutable once sent"),
@@ -84,23 +113,15 @@ export const registerSendTools = (server, deps) => {
             type: z.string().default("text/markdown; charset=utf-8").describe("body media type"),
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
-            attachments: z.array(attachmentInput).optional().describe("files"),
+            attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
     }, async ({ to, topic, body, type, important, no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const { to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller));
-        const outbound = decodeAttachments(attachments);
-        const sent = await caller.client.send({
-            to: recipients,
-            topic,
-            body,
-            type,
-            important,
-            noReply: no_reply,
-            attachments: outbound,
-            signal,
-        });
+        const outbound = await prepareAttachments(attachments, deps.config);
+        const hint = base64Hint(attachments, routes);
+        const sent = await sendWithAttachments(caller.client, { to: recipients, topic, body, type, important, noReply: no_reply }, outbound, signal);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -114,18 +135,19 @@ export const registerSendTools = (server, deps) => {
             ...(resolved.length ? { resolved } : {}),
             warnings: sendWarnings(sent.redactions, sent.redacted, resolved),
             thread_topic: sent.topic,
+            ...(hint ? { hint } : {}),
         };
         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(", ")}` : "") +
             redactionNote(structured.redactions, structured.redacted) + resolvedNote(resolved);
-        return ok(text, structured);
+        return ok(withHint(text, hint), structured);
     }));
     server.registerTool("reply", {
         title: "Reply in fmsg thread",
         description: `Send an immediate reply to a message (linking it into that thread). ${IMMUTABLE} ` +
             "By default the reply goes to everyone on the parent message — its sender, recipients and anyone added later — " +
             "except you; pass recipients to narrow or widen that. Fails if the parent is terminal (no replies possible); " +
-            "a parent marked no-reply is refused unless allow_no_reply is true. Secrets are redacted.",
+            `a parent marked no-reply is refused unless allow_no_reply is true. Secrets are redacted. ${guidance}`,
         inputSchema: z.strictObject({
             id: idSchema.describe("message to reply to"),
             body: z.string().describe("reply body; Markdown unless type says otherwise"),
@@ -134,33 +156,19 @@ export const registerSendTools = (server, deps) => {
             important: z.boolean().default(false).describe(IMPORTANT),
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             allow_no_reply: z.boolean().default(false).describe("reply even though the parent asked for no replies"),
-            attachments: z.array(attachmentInput).optional().describe("files"),
+            attachments,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
     }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const parent = await caller.client.getMessage(id, signal);
-        if (parent.terminal)
-            return toolError(`message ${id} is terminal and cannot be replied to`);
-        if (parent.no_reply && !allow_no_reply) {
-            return toolError(`message ${id} is marked no-reply; pass allow_no_reply: true only if the user explicitly wants to reply anyway`);
-        }
-        const { to, resolved } = recipients?.length
-            ? resolveRecipients(recipients, resolverFor(deps, caller))
-            : { to: participantsOf(parent).filter((a) => !sameAddress(a, caller.address)), resolved: [] };
-        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,
-            body,
-            type,
-            important,
-            noReply: no_reply,
-            attachments: outbound,
-            signal,
-        });
+        const target = replyRecipients(deps, caller, parent, recipients, allow_no_reply);
+        if ("content" in target)
+            return target;
+        const { to, resolved } = target;
+        const outbound = await prepareAttachments(attachments, deps.config);
+        const hint = base64Hint(attachments, routes);
+        const sent = await sendWithAttachments(caller.client, { to, pid: parent.id, body, type, important, noReply: no_reply }, outbound, signal);
         const structured = {
             id: sent.id,
             time: isoTime(sent.time),
@@ -175,11 +183,12 @@ export const registerSendTools = (server, deps) => {
             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),
+            ...(hint ? { hint } : {}),
         };
         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 ?? "?"}` +
             redactionNote(structured.redactions, structured.redacted) + resolvedNote(resolved);
-        return ok(text, structured);
+        return ok(withHint(text, hint), structured);
     }));
     server.registerTool("add_recipients", {
         title: "Add fmsg recipients",

package/dist/upload.d.ts

@@ -0,0 +1,18 @@
+export declare const UPLOAD_PATH = "/mcp/drafts";
+/** Content-Encoding values accepted on uploads; decoded before the bytes reach fmsg. */
+export declare const UPLOAD_ENCODINGS: readonly ["gzip", "deflate"];
+export declare const CHECKSUM_HEADER = "x-content-sha256";
+/** The PUT target for one draft's attachments, with `{filename}` left for the host to fill in. */
+export declare function draftUploadUrlTemplate(baseUrl: string, id: string): string;
+export declare function parseUploadPath(pathname: string): {
+    id: string;
+    filename: string;
+};
+/** The upload request's own body was unusable (such as invalid compressed data); answered with 400. */
+export declare class UploadBodyError extends Error {
+    constructor(message: string);
+}
+/** Decode a Content-Encoding while streaming, reporting corrupt data as UploadBodyError. */
+export declare function decodedUploadBody(body: ReadableStream<Uint8Array>, encoding: string | undefined): ReadableStream<Uint8Array>;
+/** The upload's Content-Encoding, lowercased; "identity" or none means undecoded. Throws for an unsupported one. */
+export declare function uploadEncoding(header: string | null): string | undefined;

package/dist/upload.js

@@ -0,0 +1,57 @@
+import { normalizeMessageId } from "./client/message-id.js";
+import { FILENAME } from "./tools/attachments.js";
+export const UPLOAD_PATH = "/mcp/drafts";
+/** Content-Encoding values accepted on uploads; decoded before the bytes reach fmsg. */
+export const UPLOAD_ENCODINGS = ["gzip", "deflate"];
+export const CHECKSUM_HEADER = "x-content-sha256";
+/** The PUT target for one draft's attachments, with `{filename}` left for the host to fill in. */
+export function draftUploadUrlTemplate(baseUrl, id) {
+    return `${baseUrl.replace(/\/$/u, "")}/drafts/${normalizeMessageId(id)}/attachments/{filename}`;
+}
+export function parseUploadPath(pathname) {
+    const parts = pathname.slice(UPLOAD_PATH.length + 1).split("/");
+    if (parts.length !== 3 || parts[1] !== "attachments")
+        throw new Error("invalid attachment upload path");
+    const filename = decodeURIComponent(parts[2]);
+    if (!FILENAME.test(filename) || /^\.+$/u.test(filename))
+        throw new Error("invalid attachment upload filename");
+    return { id: normalizeMessageId(parts[0]), filename };
+}
+/** The upload request's own body was unusable (such as invalid compressed data); answered with 400. */
+export class UploadBodyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UploadBodyError";
+    }
+}
+/** Decode a Content-Encoding while streaming, reporting corrupt data as UploadBodyError. */
+export function decodedUploadBody(body, encoding) {
+    if (!encoding)
+        return body;
+    const reader = body.pipeThrough(new DecompressionStream(encoding)).getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (error) {
+                throw new UploadBodyError(`the ${encoding} request body is invalid or truncated: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (chunk.done)
+                controller.close();
+            else
+                controller.enqueue(chunk.value);
+        },
+        cancel: (reason) => reader.cancel(reason),
+    });
+}
+/** The upload's Content-Encoding, lowercased; "identity" or none means undecoded. Throws for an unsupported one. */
+export function uploadEncoding(header) {
+    const value = header?.trim().toLowerCase();
+    if (!value || value === "identity")
+        return undefined;
+    if (!UPLOAD_ENCODINGS.includes(value))
+        throw new Error(`unsupported Content-Encoding ${JSON.stringify(header)}; use ${UPLOAD_ENCODINGS.join(" or ")}, or none`);
+    return value;
+}

package/docs/http-deployment.md

@@ -31,7 +31,7 @@ Save this as `Caddyfile`:
 
 ```caddyfile
 mcp.example.com {
-    @fmsg path /mcp /mcp/attachments/* /.well-known/oauth-protected-resource /.well-known/oauth-protected-resource/*
+    @fmsg path /mcp /mcp/* /.well-known/oauth-protected-resource /.well-known/oauth-protected-resource/*
     handle @fmsg {
         reverse_proxy 127.0.0.1:8765 {
             transport http {
@@ -85,7 +85,7 @@ Set `FMSG_MCP_PUBLIC_URL` to the exact external MCP endpoint when using API keys
 to `FMSG_MCP_OAUTH_RESOURCE_URL`; if both are set, they must match. These URLs require HTTPS outside
 loopback and cannot contain credentials, queries or fragments. Request Host and forwarded headers
 never select the download URL. If the proxy exposes MCP under a different public path, map that
-path and its `/attachments/*` suffix to `/mcp` and `/mcp/attachments/*` respectively.
+path and everything under it to `/mcp` and `/mcp/*` respectively.
 
 Downloads use the original MIME type, `Content-Disposition: attachment`, Unicode filename encoding,
 `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`. The body streams with backpressure;
@@ -94,7 +94,39 @@ truncated file. No temporary server files, signed URLs or tokens in query string
 Range/resume requests are not implemented: GET returns the full file. Treat a failed transfer as
 incomplete and discard its partial local output before retrying.
 
-Host and Origin validation applies to downloads too. Allowed browser clients can preflight GET
+## Attachment uploads
+
+`create_draft` returns an upload URL template such as
+`https://mcp.example.com/mcp/drafts/123/attachments/{filename}`. A host that can send the MCP
+connection's Authorization header PUTs the raw file bytes there, then calls `send_draft`:
+
+```sh
+curl -X PUT -H "Authorization: Bearer $TOKEN" \
+  -H "x-content-sha256: $(sha256sum report.pdf | cut -c1-64)" \
+  --data-binary @report.pdf https://mcp.example.com/mcp/drafts/123/attachments/report.pdf
+```
+
+The server streams the body straight into the fmsg draft (`POST /fmsg/:id/attach`) without
+storing it, so the draft and its attachments are visible in the user's other fmsg clients and the
+fmsg host's own size limits apply; its refusal comes back with its status and text. OAuth requires
+`fmsg:write`. The response is `201` with `filename`, `size`, `sha256` and `type`. The fmsg host may
+rename a duplicate filename; the response gives the stored name.
+
+- `x-content-sha256` (optional, hex): a mismatch answers `422`, and the attachment is removed again.
+- `Content-Encoding: gzip` or `deflate` (optional): the server decodes the body while streaming, so
+  fmsg stores the original file; `size` and `sha256` describe the decoded bytes. Other encodings
+  answer `415`; corrupt or truncated compressed data answers `400` and nothing is kept.
+- The file's type comes from `Content-Type`, except that `application/x-www-form-urlencoded`
+  (curl's default for `--data-binary`) and `application/octet-stream` are replaced by the type the
+  filename implies.
+
+Uploads have no total time limit: each chunk resets a 60-second idle timeout, as for downloads.
+Other requests must arrive in full within 60 seconds. Upload connections close after the response.
+The server does the proxying to the fmsg host itself: a TLS proxy that forwards `/mcp/*`, like the
+Caddy example above, needs no upload-specific settings. Proxies that cap request bodies by default
+(nginx's `client_max_body_size` is 1 MB) should not cap them below the fmsg host's attachment limit.
+
+Host and Origin validation applies to downloads and uploads too. Allowed browser clients can preflight GET
 with Authorization and read Content-Disposition. Hosts must attach the connection credential
 themselves; never ask the model to locate or copy tokens. Clients that cannot fetch authenticated
 links can still use `download_attachment` inline. Compatibility of authenticated links with each