@forestadmin/mcp-server 1.21.0 → 1.22.0

package/README.md

@@ -20,6 +20,7 @@ This MCP server provides HTTP REST API access to Forest Admin operations, enabli
 | `dissociate` | Dissociate records from a relation |
 | `getActionForm` | Get the form fields for a custom action |
 | `executeAction` | Execute a custom action |
+| `requestActionFileUpload` | Get a destination to upload a file to, for an action `File` field (only with `fileUploads`) |
 
 ## Usage
 
@@ -67,6 +68,8 @@ yarn start:dev       # Development (loads .env file automatically)
 | `FOREST_AGENT_URL` | No | your environment's back-end URL | URL the MCP server uses to reach the back-end's data layer. Set it when the server runs next to a self-hosted back-end at an internal address (e.g. `http://localhost:3310`), instead of the public URL registered in Forest |
 | `FOREST_MCP_ACCESS_TOKEN_TTL_SECONDS` | No | `3600` (1 hour) | Maximum lifetime of the OAuth access tokens the server issues (`tokenTtl.accessTokenSeconds`). Minimum `60` |
 | `FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS` | No | unbounded | Maximum time between two interactive logins (`tokenTtl.refreshTokenSeconds`). Unset, a client that keeps refreshing never signs in again. Minimum `60` |
+| `FOREST_MCP_FILE_UPLOADS` | No | - | `false` turns action file uploads off (they are **on** by default, in memory). Any other value than `true`/`false` fails at startup |
+| `FOREST_MCP_UPLOAD_STORAGE_MODULE` | No | - | Path to a module providing the `fileUploads` options, for a real storage backend. `FOREST_MCP_FILE_UPLOADS=false` wins over it |
 
 #### Example Configuration
 
@@ -164,6 +167,250 @@ The two settings differ in what the user notices:
 
 The minimum for either value is 60 seconds; anything lower is raised to it. An invalid value (zero, negative, fractional) fails at startup rather than silently leaving the tokens uncapped.
 
+## Action File Uploads
+
+> **Experimental.** The MCP specification is still designing its own file transfer story
+> ([SEP-2631](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2631)). The
+> `UploadStorage` contract is expected to survive, but the `requestActionFileUpload` tool and the handle
+> format may change to follow the specification once it lands.
+
+Actions with **File fields** cannot normally run over MCP. The agent expects file values as data
+uris, which would transit the model's context window and exceed most MCP clients' payload limits.
+The `fileUploads` option enables them through an upload side-channel that keeps the bytes out of
+the conversation:
+
+1. The client calls the `requestActionFileUpload` tool with `{ "filename", "mimeType", "sha256"? }` and receives a pre-authorized upload URL plus a signed `fileHandle` string.
+2. The client uploads the raw bytes directly to the storage backend, so they never pass through the MCP server or the model.
+3. The client passes the handle (`"$uploadedFile:<...>"`) as the field value in `executeAction`. The server downloads the object and hands it to the agent. The model only ever exchanges the small handle.
+
+`requestActionFileUpload` follows `enabledTools` like every other tool, so a server that leaves it out never advertises it and never serves the upload endpoint.
+
+The upload URL is unauthenticated — the model holds no agent credential, and must not — so the URL
+itself is the authorization, as with an S3 presigned PUT. It carries a random uuid, is refused
+before a byte is read unless this server issued it, expires with `uploadUrlTtlSeconds`, and serves
+nothing but the `PUT`. Against the in-memory store it also **accepts a single upload**: once the
+bytes land, a leaked URL can no longer replace them. Writing is not consuming either — redemption
+needs the signed handle, which is bound to the user who requested it.
+
+A presigned backend URL is a different animal: it is typically **replayable** until it expires — S3
+accepts as many `PUT`s as fit in `expiresInSeconds` — so there, a URL leaked to an access log can
+overwrite the bytes *after* the legitimate upload and before the action runs. The `sha256` pin is
+the defense that covers every backend at once: S3 signs it into the URL, so a different payload is
+rejected at upload time, and redemption re-verifies the digest regardless of what the backend
+checked. The tool instructs the model to pin by default; treat an unpinned upload as accepting that
+window.
+
+### Nothing to provision, and nothing to switch on
+
+It is on by default. With no `storage`, the server holds the objects in memory and serves its own
+upload endpoint under `<origin>/mcp/uploads`. The `fileUploads` option only *configures* that — a
+backend, size limits, ttls:
+
+```typescript
+agent.mountAiMcpServer();                             // in memory, single instance
+agent.mountAiMcpServer({ fileUploads: { storage } }); // a real backend
+```
+
+To turn the feature off, pass `fileUploads: false` — on the standalone server,
+`FOREST_MCP_FILE_UPLOADS=false`. The tool is not registered, the upload endpoint is never mounted,
+and `executeAction` stops mentioning either. Going through `enabledTools` would work too, but it is
+an allowlist — declining this one feature that way means naming every other tool and opting out of
+everything shipped after.
+
+> **Single instance only.** The upload and the redemption are two separate requests. With several
+> replicas, in cluster mode, or on a serverless runtime, one of them lands
+> on an instance that never saw the other and the action fails — intermittently, which reads as a
+> flaky feature rather than a misconfiguration. Objects are also lost on restart. The server warns
+> the first time an upload destination is asked for, and the failure names this cause. **Those deployments need a `storage`.**
+
+`ephemeralMaxTotalBytes` bounds what the in-memory store holds across all pending uploads, 64 MiB by
+default. Redeeming a file does not free it — the object lives until `handleTtlSeconds` so a retry
+after a failed action still finds it — so on the defaults the store holds about three max-size
+files per 45-minute window rather than a rolling 64 MiB. Size it against that, or shorten
+`handleTtlSeconds`. It is deliberately absolute rather than a multiple of `maxBytes`: derived, raising the
+per-file limit would multiply what the process can hold.
+
+### With a storage backend
+
+Provide `storage` for anything beyond a single instance. Any backend that can pre-authorize an
+upload and read the object back works — S3 presigned URLs (below), GCS signed URLs, Azure SAS. The
+package has no storage dependency of its own.
+
+### On the standalone server
+
+Uploads are on with the in-memory store, with the same single-instance caveat.
+
+For a real backend, a storage is an object with methods, so unlike every other standalone option it
+cannot travel through an environment variable. Point `FOREST_MCP_UPLOAD_STORAGE_MODULE` at a module
+that default-exports the options instead — a bad path, or a module that exports nothing, fails at
+startup rather than running with uploads silently disabled:
+
+```javascript
+// forest-upload-storage.js
+module.exports = {
+  storage: {
+    /* createUploadUrl / download / getSize, as below */
+  },
+  maxBytes: 50 * 1024 * 1024,
+  downloadTimeoutSeconds: 10,
+};
+```
+
+```bash
+FOREST_MCP_UPLOAD_STORAGE_MODULE=./forest-upload-storage.js npx forest-mcp-server
+```
+
+The module may also export a function, sync or async, returning the same options — useful when the
+backend needs credentials fetched at boot.
+
+### The client must be able to upload
+
+Step 2 is an ordinary HTTPS request, made by the client, outside the MCP protocol. The client has to
+be able to make it:
+
+- **Claude Code** and custom agents: works. The shell runs on the same machine as the developer, so
+  it reaches a `localhost` agent too — this is the one place the whole flow can be tried end to end
+  against a local agent. Verified.
+- **Claude Desktop, Claude.ai and Cowork**: the attached file lands in the code execution sandbox
+  and the model can `curl -X PUT -T <path> <uploadUrl>` — applying every header the tool returned,
+  since a pinned `sha256` is signed into `x-amz-checksum-sha256` on S3 and the PUT is rejected
+  without it. Two conditions, and both are needed:
+  1. **`uploadUrl` must be publicly reachable.** That sandbox is hosted and runs on its own
+     network, so a `localhost` or private address is never reachable from it, whatever else is
+     configured. An agent running on a developer's machine cannot be tested this way.
+  2. **Its host must be allowed for outbound traffic** in that sandbox. Where this is configured
+     differs between clients and versions — and on a managed workspace the setting may not be
+     exposed to the end user at all, in which case only an administrator can unblock the upload.
+     Do not promise your users a menu path; give them the host to get allowed.
+
+  Both are client-side and outside this server's control, so document your upload host for your
+  users.
+
+  **Verified end to end** from a Claude Desktop chat and from a Cowork cloud session: an agent
+  behind a public HTTPS URL, that host added to the sandbox's allowed domains, and the model's
+  `PUT` goes through. Before the host was allowed, the same sandbox answered `Host not in
+  allowlist` even for an ordinary public domain — so the allowlist is the whole of condition 2,
+  and satisfying it is enough. The Cowork run started from a single natural sentence, with no tool
+  named: the model found the form, requested a destination and pinned the `sha256` unprompted, and
+  no tool argument carried base64 — checked against the request bodies at the tunnel, not the
+  transcript.
+
+  One wrinkle observed there: the filename the action stores is whatever the client reports, and a
+  sandbox may normalize it (`rapport-1815.pdf` arrived as `rapport1815.pdf` while the bytes and
+  mime type were exact). Treat it as a label, not an identifier.
+
+The tool states this prerequisite in its description and repeats it in its response, so a model
+whose upload was blocked has the diagnosis in context.
+
+### Trying it locally
+
+`packages/_example` needs no configuration for this — no cloud account, no storage code.
+Its `review` collection carries an `Attach a document` action with a `File` and a `FileList` field.
+Start the example agent, connect an MCP client to it, and ask for that action with a file — the
+action reports the name, mime type and byte count it received.
+
+```mermaid
+sequenceDiagram
+    participant Client as MCP client
+    participant Server as MCP server
+    participant Storage as Storage backend
+    participant Agent as Forest Admin agent
+
+    Client->>Server: requestActionFileUpload {filename, mimeType, sha256?}
+    Server-->>Client: uploadUrl + fileHandle (user-bound JWT)
+    Client->>Storage: PUT raw bytes to uploadUrl
+    Note over Client,Storage: bytes bypass the server and the model
+    Client->>Server: executeAction {values: {field: "$uploadedFile:..."}}
+    Server->>Storage: download object
+    Note over Server: verify user, TTL, maxBytes, sha256 pin
+    Server->>Agent: executeAction with the file
+    Agent-->>Server: action result
+    Server-->>Client: result (the model only saw the handle)
+```
+
+The storage backend is pluggable, and this package has no storage dependency. Provide an
+implementation of `UploadStorage`; any backend that can pre-authorize an upload and read the object
+back works, such as S3 presigned URLs (below), GCS signed URLs, Azure SAS, or an endpoint you serve
+yourself. The only hard requirement is that the URL be reachable from the MCP client, since that is
+what uploads the bytes.
+
+```typescript
+import {
+  S3Client,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+} from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import type { UploadStorage } from '@forestadmin/mcp-server';
+
+const s3 = new S3Client({});
+const bucket = 'my-uploads-bucket';
+
+const storage: UploadStorage = {
+  async createUploadUrl({ key, mimeType, sha256, expiresInSeconds }) {
+    const command = new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      ContentType: mimeType,
+      ...(sha256 && { ChecksumSHA256: sha256 }),
+    });
+    const url = await getSignedUrl(s3, command, {
+      expiresIn: expiresInSeconds,
+      // Load-bearing: without it the checksum is hoisted to the query string, which S3 does not
+      // enforce — the pin would silently stop protecting the upload.
+      ...(sha256 && { unhoistableHeaders: new Set(['x-amz-checksum-sha256']) }),
+    });
+    return {
+      url,
+      headers: { 'Content-Type': mimeType, ...(sha256 && { 'x-amz-checksum-sha256': sha256 }) },
+    };
+  },
+  async getSize(key) {
+    const head = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+    return head.ContentLength;
+  },
+  async download(key) {
+    const object = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    return Buffer.from(await object.Body.transformToByteArray());
+  },
+};
+
+const server = new ForestMCPServer({
+  // ...
+  fileUploads: { storage },
+});
+```
+
+The other options are `keyPrefix` (default `mcp-uploads/`), `uploadUrlTtlSeconds` (default 15 min),
+`handleTtlSeconds` (default 45 min, longer than the upload URL so a slow upload still leaves time to
+run the action), `maxBytes` (default 20 MiB), `maxConcurrentDownloads` (default 5), and
+`downloadTimeoutSeconds` (default 15 s), and `ephemeralMaxTotalBytes` (default 64 MiB, in-memory store only).
+
+Lower `downloadTimeoutSeconds` if the clients calling your agent cut requests sooner than that. The
+whole `executeAction` has to fit inside their timeout: reading the object, encoding it, and running
+your action. A read that outlives the caller is wasted work — and left unbounded it would hold its
+concurrency slot after the caller gave up.
+
+A few properties matter in production.
+
+- The server stays stateless. The handle is a JWT signed with `authSecret`, so there is no database and no session affinity, and any replica can redeem a handle issued by another.
+- A handle is bound to the user it was issued to. Only that user's Bearer token can redeem it, and it expires with `handleTtlSeconds`. It stays redeemable until then, so keep the TTL short.
+- When the client sends `sha256` (hex or base64), the upload URL is pinned to that digest and the digest is checked again on the downloaded bytes at redemption. Content substituted after an upload URL leak cannot be redeemed.
+- **`maxBytes` does not bound memory on its own.** A pre-authorized upload URL cannot always cap the object size, so the limit is enforced at redemption: before downloading when `getSize` reports a size, and only after the bytes are in memory when it returns `undefined`. Implement `getSize` whenever the backend can answer it cheaply.
+- **`maxConcurrentDownloads` bounds concurrent downloads, not peak memory.** All the files one `executeAction` call references are held together until the call completes, so a form with N file fields holds up to N × `maxBytes` whatever the concurrency limit is. Size `maxBytes` against the number of file fields your actions declare.
+- **A timed-out read is abandoned, not cancelled.** `UploadStorage.download` takes no `AbortSignal`, so when `downloadTimeoutSeconds` fires the concurrency slot is freed while the underlying read keeps running. Against a backend slower than that timeout the number of reads in flight can therefore exceed `maxConcurrentDownloads`. Keep `downloadTimeoutSeconds` low so a slow backend fails fast instead of accumulating.
+- The server never deletes objects, and does not delete them once redeemed either: `executeAction` downloads every reference before it sets fields or runs, so consuming on read would leave a model retrying after any later failure with handles whose objects are gone, told the upload failed when it had not. Configure a lifecycle rule on the storage backend, for example deleting objects under `keyPrefix` after one day; the in-memory store reclaims on `handleTtlSeconds` and on its own total.
+
+Only `executeAction` resolves handles. `getActionForm` echoes field values back to the model, so a
+handle stays a handle there: resolving it would put the file content back into the model's context.
+
+**Change hooks never see a handle.** On the `getActionForm` path, file references are withheld from
+`tryToSetFields`, so a hook fired by another field reads the file field as unset rather than as a
+string it would call `.buffer` on. On the `executeAction` path the handles are already resolved, so
+a hook receives the file as the data uri it expects. Either way a hook never has to know this
+side-channel exists.
+
 ## API Endpoints
 
 Once running, the MCP server exposes the following endpoints:

package/dist/cli.js

@@ -5,26 +5,45 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const server_1 = __importDefault(require("./server"));
+const load_file_uploads_1 = __importDefault(require("./utils/load-file-uploads"));
 const parse_domain_list_1 = __importDefault(require("./utils/parse-domain-list"));
 const parse_tool_list_1 = __importDefault(require("./utils/parse-tool-list"));
 const toSeconds = (value) => (value === undefined ? undefined : Number(value));
-// Start the server when run directly as CLI
-const server = new server_1.default({
-    forestServerUrl: process.env.FOREST_SERVER_URL || 'https://api.forestadmin.com',
-    forestAppUrl: process.env.FOREST_APP_URL || 'https://app.forestadmin.com',
-    envSecret: process.env.FOREST_ENV_SECRET,
-    authSecret: process.env.FOREST_AUTH_SECRET,
-    enabledTools: (0, parse_tool_list_1.default)(process.env.FOREST_MCP_ENABLED_TOOLS),
-    allowedOAuthClients: (0, parse_domain_list_1.default)(process.env.FOREST_MCP_ALLOWED_OAUTH_CLIENTS),
-    agentUrl: process.env.FOREST_AGENT_URL,
-    // normalizeTokenTtl rejects NaN and non-positive values, so a bad variable fails at startup.
-    tokenTtl: {
-        accessTokenSeconds: toSeconds(process.env.FOREST_MCP_ACCESS_TOKEN_TTL_SECONDS),
-        refreshTokenSeconds: toSeconds(process.env.FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS),
-    },
-});
-server.run().catch(error => {
+async function main() {
+    // Uploads are on by default, so this variable only means one thing: 'false' turns them off.
+    // Anything else fails at startup like every other option — 'FALSE' or '0' silently leaving the
+    // feature on is the kind of surprise an operator meets in production.
+    const rawFileUploadsFlag = process.env.FOREST_MCP_FILE_UPLOADS;
+    if (rawFileUploadsFlag !== undefined && !['true', 'false'].includes(rawFileUploadsFlag)) {
+        throw new Error(`Invalid FOREST_MCP_FILE_UPLOADS "${rawFileUploadsFlag}": use 'false' to turn action file ` +
+            'uploads off. They are on by default.');
+    }
+    // Loaded before constructing, so a bad module fails at startup like every other option. Uploads
+    // are on without it, held in memory; this only points them at a real backend. 'false' wins over
+    // a configured module — an operator setting both is turning the feature off.
+    const fileUploads = rawFileUploadsFlag === 'false'
+        ? false
+        : await (0, load_file_uploads_1.default)(process.env.FOREST_MCP_UPLOAD_STORAGE_MODULE);
+    const server = new server_1.default({
+        forestServerUrl: process.env.FOREST_SERVER_URL || 'https://api.forestadmin.com',
+        forestAppUrl: process.env.FOREST_APP_URL || 'https://app.forestadmin.com',
+        envSecret: process.env.FOREST_ENV_SECRET,
+        authSecret: process.env.FOREST_AUTH_SECRET,
+        enabledTools: (0, parse_tool_list_1.default)(process.env.FOREST_MCP_ENABLED_TOOLS),
+        allowedOAuthClients: (0, parse_domain_list_1.default)(process.env.FOREST_MCP_ALLOWED_OAUTH_CLIENTS),
+        agentUrl: process.env.FOREST_AGENT_URL,
+        // normalizeTokenTtl rejects NaN and non-positive values, so a bad variable fails at startup.
+        tokenTtl: {
+            accessTokenSeconds: toSeconds(process.env.FOREST_MCP_ACCESS_TOKEN_TTL_SECONDS),
+            refreshTokenSeconds: toSeconds(process.env.FOREST_MCP_REFRESH_TOKEN_TTL_SECONDS),
+        },
+        // Not a truthy spread: `false` is a meaningful value and has to reach the constructor.
+        ...(fileUploads !== undefined && { fileUploads }),
+    });
+    await server.run();
+}
+main().catch(error => {
     console.error('[FATAL] Server crashed:', error);
     process.exit(1);
 });
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NsaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7QUFFQSxzREFBdUM7QUFDdkMsa0ZBQXdEO0FBQ3hELDhFQUFvRDtBQUVwRCxNQUFNLFNBQVMsR0FBRyxDQUFDLEtBQWMsRUFBRSxFQUFFLENBQUMsQ0FBQyxLQUFLLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDO0FBRXhGLDRDQUE0QztBQUM1QyxNQUFNLE1BQU0sR0FBRyxJQUFJLGdCQUFlLENBQUM7SUFDakMsZUFBZSxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsaUJBQWlCLElBQUksNkJBQTZCO0lBQy9FLFlBQVksRUFBRSxPQUFPLENBQUMsR0FBRyxDQUFDLGNBQWMsSUFBSSw2QkFBNkI7SUFDekUsU0FBUyxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsaUJBQWlCO0lBQ3hDLFVBQVUsRUFBRSxPQUFPLENBQUMsR0FBRyxDQUFDLGtCQUFrQjtJQUMxQyxZQUFZLEVBQUUsSUFBQSx5QkFBYSxFQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsd0JBQXdCLENBQUM7SUFDakUsbUJBQW1CLEVBQUUsSUFBQSwyQkFBZSxFQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsZ0NBQWdDLENBQUM7SUFDbEYsUUFBUSxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsZ0JBQWdCO0lBQ3RDLDZGQUE2RjtJQUM3RixRQUFRLEVBQUU7UUFDUixrQkFBa0IsRUFBRSxTQUFTLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxtQ0FBbUMsQ0FBQztRQUM5RSxtQkFBbUIsRUFBRSxTQUFTLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxvQ0FBb0MsQ0FBQztLQUNqRjtDQUNGLENBQUMsQ0FBQztBQUVILE1BQU0sQ0FBQyxHQUFHLEVBQUUsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLEVBQUU7SUFDekIsT0FBTyxDQUFDLEtBQUssQ0FBQyx5QkFBeUIsRUFBRSxLQUFLLENBQUMsQ0FBQztJQUNoRCxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQ2xCLENBQUMsQ0FBQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NsaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7QUFFQSxzREFBdUM7QUFDdkMsa0ZBQXdEO0FBQ3hELGtGQUF3RDtBQUN4RCw4RUFBb0Q7QUFFcEQsTUFBTSxTQUFTLEdBQUcsQ0FBQyxLQUFjLEVBQUUsRUFBRSxDQUFDLENBQUMsS0FBSyxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQztBQUV4RixLQUFLLFVBQVUsSUFBSTtJQUNqQiw0RkFBNEY7SUFDNUYsK0ZBQStGO0lBQy9GLHNFQUFzRTtJQUN0RSxNQUFNLGtCQUFrQixHQUFHLE9BQU8sQ0FBQyxHQUFHLENBQUMsdUJBQXVCLENBQUM7SUFFL0QsSUFBSSxrQkFBa0IsS0FBSyxTQUFTLElBQUksQ0FBQyxDQUFDLE1BQU0sRUFBRSxPQUFPLENBQUMsQ0FBQyxRQUFRLENBQUMsa0JBQWtCLENBQUMsRUFBRSxDQUFDO1FBQ3hGLE1BQU0sSUFBSSxLQUFLLENBQ2Isb0NBQW9DLGtCQUFrQixxQ0FBcUM7WUFDekYsc0NBQXNDLENBQ3pDLENBQUM7SUFDSixDQUFDO0lBRUQsZ0dBQWdHO0lBQ2hHLGdHQUFnRztJQUNoRyw2RUFBNkU7SUFDN0UsTUFBTSxXQUFXLEdBQ2Ysa0JBQWtCLEtBQUssT0FBTztRQUM1QixDQUFDLENBQUUsS0FBZTtRQUNsQixDQUFDLENBQUMsTUFBTSxJQUFBLDJCQUFlLEVBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxnQ0FBZ0MsQ0FBQyxDQUFDO0lBRTFFLE1BQU0sTUFBTSxHQUFHLElBQUksZ0JBQWUsQ0FBQztRQUNqQyxlQUFlLEVBQUUsT0FBTyxDQUFDLEdBQUcsQ0FBQyxpQkFBaUIsSUFBSSw2QkFBNkI7UUFDL0UsWUFBWSxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsY0FBYyxJQUFJLDZCQUE2QjtRQUN6RSxTQUFTLEVBQUUsT0FBTyxDQUFDLEdBQUcsQ0FBQyxpQkFBaUI7UUFDeEMsVUFBVSxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUMsa0JBQWtCO1FBQzFDLFlBQVksRUFBRSxJQUFBLHlCQUFhLEVBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyx3QkFBd0IsQ0FBQztRQUNqRSxtQkFBbUIsRUFBRSxJQUFBLDJCQUFlLEVBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxnQ0FBZ0MsQ0FBQztRQUNsRixRQUFRLEVBQUUsT0FBTyxDQUFDLEdBQUcsQ0FBQyxnQkFBZ0I7UUFDdEMsNkZBQTZGO1FBQzdGLFFBQVEsRUFBRTtZQUNSLGtCQUFrQixFQUFFLFNBQVMsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLG1DQUFtQyxDQUFDO1lBQzlFLG1CQUFtQixFQUFFLFNBQVMsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLG9DQUFvQyxDQUFDO1NBQ2pGO1FBQ0QsdUZBQXVGO1FBQ3ZGLEdBQUcsQ0FBQyxXQUFXLEtBQUssU0FBUyxJQUFJLEVBQUUsV0FBVyxFQUFFLENBQUM7S0FDbEQsQ0FBQyxDQUFDO0lBRUgsTUFBTSxNQUFNLENBQUMsR0FBRyxFQUFFLENBQUM7QUFDckIsQ0FBQztBQUVELElBQUksRUFBRSxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUMsRUFBRTtJQUNuQixPQUFPLENBQUMsS0FBSyxDQUFDLHlCQUF5QixFQUFFLEtBQUssQ0FBQyxDQUFDO0lBQ2hELE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDbEIsQ0FBQyxDQUFDLENBQUMifQ==

package/dist/file-uploads/ephemeral-storage.d.ts

@@ -0,0 +1,46 @@
+import type { UploadStorage } from './types';
+import type { Logger } from '../server';
+import type { Router } from 'express';
+interface EphemeralOptions {
+    maxBytes: number;
+    maxTotalBytes: number;
+    ttlSeconds: number;
+    issuedTtlSeconds: number;
+    publicBaseUrl: string;
+}
+/**
+ * In-memory UploadStorage serving its own PUT endpoint on the MCP server's own origin, used when
+ * `fileUploads` is enabled without a storage backend. Nothing to provision — and nothing shared:
+ * objects live in this process only.
+ *
+ * The upload and the redemption are two separate requests, so behind several replicas, in cluster
+ * mode, or on a serverless runtime one lands on an instance that never saw the other. Those
+ * deployments need a real backend; this one is for a single instance.
+ */
+export default class EphemeralStorage implements UploadStorage {
+    private readonly logger;
+    private readonly objects;
+    private readonly issued;
+    private storedBytes;
+    private inFlightBytes;
+    private options;
+    private announced;
+    constructor(logger: Logger);
+    /** Separate from the constructor because the server only knows its own base url later. */
+    configure(options: EphemeralOptions): void;
+    createUploadUrl({ key }: {
+        key: string;
+    }): Promise<{
+        url: string;
+        method: string;
+    }>;
+    download(key: string): Promise<Buffer>;
+    getSize(key: string): Promise<number | undefined>;
+    createRouter(): Router;
+    private write;
+    private read;
+    private forget;
+    private expire;
+}
+export {};
+//# sourceMappingURL=ephemeral-storage.d.ts.map

package/dist/file-uploads/ephemeral-storage.js

@@ -0,0 +1,216 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+// Issued keys are cheap next to a body — a few hundred bytes against up to maxBytes — but they
+// outlive the request that asked for one, and nothing forces the caller to ever upload. This bounds
+// them at about 2 MB, orders of magnitude beyond any real number of pending uploads.
+const MAX_OUTSTANDING_KEYS = 10000;
+/**
+ * In-memory UploadStorage serving its own PUT endpoint on the MCP server's own origin, used when
+ * `fileUploads` is enabled without a storage backend. Nothing to provision — and nothing shared:
+ * objects live in this process only.
+ *
+ * The upload and the redemption are two separate requests, so behind several replicas, in cluster
+ * mode, or on a serverless runtime one lands on an instance that never saw the other. Those
+ * deployments need a real backend; this one is for a single instance.
+ */
+class EphemeralStorage {
+    constructor(logger) {
+        this.logger = logger;
+        this.objects = new Map();
+        this.issued = new Map();
+        this.storedBytes = 0;
+        this.inFlightBytes = 0;
+        this.announced = false;
+    }
+    /** Separate from the constructor because the server only knows its own base url later. */
+    configure(options) {
+        this.options = options;
+    }
+    async createUploadUrl({ key }) {
+        const { publicBaseUrl, issuedTtlSeconds } = this.options;
+        // Said here rather than at startup: uploads are on by default, so a boot-time warning would
+        // reach every agent including those whose actions have no file field. This fires when the
+        // feature is actually used, which is when the limitation starts to matter.
+        if (!this.announced) {
+            this.announced = true;
+            this.logger('Warn', '[fileUploads] no storage backend: uploaded files are held in memory, on this instance ' +
+                'only. They are lost on restart, and a deployment with several replicas or a serverless ' +
+                'runtime needs a real backend on the fileUploads option.');
+        }
+        // Recorded so the endpoint only accepts keys it handed out. Without this, anything reaching the
+        // origin could fill the store under keys of its own and deny the feature to everyone else.
+        this.expire();
+        // Insertion order, so this drops the least recent pending upload. Refusing to issue instead
+        // would let one caller deny the feature to everyone; whoever is evicted gets a 404 telling
+        // them to ask again.
+        if (this.issued.size >= MAX_OUTSTANDING_KEYS) {
+            const [oldest] = this.issued.keys();
+            this.issued.delete(oldest);
+            this.logger('Warn', `[fileUploads] ${MAX_OUTSTANDING_KEYS} upload urls are outstanding: dropped ${oldest}, ` +
+                'whose upload never came. Something is requesting destinations without uploading.');
+        }
+        this.issued.set(key, Date.now() + issuedTtlSeconds * 1000);
+        return {
+            url: `${publicBaseUrl.replace(/\/+$/, '')}/${encodeURIComponent(key)}`,
+            method: 'PUT',
+        };
+    }
+    async download(key) {
+        const stored = this.read(key);
+        if (!stored) {
+            throw new Error('not found in the in-memory store. Either the upload never completed — a refused one is ' +
+                'answered with a 413 — or it expired after handleTtlSeconds, or it reached another ' +
+                'instance: this store only holds what this instance received, so several replicas or a ' +
+                'serverless runtime need a storage backend on the fileUploads option.');
+        }
+        // Deliberately NOT dropped on read. executeAction downloads every reference before it sets
+        // fields or runs, so any later failure — a mistyped field name, a throwing hook — would leave
+        // the model retrying with handles whose objects are gone, told the upload failed when it did
+        // not. expire() and maxTotalBytes reclaim instead. The upload url stays single-use; that is a
+        // different property, enforced on the issued key.
+        return stored.body;
+    }
+    async getSize(key) {
+        return this.read(key)?.body.length;
+    }
+    createRouter() {
+        const router = express_1.default.Router();
+        const { logger } = this;
+        // The uploads route is mounted ahead of the request logger, which needs the body parsers this
+        // one must precede, so each outcome is reported here instead.
+        const refuse = (res, key, status, reason) => {
+            logger('Warn', `[fileUploads] refused ${key}: ${reason}`);
+            res.status(status).json({ error: reason });
+        };
+        router.put('/:key', (req, res) => {
+            const { key } = req.params;
+            const { maxBytes, maxTotalBytes } = this.options;
+            this.expire();
+            // Consumed here rather than in write(): two concurrent PUTs for one key would both pass a
+            // has() check and the later would silently overwrite the earlier. A failed attempt burns the
+            // url too, which is the honest reading of single-use — retrying needs a fresh destination.
+            if (!this.issued.delete(key)) {
+                // An object still sitting here means the url was already used, which is the case an
+                // integrator actually hits. Reported apart because "or it has expired" sends them looking
+                // at ttls instead.
+                if (this.objects.has(key)) {
+                    refuse(res, key, 409, 'this upload url was already used; request a fresh one');
+                }
+                else {
+                    refuse(res, key, 404, 'no upload was authorized for this key: it was never issued, already used, or ' +
+                        'expired — or it was issued by another instance, which cannot be seen from here');
+                }
+                return;
+            }
+            // Answered before reading anything when the client declares a body that cannot fit.
+            const declared = Number(req.headers['content-length']);
+            if (Number.isFinite(declared) && declared > maxBytes) {
+                refuse(res, key, 413, `the file is larger than the ${maxBytes} byte limit`);
+                return;
+            }
+            // Dropped now rather than in write(): counting bytes this upload is about to replace would
+            // refuse a replacement that fits, and keeping them until 'end' would hold both at once.
+            this.forget(key);
+            // Refused before a byte is read whenever the store has no room at all, whatever this body
+            // turns out to be. `>=` rather than `>` so the answer is a 507 naming the store, instead of a
+            // 413 decided on the first chunk that reads as a problem with the file.
+            if (this.storedBytes + this.inFlightBytes >= maxTotalBytes) {
+                refuse(res, key, 507, `the in-memory store is full (${maxTotalBytes} bytes)`);
+                return;
+            }
+            const chunks = [];
+            let reserved = 0;
+            let refused = '';
+            // Reserved as the bytes arrive, not once the body is complete: concurrent uploads would
+            // otherwise each weigh their own size against the same stale total and all be admitted.
+            const release = () => {
+                this.inFlightBytes -= reserved;
+                reserved = 0;
+            };
+            req.on('data', chunk => {
+                if (refused)
+                    return;
+                const { length } = chunk;
+                if (reserved + length > maxBytes) {
+                    refused = `the file is larger than the ${maxBytes} byte limit`;
+                }
+                else if (this.storedBytes + this.inFlightBytes + length > maxTotalBytes) {
+                    refused = `the in-memory store is full (${maxTotalBytes} bytes)`;
+                }
+                if (refused) {
+                    // Kept reading, but no longer kept: destroying the socket or answering now would reach a
+                    // client that is still writing as a connection reset instead of a 413.
+                    chunks.length = 0;
+                    release();
+                    return;
+                }
+                reserved += length;
+                this.inFlightBytes += length;
+                chunks.push(chunk);
+            });
+            req.on('end', () => {
+                release();
+                if (refused) {
+                    refuse(res, key, 413, refused);
+                    return;
+                }
+                // A throw here would be an uncaughtException and take the whole server down, not just this
+                // request: Buffer.concat allocates and can fail under memory pressure.
+                try {
+                    const body = Buffer.concat(chunks);
+                    this.write(key, body);
+                    logger('Debug', `[fileUploads] stored ${key} (${body.length} bytes)`);
+                    res.status(200).end();
+                }
+                catch (error) {
+                    logger('Error', `[fileUploads] could not store ${key}: ${error?.message}`);
+                    res.status(500).json({ error: 'could not store the upload' });
+                }
+            });
+            // An aborted upload never reaches 'end', so its reservation would leak and shrink the store
+            // for good. Idempotent with the release above.
+            req.on('close', release);
+            // The path a client abort takes, which is the most common real failure here — silence would
+            // leave a 20 MiB upload that vanished with no trace anywhere.
+            req.on('error', (error) => {
+                logger('Warn', `[fileUploads] upload of ${key} failed after ${reserved} bytes: ${error.message}`);
+                release();
+                res.destroy();
+            });
+        });
+        return router;
+    }
+    write(key, body) {
+        this.forget(key);
+        this.objects.set(key, { body, expiresAt: Date.now() + this.options.ttlSeconds * 1000 });
+        this.storedBytes += body.length;
+    }
+    read(key) {
+        this.expire();
+        return this.objects.get(key);
+    }
+    forget(key) {
+        const stored = this.objects.get(key);
+        if (stored) {
+            this.objects.delete(key);
+            this.storedBytes -= stored.body.length;
+        }
+    }
+    expire() {
+        const now = Date.now();
+        this.objects.forEach((stored, key) => {
+            if (stored.expiresAt <= now)
+                this.forget(key);
+        });
+        this.issued.forEach((expiresAt, key) => {
+            if (expiresAt <= now)
+                this.issued.delete(key);
+        });
+    }
+}
+exports.default = EphemeralStorage;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXBoZW1lcmFsLXN0b3JhZ2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZmlsZS11cGxvYWRzL2VwaGVtZXJhbC1zdG9yYWdlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7O0FBSUEsc0RBQThCO0FBTzlCLCtGQUErRjtBQUMvRixvR0FBb0c7QUFDcEcscUZBQXFGO0FBQ3JGLE1BQU0sb0JBQW9CLEdBQUcsS0FBTSxDQUFDO0FBVXBDOzs7Ozs7OztHQVFHO0FBQ0gsTUFBcUIsZ0JBQWdCO0lBUW5DLFlBQTZCLE1BQWM7UUFBZCxXQUFNLEdBQU4sTUFBTSxDQUFRO1FBUDFCLFlBQU8sR0FBRyxJQUFJLEdBQUcsRUFBd0IsQ0FBQztRQUMxQyxXQUFNLEdBQUcsSUFBSSxHQUFHLEVBQWtCLENBQUM7UUFDNUMsZ0JBQVcsR0FBRyxDQUFDLENBQUM7UUFDaEIsa0JBQWEsR0FBRyxDQUFDLENBQUM7UUFFbEIsY0FBUyxHQUFHLEtBQUssQ0FBQztJQUVvQixDQUFDO0lBRS9DLDBGQUEwRjtJQUMxRixTQUFTLENBQUMsT0FBeUI7UUFDakMsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUM7SUFDekIsQ0FBQztJQUVELEtBQUssQ0FBQyxlQUFlLENBQUMsRUFBRSxHQUFHLEVBQW1CO1FBQzVDLE1BQU0sRUFBRSxhQUFhLEVBQUUsZ0JBQWdCLEVBQUUsR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDO1FBRXpELDRGQUE0RjtRQUM1RiwwRkFBMEY7UUFDMUYsMkVBQTJFO1FBQzNFLElBQUksQ0FBQyxJQUFJLENBQUMsU0FBUyxFQUFFLENBQUM7WUFDcEIsSUFBSSxDQUFDLFNBQVMsR0FBRyxJQUFJLENBQUM7WUFDdEIsSUFBSSxDQUFDLE1BQU0sQ0FDVCxNQUFNLEVBQ04sd0ZBQXdGO2dCQUN0Rix5RkFBeUY7Z0JBQ3pGLHlEQUF5RCxDQUM1RCxDQUFDO1FBQ0osQ0FBQztRQUVELGdHQUFnRztRQUNoRywyRkFBMkY7UUFDM0YsSUFB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

package/dist/file-uploads/file-reference.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sentinel prefix used inside action form values, e.g.
+ *   { "document": "$uploadedFile:<jwt>" }
+ * A string rather than an object, so it passes the agent-client field validation and stays
+ * cheap when getActionForm echoes it back into the model's context.
+ */
+export declare const UPLOADED_FILE_PREFIX = "$uploadedFile:";
+/**
+ * Isolated so that the file URIs the MCP specification is designing (SEP-2631) can be recognized
+ * here without touching the resolution path.
+ */
+export default function parseFileReference(value: unknown): string | null;
+//# sourceMappingURL=file-reference.d.ts.map