feat: upload files through the MCP server for action File fields

.gitignore

@@ -18,6 +18,7 @@ lerna-debug.log
 # forest-bff openapi --output default destination
 openapi.json
 
+
 # yarn
 yarn-error.log
 .vscode/settings.json

packages/_example/src/forest/agent.ts

@@ -93,7 +93,9 @@ export default function makeAgent() {
 
       return resultBuilder.value((rows?.[0]?.value as number) ?? 0);
     })
-    .mountAiMcpServer(allowedOAuthClients ? { allowedOAuthClients } : undefined)
+    .mountAiMcpServer({
+      ...(allowedOAuthClients && { allowedOAuthClients }),
+    })
 
     .customizeCollection('card', customizeCard)
     .customizeCollection('account', customizeAccount)

packages/_example/src/forest/customizations/review.ts

@@ -1,4 +1,35 @@
 import type { ReviewCustomizer } from '../typings';
 
 export default (collection: ReviewCustomizer) =>
-  collection.addManyToOneRelation('store', 'store', { foreignKey: 'storeId' });
+  collection
+    .addManyToOneRelation('store', 'store', { foreignKey: 'storeId' })
+
+    .addAction('Attach a document', {
+      scope: 'Single',
+      form: [
+        { label: 'Document', type: 'File', isRequired: true },
+        { label: 'Extra pages', type: 'FileList' },
+        { label: 'Note', type: 'String' },
+      ],
+      execute: async (context, resultBuilder) => {
+        const document = context.formValues.Document as {
+          name: string;
+          mimeType: string;
+          buffer: Buffer;
+        };
+        const extras = (context.formValues['Extra pages'] ?? []) as (typeof document)[];
+
+        const describe = (file: typeof document) =>
+          `${file?.name} (${file?.mimeType}, ${file?.buffer?.length} bytes)`;
+
+        return resultBuilder.success(
+          [
+            `Received ${describe(document)}`,
+            extras.length
+              ? `plus ${extras.length}: ${extras.map(describe).join(', ')}`
+              : 'no extras',
+            `note: ${context.formValues.Note ?? '-'}`,
+          ].join(' — '),
+        );
+      },
+    });

packages/agent-bff/src/action/action-form-mapper.ts

@@ -5,7 +5,8 @@ const ENUM_TYPE = 'Enum';
 
 export interface ActionFormFieldResponse {
   name: string;
-  type: string;
+  /** Verbatim from the agent, so a list type is `['String']` rather than `'StringList'`. */
+  type: string | [string];
   value: unknown;
   isRequired: boolean;
   enumValues?: string[] | null;

packages/agent-bff/src/action/agent-action-client.ts

@@ -7,7 +7,8 @@ import createAgentHttpRequester from '../agent/create-agent-http-requester';
 
 export interface ActionFormField {
   getName(): string;
-  getType(): string;
+  /** A list type is the array the agent sent, `['String']`, not `'StringList'`. */
+  getType(): string | [string];
   getValue(): unknown;
   isRequired(): boolean | undefined;
 }

packages/agent-client/src/action-fields/action-field.ts

@@ -1,4 +1,5 @@
 import type FieldFormStates from './field-form-states';
+import type { PlainField } from './types';
 
 export default abstract class ActionField {
   private readonly fieldsFormStates: FieldFormStates;
@@ -17,10 +18,14 @@ export default abstract class ActionField {
     return this.name;
   }
 
-  getType(): string {
+  getType(): PlainField['type'] {
     return this.field?.getType();
   }
 
+  getTypeName(): string {
+    return this.field?.getTypeName();
+  }
+
   getValue() {
     return this.field?.getValue();
   }

packages/agent-client/src/action-fields/field-form-states.ts

@@ -7,6 +7,7 @@ import type {
 import HttpRequester from '../http-requester';
 import ActionFieldMultipleChoice from './action-field-multiple-choice';
 import FieldGetter from './field-getter';
+import encodeFileFieldValue from './file-value';
 
 export default class FieldFormStates {
   private readonly fields: FieldGetter[];
@@ -70,7 +71,7 @@ export default class FieldFormStates {
     const field = this.getField(name);
     if (!field) throw new Error(`Field "${name}" not found in action "${this.actionName}"`);
 
-    field.getPlainField().value = value;
+    field.getPlainField().value = encodeFileFieldValue(field.getTypeName(), value, name);
 
     const fieldHasHook = field.getPlainField().hook;
 

packages/agent-client/src/action-fields/field-getter.ts

@@ -19,7 +19,19 @@ export default class FieldGetter {
     return this.plainField.field;
   }
 
-  getType(): string {
+  /** Exactly what the agent sent: a list type is the array `['File']`, not `'FileList'`. */
+  getType(): PlainField['type'] {
     return this.plainField.type;
   }
+
+  /**
+   * The same type as a single name, `['File']` becoming `'FileList'`. For dispatching on the type
+   * and for reporting it to a reader; never for anything that goes back to an agent, which echoes
+   * `plainField` verbatim through loadChanges and matches only the array form.
+   */
+  getTypeName(): string {
+    const { type } = this.plainField;
+
+    return Array.isArray(type) ? `${type[0]}List` : type;
+  }
 }

packages/agent-client/src/action-fields/file-value.ts

@@ -0,0 +1,68 @@
+import type { File } from '@forestadmin/datasource-toolkit';
+
+import { makeDataUri } from '@forestadmin/datasource-toolkit';
+
+function isFileType(type: string): boolean {
+  return type === 'File';
+}
+
+function isFileListType(type: string): boolean {
+  return type === 'FileList';
+}
+
+function isFile(value: unknown): value is File {
+  const candidate = value as File;
+
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Buffer.isBuffer(candidate.buffer) &&
+    typeof candidate.mimeType === 'string' &&
+    typeof candidate.name === 'string'
+  );
+}
+
+function fileError(fieldName: string, detail: string): Error {
+  return new Error(`Field "${fieldName}" ${detail}`);
+}
+
+function encodeFileValue(value: unknown, fieldName: string): unknown {
+  if (value === null || value === undefined) return value;
+
+  // Callers that address the file indirectly (mcp-server upload handles) keep their sentinel:
+  // validating strings here would break them, and the agent owns the final validation.
+  if (typeof value === 'string') return value;
+
+  if (isFile(value)) return makeDataUri(value);
+
+  throw fileError(
+    fieldName,
+    'expects a file: pass { buffer, mimeType, name } or a string holding a data uri.',
+  );
+}
+
+export default function encodeFileFieldValue(
+  type: string,
+  value: unknown,
+  fieldName: string,
+): unknown {
+  if (isFileListType(type)) {
+    if (value === null || value === undefined) return value;
+
+    if (!Array.isArray(value)) {
+      throw fileError(fieldName, 'expects a list of files: pass an array.');
+    }
+
+    return value.map(item => encodeFileValue(item, fieldName));
+  }
+
+  if (isFileType(type)) return encodeFileValue(value, fieldName);
+
+  // A file reaching a field that is not declared as one is never intentional, and it would be
+  // JSON-serialized into the column as {"buffer":{"type":"Buffer",...}} without any error.
+  if (isFile(value)) {
+    throw fileError(fieldName, `is a ${type} field and cannot hold a file.`);
+  }
+
+  return value;
+}

packages/agent-client/src/action-fields/types.ts

@@ -12,7 +12,8 @@ export type PlainFieldOption = {
 
 export type PlainField = {
   field: string;
-  type: string;
+  // Agents emit list types as a single-element array, e.g. ['File'] or ['String'].
+  type: string | [string];
   description?: string;
   value?: unknown;
   isRequired: boolean;

packages/agent-client/src/index.ts

@@ -68,3 +68,4 @@ export function createRemoteAgentClient(params: {
 }
 
 export type { RecordId, SelectOptions } from './types';
+export type { File } from '@forestadmin/datasource-toolkit';