@markmnl/fmsg-mcp 1.0.0 → 1.1.1

package/dist/http.js

@@ -4,10 +4,14 @@ import { createMcpHandler, hostHeaderValidationResponse, localhostAllowedHostnam
 import { ApiKeyCallerProvider, FMSG_SCOPE } from "./auth.js";
 import { createFmsgMcpServer } from "./server.js";
 import { OAuthCallerProvider } from "./oauth/provider.js";
-import { invalidToken, insufficientScope, OAuthRequestError, oauthErrorResponse, oauthRequestState } from "./oauth/errors.js";
-import { MESSAGING_SCOPES, READ_SCOPE, requestScopes } from "./oauth/scopes.js";
+import { invalidToken, insufficientScope, missingToken, OAuthRequestError, oauthErrorResponse, oauthRequestState } from "./oauth/errors.js";
+import { MESSAGING_SCOPES, READ_SCOPE, WRITE_SCOPE, requestScopes } from "./oauth/scopes.js";
 import { DOWNLOAD_PATH, downloadBaseUrl, downloadHeaders, parseDownloadPath } from "./download.js";
+import { CHECKSUM_HEADER, UPLOAD_DRAIN_IDLE_MS, UPLOAD_PATH, UploadBodyError, decodedUploadBody, drainableBody, parseUploadPath, uploadEncoding } from "./upload.js";
+import { AttachmentChecksumError, UploadInterruptedError } from "./client/client.js";
 import { FmsgHttpError } from "./client/errors.js";
+import { sameAddress } from "./address.js";
+import { attachmentType } from "./render.js";
 import { describeError } from "./errors.js";
 import { VERSION } from "./version.js";
 import { safeErrorMessage } from "./client/redact.js";
@@ -16,7 +20,10 @@ export const MCP_PATH = "/mcp";
 /** How long close() lets in-flight requests finish (waits end at once) before cutting them off. */
 export const SHUTDOWN_GRACE_MS = 5000;
 const CORS_METHODS = ["POST", "GET", "DELETE"];
-const CORS_HEADERS = ["authorization", "content-type", "accept", "mcp-protocol-version", "mcp-method", "mcp-name", "mcp-session-id", "last-event-id"];
+const CORS_HEADERS = ["authorization", "content-type", "accept", "mcp-protocol-version", "mcp-method", "mcp-name", "mcp-session-id", "last-event-id",
+    "content-encoding", CHECKSUM_HEADER];
+/** How long a request other than an attachment upload may take to arrive in full. Uploads use an idle budget instead. */
+export const REQUEST_BODY_TIMEOUT_MS = 60_000;
 // Combined mode routes only fmsg API keys to API-key authentication; everything else is OAuth.
 const API_KEY_BEARER = /^Bearer fmsgk_/iu;
 /** Convert a Node request into a web-standard Request for the MCP handler. */
@@ -98,6 +105,18 @@ export async function sendWebResponse(res, response, failure) {
             res.end();
     }
 }
+/**
+ * After the host cut off an upload, the reason it gave is lost; say why when the draft shows it. A failed lookup
+ * throws the host's own error, such as a draft the caller cannot see.
+ */
+async function draftRefusal(caller, id, signal) {
+    const draft = await caller.client.getMessage(id, signal);
+    if (draft.time !== null && draft.time !== undefined)
+        return `message ${id} was already sent; attachments can be added only to drafts`;
+    if (!sameAddress(draft.from, caller.address))
+        return `message ${id} is not your draft; only its sender can add attachments`;
+    return undefined;
+}
 export function createHttpServer(config, log = (l) => console.error(l)) {
     const allowedHosts = config.http.allowedHosts.length
         ? config.http.allowedHosts
@@ -135,8 +154,16 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         const abort = () => controller.abort();
         req.once("aborted", abort);
         res.once("close", abort);
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const isUpload = url.pathname.startsWith(`${UPLOAD_PATH}/`);
+        // A progressing upload may take longer than any fixed budget; the upload stream has an idle timeout instead.
+        // Closing the connection afterwards stops Node reading the rest of an upload refused before authentication;
+        // an authenticated caller's failed upload is drained first so its answer arrives (see serveUpload).
+        const bodyTimer = isUpload ? undefined : setTimeout(() => { if (!req.complete)
+            req.destroy(); }, REQUEST_BODY_TIMEOUT_MS).unref();
+        if (isUpload)
+            res.setHeader("connection", "close");
         const done = (async () => {
-            const url = new URL(req.url ?? "/", "http://localhost");
             const isDownload = url.pathname.startsWith(`${DOWNLOAD_PATH}/`);
             if (url.pathname === "/healthz") {
                 res.writeHead(200, { "content-type": "application/json" });
@@ -156,7 +183,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     authorization_servers: [config.oauth.issuerUrl], scopes_supported: MESSAGING_SCOPES,
                     bearer_methods_supported: ["header"], resource_name: "fmsg messaging", }, { headers }));
             }
-            if (url.pathname !== MCP_PATH && !isDownload) {
+            if (url.pathname !== MCP_PATH && !isDownload && !isUpload) {
                 res.writeHead(404, { "content-type": "text/plain" });
                 res.end("not found; the MCP endpoint is /mcp");
                 return;
@@ -188,7 +215,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             if (req.method === "OPTIONS") {
                 const method = request.headers.get("access-control-request-method") ?? "";
                 const headers = (request.headers.get("access-control-request-headers") ?? "").split(",").map((v) => v.trim().toLowerCase()).filter(Boolean);
-                const methods = isDownload ? ["GET"] : CORS_METHODS;
+                const methods = isDownload ? ["GET"] : isUpload ? ["PUT"] : CORS_METHODS;
                 if (!origin || !methods.includes(method) || headers.some((h) => !CORS_HEADERS.includes(h))) {
                     return sendWebResponse(res, new Response("preflight not allowed", { status: 403 }));
                 }
@@ -210,20 +237,81 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                     return sendWebResponse(res, new Response("invalid attachment download path", { status: 400 }));
                 }
             }
-            const serveDownload = async (provider, auth) => {
-                let caller;
+            let upload;
+            if (isUpload) {
+                // Refusals are JSON, like the errors from the upload itself.
+                const uploadRefusal = (error, status, headers = {}) => sendWebResponse(res, Response.json({ error }, { status, headers }));
+                if (req.method !== "PUT")
+                    return uploadRefusal("use PUT to upload attachments", 405, { allow: "PUT, OPTIONS" });
+                if (url.search)
+                    return uploadRefusal("attachment URLs must not contain query parameters", 400);
                 try {
-                    caller = await provider.forRequest(auth);
-                    const { stream, contentType } = await caller.client.streamAttachment(download.id, download.filename, controller.signal);
-                    let response;
-                    try {
-                        response = new Response(stream, { headers: downloadHeaders(download.filename, contentType) });
+                    upload = { ...parseUploadPath(url.pathname), contentType: "" };
+                }
+                catch {
+                    return uploadRefusal("invalid attachment upload path; use /mcp/drafts/{id}/attachments/{filename}", 400);
+                }
+                try {
+                    upload.encoding = uploadEncoding(request.headers.get("content-encoding"));
+                }
+                catch (error) {
+                    return uploadRefusal(error.message, 415);
+                }
+                const sha256 = request.headers.get(CHECKSUM_HEADER)?.trim();
+                if (sha256 !== undefined) {
+                    if (!/^[0-9A-Fa-f]{64}$/u.test(sha256))
+                        return uploadRefusal(`${CHECKSUM_HEADER} must be 64 hexadecimal characters`, 400);
+                    upload.sha256 = sha256.toLowerCase();
+                }
+                // curl and similar tools label raw bodies as form data by default; that says nothing about the file.
+                const declared = request.headers.get("content-type")?.trim();
+                if (declared && !/^[\x20-\x7e]+$/u.test(declared))
+                    return uploadRefusal("Content-Type must be printable ASCII", 400);
+                upload.contentType = declared && !/^application\/x-www-form-urlencoded\b/iu.test(declared)
+                    ? attachmentType(upload.filename, declared) : attachmentType(upload.filename);
+            }
+            const serveDownload = (provider, auth) => serveTransfer(provider, auth, READ_SCOPE, async (caller) => {
+                const { stream, contentType } = await caller.client.streamAttachment(download.id, download.filename, controller.signal);
+                let response;
+                try {
+                    response = new Response(stream, { headers: downloadHeaders(download.filename, contentType) });
+                }
+                catch (error) {
+                    await stream.cancel().catch(() => undefined);
+                    throw error;
+                }
+                return sendWebResponse(res, response);
+            });
+            const serveUpload = (provider, auth) => serveTransfer(provider, auth, WRITE_SCOPE, async (caller) => {
+                const { stream, drain } = drainableBody(request.body ?? new ReadableStream({ start: (c) => c.close() }), UPLOAD_DRAIN_IDLE_MS);
+                const body = decodedUploadBody(stream, upload.encoding);
+                let uploaded;
+                try {
+                    uploaded = await caller.client.uploadAttachmentStream(upload.id, {
+                        filename: upload.filename, stream: body, contentType: upload.contentType, ...(upload.sha256 ? { expectedSha256: upload.sha256 } : {}),
+                    }, controller.signal);
+                }
+                catch (error) {
+                    // Answering while the client is still sending would close the connection with unread data, resetting it
+                    // and losing the answer; the caller is authenticated and could send these bytes to its own draft anyway.
+                    if (!(await drain())) {
+                        res.destroy();
+                        return;
                     }
-                    catch (error) {
-                        await stream.cancel().catch(() => undefined);
+                    if (!(error instanceof UploadInterruptedError))
                         throw error;
-                    }
-                    return await sendWebResponse(res, response);
+                    const refusal = await draftRefusal(caller, upload.id, controller.signal).catch((lookup) => { throw lookup instanceof FmsgHttpError ? lookup : error; });
+                    if (refusal === undefined)
+                        throw error;
+                    return sendWebResponse(res, Response.json({ error: refusal }, { status: 403 }));
+                }
+                return sendWebResponse(res, Response.json({ id: upload.id, ...uploaded, type: upload.contentType }, { status: 201 }));
+            });
+            const serveTransfer = async (provider, auth, scope, transfer) => {
+                let caller;
+                try {
+                    caller = await provider.forRequest(auth);
+                    return await transfer(caller);
                 }
                 catch (error) {
                     const rejectedAuth = (error instanceof OAuthRequestError && error.status === 401) ||
@@ -242,10 +330,11 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                         if (rejectedAuth)
                             return sendWebResponse(res, oauthErrorResponse(invalidToken(), metadataUrl));
                         if (error instanceof FmsgHttpError && error.insufficientScope) {
-                            return sendWebResponse(res, oauthErrorResponse(new OAuthRequestError(403, "insufficient_scope", error.message, [READ_SCOPE]), metadataUrl));
+                            return sendWebResponse(res, oauthErrorResponse(new OAuthRequestError(403, "insufficient_scope", error.message, [scope]), metadataUrl));
                         }
                     }
-                    const status = rejectedAuth ? 401 : error instanceof FmsgHttpError && error.status >= 400 && error.status <= 599 ? error.status : 502;
+                    const status = rejectedAuth ? 401 : error instanceof AttachmentChecksumError ? 422 : error instanceof UploadBodyError ? 400
+                        : error instanceof FmsgHttpError && error.status >= 400 && error.status <= 599 ? error.status : 502;
                     const challenge = `Bearer error="invalid_token"${resource ? `, resource_metadata=${JSON.stringify(metadataUrl)}` : ""}`;
                     return sendWebResponse(res, Response.json({ error: describeError(error) }, {
                         status, headers: status === 401 ? { "www-authenticate": challenge } : {},
@@ -257,7 +346,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                 try {
                     const bearer = /^Bearer ([A-Za-z0-9._~+\/-]+=*)$/iu.exec(authorization);
                     if (!bearer)
-                        throw invalidToken();
+                        throw authorization ? invalidToken() : missingToken();
                     const authenticated = await oauthProvider.verifyAccessToken(bearer[1]);
                     release = () => oauthProvider.release(authenticated);
                     let parsedBody;
@@ -271,11 +360,13 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                         if (Array.isArray(parsedBody))
                             return sendWebResponse(res, new Response("MCP batch requests are not supported", { status: 400 }));
                     }
-                    const scopes = download ? [READ_SCOPE] : requestScopes(parsedBody);
+                    const scopes = download ? [READ_SCOPE] : upload ? [WRITE_SCOPE] : requestScopes(parsedBody);
                     if (scopes.some(scope => !authenticated.scopes.includes(scope)))
                         throw insufficientScope(scopes);
                     if (download)
                         return await serveDownload(oauthProvider, authenticated);
+                    if (upload)
+                        return await serveUpload(oauthProvider, authenticated);
                     // Discover/list operations only need the incoming JWT. Resolve an
                     // exchanged credential before starting any protected tool response.
                     if (scopes.length) {
@@ -314,6 +405,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
                 return sendWebResponse(res, auth);
             if (download)
                 return serveDownload(apiKeyProvider, auth);
+            if (upload)
+                return serveUpload(apiKeyProvider, auth);
             return sendWebResponse(res, await apiKeyHandler.fetch(request, { authInfo: auth }));
         })().catch((error) => {
             safeLog(`request failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -326,6 +419,7 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
             res.writeHead(500, { "content-type": "text/plain" });
             res.end("internal error");
         }).finally(() => {
+            clearTimeout(bodyTimer);
             release?.();
             active.delete(controller);
             req.off("aborted", abort);
@@ -333,8 +427,8 @@ export function createHttpServer(config, log = (l) => console.error(l)) {
         });
         active.set(controller, { res, done });
     });
-    // This bounds receiving the request body, not the duration of a wait response.
-    server.requestTimeout = 60_000;
+    // Request bodies are bounded per request above (REQUEST_BODY_TIMEOUT_MS, or the upload idle budget).
+    server.requestTimeout = 0;
     server.headersTimeout = 60_000;
     server.keepAliveTimeout = 65_000;
     let closing;

package/dist/instructions.d.ts

@@ -1,7 +1,10 @@
+import type { FileRoutes } from "./tools/attachments.js";
 export type InstructionsContext = {
     /** The address this server acts as, when already known (HTTP callers; stdio after a token exchange). */
     address?: string;
     /** FMSG_DEFAULT_DOMAIN: a domain, or CALLER_DOMAIN for the caller's own domain. */
     defaultDomain?: string;
+    /** Large-file routes this server offers; none when omitted. */
+    files?: FileRoutes;
 };
 export declare function buildInstructions(ctx?: InstructionsContext): string;

package/dist/instructions.js

@@ -2,11 +2,19 @@
  * Server instructions: returned in the MCP `initialize` result and folded into
  * the model's system prompt by hosts that support them (some chat hosts do not, so
  * nothing a tool needs may live only here). Rules that span tools, each stated once:
- * which address this server acts as, the fmsg terms, the inbox routine, the
- * irreversible-send rule and untrusted content. Per-tool detail lives in the tool
+ * which address this server acts as, the fmsg terms, the inbox routine, how to
+ * send files, the irreversible-send rule and untrusted content. Per-tool detail lives in the tool
  * descriptions; situational guidance in results.
  */
 import { CALLER_DOMAIN, effectiveDefaultDomain } from "./address.js";
+/** How to send files, naming only the routes this server offers. */
+function filesParagraph(files) {
+    const large = [
+        ...(files?.uploadUrl ? ["create_draft, PUT each file to its upload URL, then send_draft"] : []),
+        ...(files?.uploadFolder ? ["give path, a file in the upload folder"] : []),
+    ];
+    return "Files: data_text for text, data_base64 for small files." + (large.length ? ` Large files: ${large.join("; or ")}.` : "");
+}
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address
         ? `you are acting as ${ctx.address}`
@@ -27,6 +35,7 @@ export function buildInstructions(ctx = {}) {
         "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.",
+        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 " +
             "when a decision is needed to resolve unclear intent, recipients or content.",

package/dist/oauth/errors.d.ts

@@ -14,5 +14,6 @@ export declare class OAuthRequestError extends Error {
     constructor(status: 401 | 403 | 500 | 503, code: string, message: string, scopes?: string[]);
 }
 export declare const invalidToken: () => OAuthRequestError;
+export declare const missingToken: () => OAuthRequestError;
 export declare const insufficientScope: (scopes: string[]) => OAuthRequestError;
 export declare function oauthErrorResponse(error: OAuthRequestError, metadataUrl: string): Response;

package/dist/oauth/errors.js

@@ -27,6 +27,7 @@ export class OAuthRequestError extends Error {
     }
 }
 export const invalidToken = () => new OAuthRequestError(401, "invalid_token", "The OAuth connection must be refreshed or reconnected.");
+export const missingToken = () => new OAuthRequestError(401, "invalid_token", "No access token was sent; send this MCP connection's Authorization header.");
 export const insufficientScope = (scopes) => new OAuthRequestError(403, "insufficient_scope", "The OAuth connection does not authorize this operation.", scopes);
 export function oauthErrorResponse(error, metadataUrl) {
     const headers = new Headers({ "cache-control": "no-store" });

package/dist/oauth/scopes.js

@@ -10,6 +10,7 @@ export const TOOL_SCOPES = {
     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],
+    create_draft: MESSAGING_SCOPES, send_draft: MESSAGING_SCOPES, delete_draft: MESSAGING_SCOPES,
 };
 export function parseScopes(value) {
     if (typeof value !== "string")

package/dist/prompts.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/server";
-export declare function registerPrompts(server: McpServer): void;
+import type { FileRoutes } from "./tools/attachments.js";
+export declare function registerPrompts(server: McpServer, routes: FileRoutes): void;

package/dist/prompts.js

@@ -1,5 +1,51 @@
 import * as z from "zod/v4";
-export function registerPrompts(server) {
+/** Steps for sending files, using the best route this server offers. */
+function sendFileSteps(routes, to, replyTo) {
+    const recipients = to ? `to ${to}, with a short topic` : "to the recipients I name (ask me if I have not)";
+    const draft = replyTo ? `with reply_to "${replyTo}"${to ? ` and to: ${to}` : ""}` : recipients;
+    const direct = replyTo ? `reply with id "${replyTo}"${to ? ` and recipients: ${to}` : ""}` : `send_message ${recipients}`;
+    const inline = "attach text files as data_text and small binary files as data_base64, each with its sha256 when you can compute it";
+    if (routes.uploadUrl) {
+        return [
+            `1. Call create_draft ${draft}; ${inline}.`,
+            "2. For each larger file, PUT its raw bytes to the draft's upload URL with your host's authenticated HTTP tools, " +
+                "sending its sha256 in x-content-sha256, and check each response's size and sha256. If your host cannot send this " +
+                "connection's credentials with its own requests, recreate the draft with the file as data_base64 instead; never look for or copy credentials.",
+            "3. Call send_draft with the draft id and tell me what was sent. If a step fails, call delete_draft unless I want to keep the draft.",
+        ];
+    }
+    if (routes.uploadFolder) {
+        return [
+            `1. Call ${direct}; ${inline}.`,
+            "2. Give each larger file as path, relative to the upload folder, instead of its data. A file outside the folder must be " +
+                "copied into it first; if you cannot, ask me to.",
+            "3. Tell me what was sent.",
+        ];
+    }
+    return [
+        `1. Call ${direct}; ${inline}.`,
+        "2. This server has no upload route, so every file is written inline: tell me first if a file is too large for that to be practical.",
+        "3. Tell me what was sent.",
+    ];
+}
+export function registerPrompts(server, routes) {
+    server.registerPrompt("send_file", {
+        title: "Send files over fmsg",
+        description: "Send files to fmsg recipients or as a reply, using the most efficient way this server accepts them.",
+        argsSchema: z.object({
+            files: z.string().describe("the files to send: paths, or a description of them"),
+            to: z.string().optional().describe("recipients, separated by commas"),
+            reply_to: z.string().optional().describe("message id to reply to instead of starting a thread"),
+            message: z.string().optional().describe("what the message should say"),
+        }),
+    }, ({ files, to, reply_to, message }) => {
+        const text = [
+            `Send these files over fmsg: ${files}.${message ? ` The message should say: ${message}` : " Write a short message saying what they are."}`,
+            "Send the files as they are, without zipping or re-encoding them; fmsg compresses them in transit.",
+            ...sendFileSteps(routes, to, reply_to),
+        ].join("\n");
+        return { messages: [{ role: "user", content: { type: "text", text } }] };
+    });
     server.registerPrompt("chat", {
         title: "Chat over fmsg",
         description: "Wait for incoming fmsg messages and reply on the user's behalf, once or continuously within a thread.",

package/dist/server.js

@@ -2,10 +2,12 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { buildInstructions } from "./instructions.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
+import { fileRoutes } from "./tools/attachments.js";
 import { registerIdentityTools } from "./tools/identity.js";
 import { registerListTools } from "./tools/list.js";
 import { registerReadTools } from "./tools/read.js";
 import { registerSendTools } from "./tools/send.js";
+import { registerDraftTools } from "./tools/draft.js";
 import { registerWaitTools } from "./tools/wait.js";
 import { registerSaveTool } from "./tools/save.js";
 import { registerDownloadTool } from "./tools/download.js";
@@ -19,6 +21,7 @@ export function createFmsgMcpServer(provider, config, options = {}) {
     const instructions = buildInstructions({
         ...(options.address ? { address: options.address } : {}),
         ...(config.defaultDomain ? { defaultDomain: config.defaultDomain } : {}),
+        files: fileRoutes(config),
     });
     const server = new McpServer({ name: SERVER_NAME, title: "fmsg", version: VERSION }, { instructions });
     const deps = { provider, config, ...(options.shutdown ? { shutdown: options.shutdown } : {}) };
@@ -28,8 +31,9 @@ export function createFmsgMcpServer(provider, config, options = {}) {
     registerSaveTool(server, deps);
     registerDownloadTool(server, deps);
     registerSendTools(server, deps);
+    registerDraftTools(server, deps);
     registerWaitTools(server, deps);
     registerResources(server, deps);
-    registerPrompts(server);
+    registerPrompts(server, fileRoutes(config));
     return server;
 }

package/dist/tools/attachments.d.ts

@@ -0,0 +1,66 @@
+import * as z from "zod/v4";
+import type { FmsgClient } from "../client/client.js";
+import type { Attachment, DraftInput, DraftResult } from "../client/types.js";
+import type { Config } from "../config.js";
+export declare const FILENAME: RegExp;
+/** Ways this server can take a file without the model writing its bytes. */
+export type FileRoutes = {
+    /** create_draft returns an HTTP upload URL (HTTP with a public MCP URL). */
+    uploadUrl: boolean;
+    /** Attachments may name a file in FMSG_MCP_UPLOAD_DIR (stdio). */
+    uploadFolder: boolean;
+};
+export declare function fileRoutes(config: Config): FileRoutes;
+/** A hint for the model after it wrote a large file as base64 although this server offers a route that avoids it. */
+export declare function base64Hint(items: AttachmentArgs[] | undefined, routes: FileRoutes): string | undefined;
+/** One outbound attachment as a tool argument: a filename and exactly one source of bytes. */
+export declare function attachmentInput(config: Config): z.ZodObject<{
+    content_type: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    path?: z.ZodOptional<z.ZodString> | undefined;
+    filename: z.ZodString;
+    data_base64: z.ZodOptional<z.ZodString>;
+    data_text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Parsed attachment arguments; `path` is a string whenever the schema registered it. */
+export type AttachmentArgs = {
+    filename: string;
+    data_base64?: string;
+    data_text?: string;
+    path?: unknown;
+    content_type?: string;
+    sha256?: string;
+};
+/** A validated attachment ready to upload: bytes in memory, or a file to stream. */
+export type PreparedAttachment = {
+    filename: string;
+    contentType: string;
+    sha256?: string;
+} & ({
+    data: Uint8Array;
+} | {
+    file: string;
+});
+/**
+ * Decode base64 strictly: one alphabet (standard, or URL-safe with - and _) plus whitespace, `=` padding only at the
+ * end, a valid length, and no stray trailing bits. Node's decoder skips anything else silently, which would send a
+ * corrupted file.
+ */
+export declare function decodeBase64Strict(filename: string, input: string): Buffer;
+/** Validate every attachment before anything is created upstream, so a bad one never leaves a draft behind. */
+export declare function prepareAttachments(items: AttachmentArgs[] | undefined, config: Config): Promise<PreparedAttachment[]>;
+/** Upload prepared attachments into a draft; files stream from disk and are checked against their sha256. */
+export declare function uploadPrepared(client: FmsgClient, draftId: string, prepared: PreparedAttachment[], signal: AbortSignal): Promise<Attachment[]>;
+/** Create a draft and upload its attachments, deleting the draft if any upload fails. */
+export declare function draftWithAttachments(client: FmsgClient, input: DraftInput, prepared: PreparedAttachment[], signal: AbortSignal): Promise<DraftResult & {
+    attachments: Attachment[];
+}>;
+/** Draft, attach and send in one step; the draft is deleted if any step fails. */
+export declare function sendWithAttachments(client: FmsgClient, input: DraftInput, prepared: PreparedAttachment[], signal: AbortSignal): Promise<{
+    id: string;
+    time: number | null;
+    redactions: number;
+    redacted: string[];
+    topic: string;
+    attachments: Attachment[];
+}>;

package/dist/tools/attachments.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import * as z from "zod/v4";
+import { downloadBaseUrl } from "../download.js";
+import { attachmentType } from "../render.js";
+export const FILENAME = /^[A-Za-z0-9._-]+$/u;
+const SHA256 = /^[0-9A-Fa-f]{64}$/u;
+export function fileRoutes(config) {
+    return { uploadUrl: Boolean(downloadBaseUrl(config)), uploadFolder: Boolean(config.uploadDir) };
+}
+/** Inline base64 this long (about 48 KB of file) earns a hint about a better route next time. A hint only, never a limit. */
+const BASE64_HINT_CHARS = 64 * 1024;
+/** A hint for the model after it wrote a large file as base64 although this server offers a route that avoids it. */
+export function base64Hint(items, routes) {
+    const large = (items ?? []).filter((a) => (a.data_base64?.length ?? 0) >= BASE64_HINT_CHARS).map((a) => a.filename);
+    const better = [
+        ...(routes.uploadUrl ? ["call create_draft, PUT them to its upload URL, then call send_draft"] : []),
+        ...(routes.uploadFolder ? ["give their path in the upload folder instead of data_base64"] : []),
+    ];
+    if (!large.length || !better.length)
+        return undefined;
+    return `${large.join(", ")} went inline as base64. Next time, send files this large without writing their bytes: ${better.join(", or ")}.`;
+}
+/** The attachment sources this server accepts; `path` only over stdio with an upload folder. */
+function sources(config) {
+    return ["data_base64", "data_text", ...(config.uploadDir ? ["path"] : [])];
+}
+/** One outbound attachment as a tool argument: a filename and exactly one source of bytes. */
+export function attachmentInput(config) {
+    const names = sources(config);
+    return z.strictObject({
+        filename: z.string().regex(FILENAME, "letters, digits, dot, underscore, hyphen only").describe("file name"),
+        data_base64: z.string().optional().describe(`base64 file contents, for small files${config.uploadDir ? "; give large files as path" : downloadBaseUrl(config) ? "; send large files with create_draft's upload URL" : ""}. The host sets the size limit`),
+        data_text: z.string().optional().describe("text file contents, sent as UTF-8 bytes; use instead of data_base64 for text"),
+        ...(config.uploadDir ? {
+            path: z.string().min(1).optional().describe("file in the configured upload folder, relative to it; the server reads it so its bytes skip model context"),
+        } : {}),
+        content_type: z.string().optional().describe("inferred from the filename when omitted"),
+        sha256: z.string().regex(SHA256, "64 hexadecimal characters").optional().describe("hex sha256 of the file; the attachment is refused, and nothing sent, if the bytes differ. Give it when you can compute it"),
+    }).superRefine((a, ctx) => {
+        const given = names.filter((name) => a[name] !== undefined);
+        if (given.length !== 1)
+            ctx.addIssue({ code: "custom", message: `attachment ${a.filename}: give exactly one of ${names.join(", ")}` });
+    });
+}
+/**
+ * Decode base64 strictly: one alphabet (standard, or URL-safe with - and _) plus whitespace, `=` padding only at the
+ * end, a valid length, and no stray trailing bits. Node's decoder skips anything else silently, which would send a
+ * corrupted file.
+ */
+export function decodeBase64Strict(filename, input) {
+    const bad = /[^A-Za-z0-9+/\-_=\s]/u.exec(input);
+    if (bad)
+        throw new Error(`attachment ${filename}: invalid base64 character ${JSON.stringify(bad[0])} at position ${bad.index}`);
+    const standard = /[+/]/u.exec(input);
+    const urlSafe = /[-_]/u.exec(input);
+    if (standard && urlSafe) {
+        const [first, second] = standard.index < urlSafe.index ? [standard, urlSafe] : [urlSafe, standard];
+        throw new Error(`attachment ${filename}: base64 mixes the standard and URL-safe alphabets (${JSON.stringify(first[0])} at position ${first.index}, ` +
+            `${JSON.stringify(second[0])} at position ${second.index}); part of the data may be corrupt`);
+    }
+    const compact = input.replace(/\s+/gu, "").replace(/-/gu, "+").replace(/_/gu, "/");
+    const padding = compact.indexOf("=");
+    const unpadded = padding < 0 ? compact : compact.slice(0, padding);
+    if ((padding >= 0 && (!/^={1,2}$/u.test(compact.slice(padding)) || compact.length % 4 !== 0)) || unpadded.length % 4 === 1) {
+        throw new Error(`attachment ${filename}: invalid base64 length or padding; part of the data may be missing`);
+    }
+    const data = Buffer.from(compact, "base64");
+    if (data.toString("base64").replace(/=+$/u, "") !== unpadded)
+        throw new Error(`attachment ${filename}: invalid base64 ending; part of the data may be missing`);
+    return data;
+}
+/** Resolve a path inside the operator's upload folder; refuse anything that leaves it, including through symlinks. */
+async function uploadFile(directory, filename, relative) {
+    if (path.isAbsolute(relative) || relative.includes("\0"))
+        throw new Error(`attachment ${filename}: path must be relative to the upload folder`);
+    const root = await realpath(directory);
+    let target;
+    try {
+        target = await realpath(path.join(root, relative));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error(`attachment ${filename}: ${relative} was not found in the upload folder`);
+        throw error;
+    }
+    const inside = path.relative(root, target);
+    if (!inside || inside.startsWith("..") || path.isAbsolute(inside))
+        throw new Error(`attachment ${filename}: path must stay inside the upload folder`);
+    if (!(await stat(target)).isFile())
+        throw new Error(`attachment ${filename}: ${relative} is not a regular file`);
+    return target;
+}
+function checksum(filename, expected, data) {
+    if (!expected)
+        return;
+    const actual = createHash("sha256").update(data).digest("hex");
+    if (actual !== expected.toLowerCase())
+        throw new Error(`attachment ${filename}: sha256 mismatch (expected ${expected.toLowerCase()}, got ${actual}); nothing was sent`);
+}
+/** Validate every attachment before anything is created upstream, so a bad one never leaves a draft behind. */
+export async function prepareAttachments(items, config) {
+    const prepared = [];
+    for (const a of items ?? []) {
+        const sha256 = a.sha256?.toLowerCase();
+        const base = { filename: a.filename, ...(sha256 ? { sha256 } : {}) };
+        if (typeof a.path === "string") {
+            if (!config.uploadDir)
+                throw new Error(`attachment ${a.filename}: path needs an upload folder (FMSG_MCP_UPLOAD_DIR, stdio only)`);
+            prepared.push({ ...base, contentType: a.content_type ?? attachmentType(a.filename), file: await uploadFile(config.uploadDir, a.filename, a.path) });
+            continue;
+        }
+        const text = a.data_text !== undefined;
+        const data = text ? Buffer.from(a.data_text, "utf8") : decodeBase64Strict(a.filename, a.data_base64 ?? "");
+        if (data.byteLength === 0)
+            throw new Error(`attachment ${a.filename} is empty`);
+        checksum(a.filename, sha256, data);
+        const inferred = attachmentType(a.filename);
+        const contentType = a.content_type ?? (text && inferred === "application/octet-stream" ? "text/plain; charset=utf-8" : inferred);
+        prepared.push({ ...base, contentType, data: new Uint8Array(data) });
+    }
+    return prepared;
+}
+/** Upload prepared attachments into a draft; files stream from disk and are checked against their sha256. */
+export async function uploadPrepared(client, draftId, prepared, signal) {
+    const uploaded = [];
+    for (const a of prepared) {
+        if ("data" in a) {
+            uploaded.push(await client.uploadAttachment(draftId, { filename: a.filename, data: a.data, contentType: a.contentType }, signal));
+        }
+        else {
+            const stream = Readable.toWeb(createReadStream(a.file));
+            const { filename, size } = await client.uploadAttachmentStream(draftId, {
+                filename: a.filename, stream, contentType: a.contentType, ...(a.sha256 ? { expectedSha256: a.sha256 } : {}),
+            }, signal);
+            uploaded.push({ filename, size });
+        }
+    }
+    return uploaded;
+}
+/** Create a draft and upload its attachments, deleting the draft if any upload fails. */
+export async function draftWithAttachments(client, input, prepared, signal) {
+    const draft = await client.createDraft({ ...input, signal });
+    try {
+        return { ...draft, attachments: await uploadPrepared(client, draft.id, prepared, signal) };
+    }
+    catch (error) {
+        await client.deleteMessage(draft.id).catch(() => undefined);
+        throw error;
+    }
+}
+/** Draft, attach and send in one step; the draft is deleted if any step fails. */
+export async function sendWithAttachments(client, input, prepared, signal) {
+    const draft = await draftWithAttachments(client, input, prepared, signal);
+    try {
+        return { ...draft, ...(await client.sendDraft(draft.id, signal)) };
+    }
+    catch (error) {
+        await client.deleteMessage(draft.id).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/tools/draft.d.ts

@@ -0,0 +1,2 @@
+import { type Register } from "./common.js";
+export declare const registerDraftTools: Register;