ADR-029: Files reach the model as content, and the disk only from a local server¶
An attachment the model needs arrives as content every MCP client shows it: text, or an image, converted on the server by internal/fileview. Text comes back in windows of numbered lines the model pages through; a Word, PowerPoint or Excel file as its extracted text; an archive as a listing; an image as an image, turned upright and scaled to what clients take, with a note when it was scaled; small audio and video as themselves beside a description. Anything else is described by its type and size, with the post's link for the person to open, and a file over the cap is described without being read. A result never points the model at a command, a path or a download in place of content.
An attachment is also an MCP resource, from a template every server lists: mattermost://<server>/files/{file_id}, an address of mm-mcp's own rather than the file's https one, which a client would fetch itself without the credential. Reading a resource converts the file as read_file does and returns it whole: text, a document's extracted text and an archive's listing as text; an image as the image read_file returns; a PDF, audio, video and any other file as its bytes with their type. A resource goes to the client, which shows it, saves it or puts it in the conversation, rather than straight into the model's context, so read_file's limits do not bound it. What does is the client's own limit on one message: MCP sends a resource whole, in the one message that answers its read, with no way to send it in parts, and a client drops a message past its limit, and with it the request or the whole session; the TypeScript SDK's stdio transport takes 10 MiB, Go's 16 MiB. So the message is capped, by MM_MCP_RESOURCE_MAX_MB, 10 by default, measured whole, a binary file as its base64 and the response around it included, and refused before it is sent. The file a read downloads is bounded by Mattermost's own limit on a file, MaxFileSize, read from the configuration Mattermost tells every signed-in client: every upload was within it, so a larger file most likely came before an administrator lowered it, and it is refused before it is fetched, saying that the limit is Mattermost's. A file past a cap, or a document's text or an archive's listing the conversion cut short, is refused with read_file's windows and save_file as the ways to read it, since a resource is read whole. A post's files and search_files give each file's address beside its id, the answer carries a resource link to each, and every file_id takes the address. A client that completes a template's argument is offered the files whose name starts with what the person typed; MCP's completion holds bare values, so what it offers is ids. read_file and save_file stay: in many clients only the person, not the model, can open a resource, and a resource writes nothing to disk. Whether either can go is a question for when clients reliably let the model read resources.
Files, and the pictures a post shows with them, are resources. An attached image's preview, the smaller image its post shows, is at mattermost://<server>/files/{file_id}/preview, and a post's files give an image's size and its preview's address beside the file's own, since a preview is the cheaper thing to look at; a person's profile picture is at mattermost://<server>/users/{user_id}/image, and a custom emoji's at mattermost://<server>/emoji/{emoji_name}. Each reads as a picture: a raster image, never SVG, which a client could run as a page, and never anything else Mattermost answers with. A picture read is kept a while, within a bound, for the next read with the same credential, since a thread shows its people again and again, and what one credential may see another may not. Nothing else is a resource. A thread could be one, bounded and useful to bring into context by hand, but read_post already reads it for the model. A channel or a direct message is a poor fit: a resource is read whole, without pages, while a conversation grows without end, and listing a person's direct messages as resources would put every private conversation in the client's picker. Where something was said is a post's link (ADR-030).
The machine's disk is reached only by a server that runs on it, which is a server serving over stdio: the client started it as a process on the person's own machine. Only such a server offers save_file, which writes an attachment into the download directory, MM_MCP_DOWNLOAD_DIR or the person's Downloads directory, under the attachment's name, never over an existing file, and answers with the path it wrote. A tool that writes this machine's files is marked local in its spec, reads Mattermost and never changes it, and so is offered whether Mattermost writes are allowed or not; a governance test holds it to operations that only read. Likewise create_post, dm and group_message attach a file from a path only on a local server. A path is refused before anything is opened when it names another machine or a device, as \\host\share does on Windows, where merely looking makes the machine sign in to the host with the person's credentials, or when it lies in a tree the system makes up, such as /proc, which holds this server's own credential. A link is followed and the file it points at is what the call attaches, and what the question names where mm-mcp asks; a name with control or invisible characters is refused, and a file whose bytes disagree with its name's type says so. Over HTTP the server may run anywhere, and a path names a file on the server's machine, not the person's.
An upload is part of the post it belongs to. A tool that posts takes the files with the message, from a path on a local server or as text the model wrote, and the call names every file, which the question lists with its path, size and type where mm-mcp asks, before anything is sent. The files are uploaded only as the post is made, once the call is approved and, where mm-mcp asks, the person accepts, so a declined post leaves no orphaned file in Mattermost; and the person's answer accepts the files' bytes as they were when they were asked: a file changed since is refused, and the bytes the tool checks just before it uploads are the ones it uploads.
A model in a chat client can use only what the client shows it, so the server, which holds the bytes, converts them. A path on the person's machine is useful only when the person is at that machine, and the server can only know that when it runs there. A file read from disk and sent to colleagues is the one way a message in Mattermost could talk a model into leaking a local file, which is why the call names the path, for the client's approval to show, and the question too where mm-mcp asks.
Not chosen¶
- Return a file's bytes as text or base64: A binary file comes back corrupted or unreadable, and a large one fills the context in one piece.
- Save to disk over HTTP: The server's disk is not the person's, and on a shared deployment it is no one's to write.
- A separate upload tool that returns file ids: An upload nobody posts is an orphaned file, and the post's call would not show the files it carries.
- Let the model choose the path save_file writes to: A model steered by a message could overwrite a file anywhere the person can write; one directory, never overwriting, bounds what it can touch.
- The file's https address as its resource: A client reads it by fetching it, without Mattermost's credential, and gets a sign-in page.
- A resource's raw bytes, whatever the file: A client that puts a resource into the model's context would hand it a Word file's XML or a 40-megapixel photo; converted as
read_fileconverts it, a resource is what the model can use. - No default cap on a resource's message: A client past its limit does not refuse the message cleanly: Go's SDK stops reading, ending the session, and the TypeScript SDK's drops the request or closes. Refused here, the file is read with
read_fileorsave_fileinstead. - A setting of mm-mcp's own capping the file a resource read downloads: Mattermost's limit on a file already bounds every attachment, and an administrator sets it for every client at once; a second number to keep in step with it would only differ from it by mistake. Reading it costs one request a read.
- Nothing bounding the file a resource read downloads: A file attached before an administrator lowered Mattermost's limit is past what the administrator now allows anyone to upload, and a read that downloads it holds it whole in memory.
- List each file as a resource: The files a person can read have no end, and a list of them would put every private conversation's attachments in the client's picker.
- Base64 file content from the model: Models write base64 poorly and slowly; a file the model writes is text, and any other file comes from disk.