Restrict CLI image uploads to an approved directory
Set the filesystem jail and understand extension, size, and magic-byte checks.
`OFFLINECREATOR_UPLOAD_ROOT` belongs to the local stdio MCP path exposed by the OfflineCreator package; it is not a general permission for every CLI command. Set it to the smallest directory that contains the images an operator has approved for `upload_input`, then start the package from that configured environment. The current first-party configuration trims the variable and falls back to the process working directory when it is missing or blank, so an accidental launch directory can otherwise become the effective boundary.
A practical setup is a dedicated folder such as `/workspace/approved-inputs`, populated only with reviewed source images. Export `OFFLINECREATOR_UPLOAD_ROOT=/workspace/approved-inputs` in the environment used to launch the bare `offlinecreator-mcp` stdio server, or put the same variable in that server's MCP client configuration. Keep the API key separate and secret. Because configuration is loaded as the process starts, restart the local server after changing the root rather than assuming a running process has noticed the new value.
Understand the checks applied to a local file
The current local reader resolves the configured root and the requested path, then uses a relative-path comparison to reject paths that are equal to the root, absolute outside it, or begin outside it after normalization. A requested file must also end in `.png`, `.jpg`, `.jpeg`, `.webp`, or `.gif`; point to a regular, non-empty file; and fit within the byte limit. This makes a relative path such as `campaign/hero.webp` preferable to a broad absolute path because the intended boundary remains visible in configuration and review.
The default input ceiling is 10 MiB. Passing the filename check is not enough: the reader opens the file and inspects its bytes for a recognized PNG, JPEG, GIF, or WebP signature. Renaming a text file to `.png` therefore does not make it a recognized image. Conversely, the implementation derives the upload content type from the inspected bytes. Prepare the input by exporting it in one supported format and reducing its actual byte size; do not bypass a rejection by widening the root or changing only the suffix.
Use a path relative to one approved directory
After starting the local stdio server with the dedicated root, pass `upload_input` a relative `filePath` beneath it, for example `campaign/hero.webp`, together with the reserved generation ID. The public tool description identifies the path as relative to the current working directory or `OFFLINECREATOR_UPLOAD_ROOT`. The client then reads the approved local image, uploads its bytes to the reserved generation, and submits that generation for processing. The root controls what the local process may select; it does not select a file automatically.
Do not use this environment variable for a hosted remote MCP connection. The local entry point explicitly injects the filesystem reader when it starts stdio, while the API client rejects `filePath` when that reader is absent and asks for `imageBase64` instead. That distinction prevents a remote service from interpreting a pathname on the machine running the MCP client. Choose the connection mode first: an approved path under a narrow root for local stdio, or the supported byte payload for remote MCP.
Diagnose a rejected upload without expanding access
Check failures in boundary order. First confirm that the local stdio process actually received the intended `OFFLINECREATOR_UPLOAD_ROOT`; a missing value means its launch working directory is in effect. Next normalize the requested relative path and confirm it stays below that root. Then check the lowercase extension, verify the target is a regular non-empty file, measure it against 10 MiB, and finally confirm that the image's header is recognized. Each stage has a distinct first-party error, so preserve the message rather than converting every rejection into a generic upload failure.
If an operator approved an image stored elsewhere, copy a reviewed version into the dedicated directory instead of setting the root to a home directory, repository parent, or filesystem root. If the file is too large, create a smaller derivative inside the approved directory. If content sniffing fails, re-export the image rather than merely renaming it. These responses preserve the purpose of the boundary: the generation workflow gets one intentional source asset without granting the process convenient access to unrelated local files.