@markmnl/fmsg-mcp 1.4.2 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- `send_message`, `reply` and `create_draft` take `files`: files the user shared in the chat, given by
+  reference (ChatGPT's `openai/fileParams`, declared in each tool's `_meta`). The server downloads each
+  one, from public HTTPS addresses only, hashes it, attaches the exact bytes and reports its sha256 in
+  the result's `files`. ChatGPT can now send images and PDFs, which its sandbox could not upload.
+  New settings: `FMSG_MCP_FILE_HOSTS`, `FMSG_MCP_MAX_FILE_BYTES`.
 - `react` is non-destructive again (`destructiveHint: false`), reversing 1.4.1: a reaction is one emoji
   its sender changes or clears with another reaction, and it alters no one's messages, so hosts needn't
   ask before each one.

package/README.md

@@ -214,6 +214,8 @@ attach resources; prompts `chat` and `reply` script the wait → reply loop and
 | `FMSG_MCP_DOWNLOAD_DIR` | — | Enable `save_attachment` in stdio; folder for new files named from message ID and filename |
 | `FMSG_MCP_UPLOAD_DIR` | — | Allow attachment `path` arguments in stdio: files in this folder (or below it) are read by the server instead of written out by the model |
 | `FMSG_MCP_WAIT_MAX_SECONDS` | `230` | Cap on one `wait_for_message` call |
+| `FMSG_MCP_FILE_HOSTS` | any public host | Comma list of host names (or parent domains) that [files given by reference](#files-given-by-reference) may be downloaded from |
+| `FMSG_MCP_MAX_FILE_BYTES` | `20971520` (20 MiB) | Size limit for one file given by reference |
 | `FMSG_MCP_STATE_SECRET` | per-process random | At least 32 bytes; HMAC key for presigned links. Links still work only on the instance that issued them |
 | `FMSG_MCP_HOST` / `FMSG_MCP_PORT` | `127.0.0.1` / `8765` | HTTP bind address (or `--http host:port`) |
 | `FMSG_MCP_ALLOWED_HOSTS` | loopback names | Comma-separated `Host` header allowlist; required for non-loopback binds |
@@ -268,6 +270,26 @@ with `x-content-sha256`), then `send_draft`; see
 [attachment uploads](docs/http-deployment.md#attachment-uploads). Send files as they are: fmsg
 compresses message bodies and attachments itself when it sends them.
 
+#### Files given by reference
+
+`send_message`, `reply` and `create_draft` also take `files`: files the user shared in the chat,
+which the host fills in and the server downloads itself. This is ChatGPT's
+[`openai/fileParams`](https://developers.openai.com/apps-sdk/reference): each of the three tools
+declares `_meta["openai/fileParams"]: ["files"]`, and ChatGPT passes each file as
+`{ download_url, file_id, mime_type?, file_name? }`. The bytes never pass through the model, and the
+model needs no HTTP access of its own (ChatGPT's sandbox has none). Other hosts ignore the field.
+
+- Only `https` URLs, with no credentials in them, and at most 3 redirects. Every hop must resolve to a
+  public address: loopback, private, link-local (including cloud metadata), CGNAT, multicast and
+  reserved addresses are refused, and the connection goes to the address that was checked.
+  `FMSG_MCP_FILE_HOSTS` narrows the allowed hosts further.
+- Each file is limited to `FMSG_MCP_MAX_FILE_BYTES` and 30 seconds.
+- The name is the host's `file_name` made safe (letters, digits, dot, underscore, hyphen; `file.<ext>`
+  from the type when there is none), renamed `name-2.ext` on a clash.
+- The bytes are hashed as they download. The upload is checked against that sha256, and the result's
+  `files` lists each file's `file_id`, name, size and `sha256`.
+- Every file is downloaded before a draft is created, so one that fails leaves nothing behind.
+
 Hosts that cannot attach the connection's credentials to their own HTTP requests can still keep file
 bytes out of the model. `get_attachment_upload_url` returns a single-use, 5-minute link per draft
 file, bound to its size and sha256, with a ready-to-run `curl` command. `get_attachment_download_url`
@@ -280,7 +302,7 @@ routes the running server offers. A model that writes a large file as base64 alt
 route exists gets a `hint` in the result naming it. The `send_file` prompt walks through the best
 route. The upload URL needs a host that can send the MCP connection's credentials with its own
 HTTP requests: scripts, SDK clients, and coding agents given an fmsg API key. Chat hosts usually
-cannot, so for them `data_text` and `data_base64` remain the routes.
+cannot; ChatGPT uses `files`, and for others `data_text` and `data_base64` remain the routes.
 
 The Web API already transfers attachments as raw bytes. Base64 is used only when embedding binary
 content in MCP's JSON results, as required by [MCP binary resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources#binary-content).

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.2",
-  "commit": "33469ebc77bea6add5bfd454d8d60914d1b90e31",
-  "describe": "v1.4.2"
+  "version": "1.5.1",
+  "commit": "78f92e1272532d7b08b98659f792b357aeea703e",
+  "describe": "v1.5.1"
 }

package/dist/config.d.ts

@@ -39,6 +39,10 @@ export type Config = {
     uploadDir?: string;
     /** Hard cap on a single wait_for_message call. */
     waitMaxSeconds: number;
+    /** Host names (or parent domains) files given by reference may be downloaded from; empty allows any public host. */
+    fileHosts?: string[];
+    /** Byte limit for one file given by reference. */
+    maxFileBytes?: number;
     http: HttpConfig;
     oauth?: OAuthConfig;
 };

package/dist/config.js

@@ -1,3 +1,4 @@
+import { DEFAULT_MAX_FILE_BYTES } from "./host-files.js";
 import { readFileSync } from "node:fs";
 import { CALLER_DOMAIN, normalizeFmsgAddress } from "./address.js";
 import { normalizeApiUrl, normalizeOrigin } from "./client/url.js";
@@ -107,6 +108,8 @@ export function loadConfig(env, transport, overrides = {}, options = {}) {
         ...(transport === "stdio" && env.FMSG_MCP_DOWNLOAD_DIR?.trim() ? { downloadDir: env.FMSG_MCP_DOWNLOAD_DIR.trim() } : {}),
         ...(transport === "stdio" && env.FMSG_MCP_UPLOAD_DIR?.trim() ? { uploadDir: env.FMSG_MCP_UPLOAD_DIR.trim() } : {}),
         waitMaxSeconds: intEnv(env, "FMSG_MCP_WAIT_MAX_SECONDS", DEFAULT_WAIT_MAX_SECONDS),
+        fileHosts: listEnv(env, "FMSG_MCP_FILE_HOSTS"),
+        maxFileBytes: intEnv(env, "FMSG_MCP_MAX_FILE_BYTES", DEFAULT_MAX_FILE_BYTES),
         http: {
             host,
             port,

package/dist/host-files.d.ts

@@ -0,0 +1,66 @@
+import * as z from "zod/v4";
+/** The input field the host fills, named in each tool's `_meta["openai/fileParams"]`. */
+export declare const HOST_FILES_FIELD = "files";
+export declare const HOST_FILE_META: {
+    "openai/fileParams": string[];
+};
+/**
+ * OpenAI's file object: the four properties declared, download_url and file_id required, the others optional.
+ * Not strict, so an optional property the host adds later is accepted.
+ */
+export declare const hostFileSchema: z.ZodObject<{
+    download_url: z.ZodString;
+    file_id: z.ZodString;
+    mime_type: z.ZodOptional<z.ZodString>;
+    file_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const hostFilesInput: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    download_url: z.ZodString;
+    file_id: z.ZodString;
+    mime_type: z.ZodOptional<z.ZodString>;
+    file_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>>;
+export type HostFileArgs = {
+    download_url: string;
+    file_id: string;
+    mime_type?: string;
+    file_name?: string;
+};
+/** A downloaded host file, ready to attach. */
+export type HostFile = {
+    fileId: string;
+    filename: string;
+    contentType: string;
+    data: Uint8Array;
+    sha256: string;
+};
+/** One HTTP response from a download hop. */
+export type HostResponse = {
+    status: number;
+    headers: Record<string, string | undefined>;
+    body: AsyncIterable<Uint8Array>;
+    cancel: () => void;
+};
+/** Fetches one URL with no redirects followed; tests substitute it. */
+export type HostTransport = (url: URL, signal: AbortSignal) => Promise<HostResponse>;
+export type HostFileOptions = {
+    /** Byte limit per file. */
+    maxBytes: number;
+    /** Allowed host names (exact or a parent domain); empty allows any public host. */
+    allowedHosts: string[];
+    transport?: HostTransport;
+    /** Per-file time budget. */
+    timeoutMs?: number;
+};
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+/** Whether an IP address is public (globally routable), so a download may connect to it. */
+export declare function isPublicAddress(address: string): boolean;
+/** The default transport: HTTPS to public addresses only, nothing followed. */
+export declare const publicHttpsTransport: HostTransport;
+/** A safe attachment name (letters, digits, dot, underscore, hyphen) from what the host gave. */
+export declare function hostFilename(given: string | undefined, contentType: string | undefined): string;
+/**
+ * Download every host file before anything is created upstream, so a bad one never leaves a draft behind.
+ * `taken` holds the names already used by the call's other attachments.
+ */
+export declare function prepareHostFiles(files: HostFileArgs[] | undefined, options: HostFileOptions, signal: AbortSignal, taken?: Set<string>): Promise<HostFile[]>;

package/dist/host-files.js

@@ -0,0 +1,258 @@
+/**
+ * Files a host hands to a tool by reference (ChatGPT's `openai/fileParams`): the host fills a file object with a
+ * download URL and the server fetches the bytes, so they never pass through the model and the model needs no
+ * outbound HTTP of its own. The download only reaches public addresses: every hop is resolved, checked and connected
+ * to by the checked address, so a hostile URL can't reach loopback, the local network or a cloud metadata service.
+ */
+import { createHash } from "node:crypto";
+import { lookup as dnsLookup } from "node:dns";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+import * as z from "zod/v4";
+import { attachmentType } from "./render.js";
+/** The input field the host fills, named in each tool's `_meta["openai/fileParams"]`. */
+export const HOST_FILES_FIELD = "files";
+export const HOST_FILE_META = { "openai/fileParams": [HOST_FILES_FIELD] };
+/**
+ * OpenAI's file object: the four properties declared, download_url and file_id required, the others optional.
+ * Not strict, so an optional property the host adds later is accepted.
+ */
+export const hostFileSchema = z.object({
+    download_url: z.string().describe("filled in by the host"),
+    file_id: z.string().describe("filled in by the host"),
+    mime_type: z.string().optional().describe("filled in by the host"),
+    file_name: z.string().optional().describe("filled in by the host"),
+}).describe("a file the user shared in this chat, filled in by the host");
+export const hostFilesInput = z.array(hostFileSchema).optional().describe("files the user shared in this chat (images, PDFs and so on); the host fills these in and this server downloads them, " +
+    "so never write their bytes as base64");
+export const DEFAULT_MAX_FILE_BYTES = 20 * 1024 * 1024;
+const MAX_REDIRECTS = 3;
+const FILENAME_MAX = 100;
+// Addresses a download must never reach.
+const blocked = new BlockList();
+for (const [net, bits] of [
+    ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12],
+    ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.88.99.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15],
+    ["198.51.100.0", 24], ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+])
+    blocked.addSubnet(net, bits, "ipv4");
+for (const [net, bits] of [
+    ["::", 128], ["::1", 128], ["100::", 64], ["2001::", 32], ["2001:db8::", 32],
+    ["fc00::", 7], ["fe80::", 10], ["ff00::", 8],
+])
+    blocked.addSubnet(net, bits, "ipv6");
+/** Whether an IP address is public (globally routable), so a download may connect to it. */
+export function isPublicAddress(address) {
+    const family = isIP(address);
+    if (!family)
+        return false;
+    if (family === 4)
+        return !blocked.check(address, "ipv4");
+    // IPv4-mapped (::ffff:a.b.c.d or ::ffff:7f00:1) and NAT64 (64:ff9b::/96) addresses are judged by their IPv4 address.
+    const embedded = embeddedIpv4(address);
+    if (embedded)
+        return !blocked.check(embedded, "ipv4");
+    return !blocked.check(address, "ipv6");
+}
+/** The IPv4 address inside an IPv4-mapped or NAT64 IPv6 address, if it is one. */
+function embeddedIpv4(address) {
+    const lower = address.toLowerCase();
+    const prefix = ["::ffff:", "64:ff9b::"].find((p) => lower.startsWith(p));
+    if (!prefix)
+        return undefined;
+    const rest = lower.slice(prefix.length);
+    if (isIP(rest) === 4)
+        return rest;
+    const m = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/u.exec(rest);
+    if (!m)
+        return undefined;
+    const hi = parseInt(m[1], 16), lo = parseInt(m[2], 16);
+    return `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+}
+class RefusedError extends Error {
+}
+/** A DNS lookup for https.request that only ever yields public addresses: the connection uses what was checked. */
+function publicLookup(hostname, options, callback) {
+    dnsLookup(hostname, { all: true }, (err, addresses) => {
+        if (err)
+            return callback(err, "", 0);
+        const ok = addresses.filter((a) => isPublicAddress(a.address));
+        if (!ok.length)
+            return callback(Object.assign(new RefusedError("address not public"), { code: "EREFUSED_PRIVATE" }), "", 0);
+        if (options.all)
+            return callback(null, ok);
+        callback(null, ok[0].address, ok[0].family);
+    });
+}
+/** The default transport: HTTPS to public addresses only, nothing followed. */
+export const publicHttpsTransport = (url, signal) => new Promise((resolve, reject) => {
+    if (isIP(url.hostname.replace(/^\[|\]$/gu, "")) && !isPublicAddress(url.hostname.replace(/^\[|\]$/gu, ""))) {
+        reject(new RefusedError("address not public"));
+        return;
+    }
+    const req = httpsRequest(url, { method: "GET", lookup: publicLookup, signal, headers: { accept: "*/*" } }, (res) => {
+        resolve({
+            status: res.statusCode ?? 0,
+            headers: Object.fromEntries(Object.entries(res.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(", ") : v])),
+            body: res,
+            cancel: () => res.destroy(),
+        });
+    });
+    req.on("error", (error) => reject(error.code === "EREFUSED_PRIVATE" ? new RefusedError("address not public") : error));
+    req.end();
+});
+function hostAllowed(host, allowed) {
+    if (!allowed.length)
+        return true;
+    const h = host.toLowerCase();
+    return allowed.some((a) => { const d = a.toLowerCase().replace(/^\./u, ""); return h === d || h.endsWith(`.${d}`); });
+}
+function checkUrl(raw, allowed) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new RefusedError("not a valid URL");
+    }
+    if (url.protocol !== "https:")
+        throw new RefusedError("only https download URLs are accepted");
+    if (url.username || url.password)
+        throw new RefusedError("credentials in the URL are not accepted");
+    if (!hostAllowed(url.hostname, allowed))
+        throw new RefusedError(`host ${url.hostname} is not an allowed file host`);
+    return url;
+}
+const EXTENSIONS = {
+    "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif", "image/webp": "webp", "image/heic": "heic", "image/svg+xml": "svg",
+    "application/pdf": "pdf", "text/plain": "txt", "text/markdown": "md", "text/csv": "csv", "application/json": "json",
+    "application/zip": "zip", "audio/mpeg": "mp3", "audio/mp4": "m4a", "video/mp4": "mp4", "video/quicktime": "mov",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+};
+/** A safe attachment name (letters, digits, dot, underscore, hyphen) from what the host gave. */
+export function hostFilename(given, contentType) {
+    const base = (given ?? "").split(/[\\/]/u).pop() ?? "";
+    let name = base.normalize("NFKD").replace(/[^A-Za-z0-9._-]+/gu, "_").replace(/_+/gu, "_").replace(/^[._]+/u, "");
+    if (name.length > FILENAME_MAX) {
+        const dot = name.lastIndexOf(".");
+        const ext = dot > 0 && name.length - dot <= 10 ? name.slice(dot) : "";
+        name = name.slice(0, FILENAME_MAX - ext.length) + ext;
+    }
+    if (!name || name === "_") {
+        const ext = EXTENSIONS[(contentType ?? "").split(";")[0].trim().toLowerCase()];
+        name = ext ? `file.${ext}` : "file";
+    }
+    return name;
+}
+function uniqueName(name, taken) {
+    if (!taken.has(name.toLowerCase())) {
+        taken.add(name.toLowerCase());
+        return name;
+    }
+    const dot = name.lastIndexOf(".");
+    const [stem, ext] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ""];
+    for (let i = 2;; i++) {
+        const candidate = `${stem}-${i}${ext}`;
+        if (!taken.has(candidate.toLowerCase())) {
+            taken.add(candidate.toLowerCase());
+            return candidate;
+        }
+    }
+}
+function sizeText(bytes) {
+    return bytes >= 1024 * 1024 ? `${Math.round(bytes / 1024 / 1024)} MiB` : `${Math.round(bytes / 1024)} KiB`;
+}
+/** Download one host file: public HTTPS, redirects checked, size-limited, hashed. */
+async function download(file, label, options, outer) {
+    const transport = options.transport ?? publicHttpsTransport;
+    const signal = AbortSignal.any([outer, AbortSignal.timeout(options.timeoutMs ?? 30_000)]);
+    let url;
+    try {
+        url = checkUrl(file.download_url, options.allowedHosts);
+    }
+    catch (error) {
+        throw new Error(`file ${label}: download refused (${error.message})`);
+    }
+    for (let hop = 0;; hop++) {
+        let res;
+        try {
+            res = await transport(url, signal);
+        }
+        catch (error) {
+            if (error instanceof RefusedError)
+                throw new Error(`file ${label}: download refused (${error.message})`);
+            if (signal.aborted)
+                throw new Error(`file ${label}: download timed out or was cancelled`);
+            throw new Error(`file ${label}: download failed (${error.message})`);
+        }
+        if (res.status >= 300 && res.status < 400 && res.headers.location) {
+            res.cancel();
+            if (hop >= MAX_REDIRECTS)
+                throw new Error(`file ${label}: download refused (too many redirects)`);
+            try {
+                url = checkUrl(new URL(res.headers.location, url).toString(), options.allowedHosts);
+            }
+            catch (error) {
+                throw new Error(`file ${label}: download refused (${error.message})`);
+            }
+            continue;
+        }
+        if (res.status !== 200) {
+            res.cancel();
+            throw new Error(`file ${label}: download failed: HTTP ${res.status}`);
+        }
+        const declared = Number(res.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > options.maxBytes) {
+            res.cancel();
+            throw new Error(`file ${label} is larger than ${sizeText(options.maxBytes)}`);
+        }
+        const hash = createHash("sha256");
+        const chunks = [];
+        let total = 0;
+        try {
+            for await (const chunk of res.body) {
+                total += chunk.byteLength;
+                if (total > options.maxBytes) {
+                    res.cancel();
+                    throw new Error(`file ${label} is larger than ${sizeText(options.maxBytes)}`);
+                }
+                hash.update(chunk);
+                chunks.push(chunk);
+            }
+        }
+        catch (error) {
+            if (error.message.startsWith(`file ${label}`))
+                throw error;
+            throw new Error(`file ${label}: download failed (${signal.aborted ? "timed out or was cancelled" : error.message})`);
+        }
+        if (total === 0)
+            throw new Error(`file ${label} is empty`);
+        const data = new Uint8Array(total);
+        let offset = 0;
+        for (const c of chunks) {
+            data.set(c, offset);
+            offset += c.byteLength;
+        }
+        const contentType = res.headers["content-type"]?.split(",")[0]?.trim();
+        return { data, sha256: hash.digest("hex"), ...(contentType ? { contentType } : {}) };
+    }
+}
+/**
+ * Download every host file before anything is created upstream, so a bad one never leaves a draft behind.
+ * `taken` holds the names already used by the call's other attachments.
+ */
+export async function prepareHostFiles(files, options, signal, taken = new Set()) {
+    const out = [];
+    for (const f of files ?? []) {
+        if (!f.download_url || !f.file_id)
+            throw new Error("each file needs download_url and file_id (the host fills them in)");
+        const label = hostFilename(f.file_name, f.mime_type);
+        const got = await download(f, label, options, signal);
+        const contentType = f.mime_type?.trim() || got.contentType || attachmentType(label);
+        const filename = uniqueName(f.file_name ? label : hostFilename(undefined, contentType), taken);
+        out.push({ fileId: f.file_id, filename, contentType, data: got.data, sha256: got.sha256 });
+    }
+    return out;
+}

package/dist/instructions.js

@@ -14,7 +14,8 @@ function filesParagraph(files) {
         ...(files?.uploadUrl ? [`create_draft, PUT each file to its upload URL${files.presigned ? " (or a get_attachment_upload_url link)" : ""}, then send_draft`] : []),
         ...(files?.uploadFolder ? ["give path, a file in the upload folder"] : []),
     ];
-    return "Files: data_text for text, data_base64 for small files (best effort; always add sha256)." + (large.length ? ` Large files: ${large.join("; or ")}.` : "");
+    return "Files: data_text for text, data_base64 for small files (best effort; always add sha256)." + (large.length ? ` Large files: ${large.join("; or ")}.` : "") +
+        " Files the user shared in this chat go in files, which the host fills in; this server downloads them, so never write their bytes.";
 }
 export function buildInstructions(ctx = {}) {
     const identity = ctx.address

package/dist/server.d.ts

@@ -1,3 +1,4 @@
+import type { HostTransport } from "./host-files.js";
 import { McpServer } from "@modelcontextprotocol/server";
 import type { Config } from "./config.js";
 import type { CallerProvider } from "./context.js";
@@ -20,6 +21,8 @@ export type CreateServerOptions = {
      * (stdio).
      */
     indicators?: IndicatorRegistry;
+    /** Fetches files given by reference (tests substitute it). */
+    hostTransport?: HostTransport;
 };
 /**
  * Build an fmsg MCP server. Registration only — no I/O — so the same factory

package/dist/server.js

@@ -41,6 +41,7 @@ export function createFmsgMcpServer(provider, config, options = {}) {
     const deps = {
         provider, config, ...(includeOwner ? { includeOwner } : {}), ...(options.shutdown ? { shutdown: options.shutdown } : {}),
         ...(options.links ? { links: options.links } : {}), indicators,
+        ...(options.hostTransport ? { hostTransport: options.hostTransport } : {}),
     };
     registerIdentityTools(server, deps);
     registerListTools(server, deps);

package/dist/tools/attachments.d.ts

@@ -2,6 +2,7 @@ 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";
+import { type HostFile, type HostFileArgs, type HostTransport } from "../host-files.js";
 export declare const FILENAME: RegExp;
 /** Ways this server can take a file without the model writing its bytes. */
 export type FileRoutes = {
@@ -40,6 +41,7 @@ export type PreparedAttachment = {
     filename: string;
     contentType: string;
     sha256?: string;
+    verify?: boolean;
 } & ({
     data: Uint8Array;
 } | {
@@ -68,3 +70,15 @@ export declare function sendWithAttachments(client: FmsgClient, input: DraftInpu
     topic: string;
     attachments: Attachment[];
 }>;
+/** What a send or draft tool attaches: its inline attachments, then the files the host gave by reference. */
+export declare function prepareAllAttachments(items: AttachmentArgs[] | undefined, files: HostFileArgs[] | undefined, config: Config, transport: HostTransport | undefined, signal: AbortSignal): Promise<{
+    prepared: PreparedAttachment[];
+    hostFiles: HostFile[];
+}>;
+/** The files given by reference as they were attached, for the tool result. */
+export declare function hostFilesResult(files: HostFile[]): Array<{
+    file_id: string;
+    filename: string;
+    size: number;
+    sha256: string;
+}>;

package/dist/tools/attachments.js

@@ -6,6 +6,7 @@ import { Readable } from "node:stream";
 import * as z from "zod/v4";
 import { downloadBaseUrl } from "../download.js";
 import { attachmentType } from "../render.js";
+import { DEFAULT_MAX_FILE_BYTES, prepareHostFiles } from "../host-files.js";
 export const FILENAME = /^[A-Za-z0-9._-]+$/u;
 const SHA256 = /^[0-9A-Fa-f]{64}$/u;
 export function fileRoutes(config, presigned = false) {
@@ -139,9 +140,17 @@ export async function prepareAttachments(items, config) {
 export async function uploadPrepared(client, draftId, prepared, signal) {
     const uploaded = [];
     for (const a of prepared) {
-        if ("data" in a) {
+        if ("data" in a && !(a.verify && a.sha256)) {
             uploaded.push(await client.uploadAttachment(draftId, { filename: a.filename, data: a.data, contentType: a.contentType }, signal));
         }
+        else if ("data" in a) {
+            // A downloaded file: the host checks the bytes it stores against the hash taken while downloading.
+            const stream = Readable.toWeb(Readable.from([Buffer.from(a.data)]));
+            const { filename, size } = await client.uploadAttachmentStream(draftId, {
+                filename: a.filename, stream, contentType: a.contentType, expectedSha256: a.sha256,
+            }, signal);
+            uploaded.push({ filename, size });
+        }
         else {
             const stream = Readable.toWeb(createReadStream(a.file));
             const { filename, size } = await client.uploadAttachmentStream(draftId, {
@@ -174,3 +183,21 @@ export async function sendWithAttachments(client, input, prepared, signal) {
         throw error;
     }
 }
+/** What a send or draft tool attaches: its inline attachments, then the files the host gave by reference. */
+export async function prepareAllAttachments(items, files, config, transport, signal) {
+    const prepared = await prepareAttachments(items, config);
+    const taken = new Set(prepared.map((a) => a.filename.toLowerCase()));
+    const hostFiles = await prepareHostFiles(files, {
+        maxBytes: config.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+        allowedHosts: config.fileHosts ?? [],
+        ...(transport ? { transport } : {}),
+    }, signal, taken);
+    return {
+        prepared: [...prepared, ...hostFiles.map((f) => ({ filename: f.filename, contentType: f.contentType, data: f.data, sha256: f.sha256, verify: true }))],
+        hostFiles,
+    };
+}
+/** The files given by reference as they were attached, for the tool result. */
+export function hostFilesResult(files) {
+    return files.map((f) => ({ file_id: f.fileId, filename: f.filename, size: f.data.byteLength, sha256: f.sha256 }));
+}

package/dist/tools/common.d.ts

@@ -1,3 +1,4 @@
+import type { HostTransport } from "../host-files.js";
 import type { CallToolResult, McpServer, ServerContext, ToolAnnotations } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
 import type { AddressResolver } from "../address.js";
@@ -17,6 +18,8 @@ export type ToolDeps = {
     links?: PresignedLinks;
     /** FMSG-006 indicators the caller sets with the indicate tool, kept up until replied, handled or cleared. */
     indicators: IndicatorRegistry;
+    /** Fetches files given by reference; the public-HTTPS transport when omitted. */
+    hostTransport?: HostTransport;
 };
 export declare const READ_ONLY: ToolAnnotations;
 export declare const SENDS: ToolAnnotations;

package/dist/tools/draft.js

@@ -4,7 +4,8 @@ import { toolError } from "../errors.js";
 import { withOwner } from "../owner.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 { attachmentInput, base64Hint, draftWithAttachments, fileRoutes, hostFilesResult, prepareAllAttachments } from "./attachments.js";
+import { HOST_FILE_META, hostFilesInput } from "../host-files.js";
 import { SENDS, attachmentItem, idSchema, ok, openEnum, outputObject, resolverFor, withCaller } from "./common.js";
 import { parentReference, replyParent } from "./parent.js";
 import { threadRoot } from "./read.js";
@@ -30,6 +31,7 @@ export const registerDraftTools = (server, deps) => {
             allow_no_reply: z.boolean().default(false).describe("draft a reply even though the parent asked for no replies"),
             ...includeOwner,
             attachments: z.array(attachmentInput(deps.config)).optional().describe("files to attach now"),
+            files: hostFilesInput,
         }),
         outputSchema: outputObject({
             draft_id: z.string(),
@@ -37,6 +39,8 @@ export const registerDraftTools = (server, deps) => {
             topic: z.string(),
             parent_id: z.string().nullable(),
             attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
+            files: z.array(outputObject({ file_id: z.string().optional(), filename: z.string().optional(), size: z.number().optional(), sha256: z.string().optional() })).optional()
+                .describe("the files given by reference, as attached: the name used, size and hex sha256 of the bytes"),
             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,
@@ -52,7 +56,8 @@ export const registerDraftTools = (server, deps) => {
             hint: hintOutput,
         }),
         annotations: { ...SENDS, destructiveHint: false, openWorldHint: false },
-    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => {
+        _meta: HOST_FILE_META,
+    }, async ({ to, topic, reply_to, body, type, important, no_reply, allow_no_reply, include_owner, attachments, files }, ctx) => {
         if (reply_to && topic)
             return toolError("a reply has no topic: pass topic only for a new message");
         if (!reply_to && !to?.length)
@@ -75,7 +80,7 @@ export const registerDraftTools = (server, deps) => {
                 ({ to: recipients, resolved } = resolveRecipients(to, resolverFor(deps, caller)));
             }
             recipients = withOwner(caller, recipients, include_owner);
-            const outbound = await prepareAttachments(attachments, deps.config);
+            const { prepared: outbound, hostFiles } = await prepareAllAttachments(attachments, files, deps.config, deps.hostTransport, signal);
             const hint = base64Hint(attachments, routes);
             const draft = await draftWithAttachments(caller.client, {
                 to: recipients, body, type, important, noReply: no_reply, ...(parentRef ?? { topic: topic ?? "" }),
@@ -96,6 +101,7 @@ export const registerDraftTools = (server, deps) => {
                 topic: draft.topic,
                 parent_id: pid ?? null,
                 attachments: sentAttachments(draft.attachments, outbound),
+                ...(hostFiles.length ? { files: hostFilesResult(hostFiles) } : {}),
                 redactions: draft.redactions,
                 redacted: draft.redacted,
                 ...(resolved.length ? { resolved } : {}),

package/dist/tools/send.d.ts

@@ -69,6 +69,12 @@ export declare const sentOutput: z.ZodObject<{
         size: z.ZodNumber;
         type: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file_id: z.ZodOptional<z.ZodString>;
+        filename: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+        sha256: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
     redactions: z.ZodNumber;
     redacted: z.ZodOptional<z.ZodArray<z.ZodString>>;
     resolved: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/tools/send.js

@@ -3,7 +3,8 @@ import { resolveAddress, sameAddress } from "../address.js";
 import { toolError } from "../errors.js";
 import { withOwner } from "../owner.js";
 import { addressList, addressText, attachmentType, headerValue, isoTime, participantsOf, sortAttachments } from "../render.js";
-import { attachmentInput, base64Hint, fileRoutes, prepareAttachments, sendWithAttachments } from "./attachments.js";
+import { attachmentInput, base64Hint, fileRoutes, hostFilesResult, prepareAllAttachments, sendWithAttachments } from "./attachments.js";
+import { HOST_FILE_META, hostFilesInput } from "../host-files.js";
 import { SENDS, attachmentItem, idSchema, ok, outputObject, resolverFor, withCaller } from "./common.js";
 import { parentReference, replyParent } from "./parent.js";
 import { WORKING_EMOJI } from "../indicators.js";
@@ -88,6 +89,8 @@ export const sentOutput = outputObject({
     topic: z.string(),
     parent_id: z.string().nullable(),
     attachments: z.array(attachmentItem).describe("sorted by filename, the same order in every tool"),
+    files: z.array(outputObject({ file_id: z.string().optional(), filename: z.string().optional(), size: z.number().optional(), sha256: z.string().optional() })).optional()
+        .describe("the files given by reference, as attached: the name used, size and hex sha256 of the bytes"),
     redactions: z.number().describe("secrets replaced with placeholders before sending"),
     redacted: z.array(z.string()).optional().describe("the kinds of secret replaced, such as github_token; empty when none"),
     resolved: resolvedOutput,
@@ -125,13 +128,15 @@ export const registerSendTools = (server, deps) => {
             no_reply: z.boolean().default(false).describe(NO_REPLY),
             ...includeOwner,
             attachments,
+            files: hostFilesInput,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
-    }, async ({ to, topic, body, type, important, no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        _meta: HOST_FILE_META,
+    }, async ({ to, topic, body, type, important, no_reply, include_owner, attachments, files }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const { to: resolvedTo, resolved } = resolveRecipients(to, resolverFor(deps, caller));
         const recipients = withOwner(caller, resolvedTo, include_owner);
-        const outbound = await prepareAttachments(attachments, deps.config);
+        const { prepared: outbound, hostFiles } = await prepareAllAttachments(attachments, files, deps.config, deps.hostTransport, signal);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to: recipients, topic, body, type, important, noReply: no_reply }, outbound, signal);
         const structured = {
@@ -142,6 +147,7 @@ export const registerSendTools = (server, deps) => {
             topic: sent.topic,
             parent_id: null,
             attachments: sentAttachments(sent.attachments, outbound),
+            ...(hostFiles.length ? { files: hostFilesResult(hostFiles) } : {}),
             redactions: sent.redactions,
             redacted: sent.redacted,
             ...(resolved.length ? { resolved } : {}),
@@ -171,10 +177,12 @@ export const registerSendTools = (server, deps) => {
             allow_no_reply: z.boolean().default(false).describe("reply even though the parent asked for no replies"),
             ...includeOwner,
             attachments,
+            files: hostFilesInput,
         }),
         outputSchema: sentOutput,
         annotations: SENDS,
-    }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, include_owner, attachments }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
+        _meta: HOST_FILE_META,
+    }, async ({ id, body, recipients, type, important, no_reply, allow_no_reply, include_owner, attachments, files }, ctx) => withCaller(deps, ctx, async (caller, signal) => {
         const parent = await replyParent(caller, id, signal);
         if ("content" in parent)
             return parent;
@@ -183,7 +191,7 @@ export const registerSendTools = (server, deps) => {
             return target;
         const { resolved } = target;
         const to = withOwner(caller, target.to, include_owner);
-        const outbound = await prepareAttachments(attachments, deps.config);
+        const { prepared: outbound, hostFiles } = await prepareAllAttachments(attachments, files, deps.config, deps.hostTransport, signal);
         const hint = base64Hint(attachments, routes);
         const sent = await sendWithAttachments(caller.client, { to, ...parentReference(caller, parent), body, type, important, noReply: no_reply }, outbound, signal);
         // The reply is already sent: a failed root lookup only leaves the topic unknown.
@@ -197,6 +205,7 @@ export const registerSendTools = (server, deps) => {
             topic: "",
             parent_id: parent.id,
             attachments: sentAttachments(sent.attachments, outbound),
+            ...(hostFiles.length ? { files: hostFilesResult(hostFiles) } : {}),
             redactions: sent.redactions,
             redacted: sent.redacted,
             ...(resolved.length ? { resolved } : {}),

package/package.json

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

package/server.json

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