@formio/uag 1.9.1 → 1.10.0

package/README.md

@@ -88,6 +88,7 @@ The following tools provided by the UAG can be described as follows:
 | find_submissions | Enables the agent to parse a user's natural language request into a query for a submission, or a specific field of a particular submission. |
 | submission_update | Provides the AI agent with the ability to update an existing submission, either by supplying unfilled fields or updating existing ones if allowed. Provides the AI agent with the context of the existing field values, allowing inline changes or edits. |
 | agent_provide_data | Enables an AI Agent to be able to analyze existing submission data according to rules defined with a configurable **Criteria**. It will then instruct the Agent to provide generated data for fields configured for a specific **persona** using the `submission_update` tool. Please read the [**Agentic Workflows**](#agentic-workflows) section for more information about this toolset. |
+| fetch_external_data | This tool enables an AI Agent to pull external data into a form workflow through the use of either a Resource component, Select with URL, or a Data Source component. |
 
 ## Agentic Workflows
 One of the more powerful features of the **UAG** is the `agent_process_data` tool. This tool provides the ability to instruct a generically trained agent how to analyze existing submission data, and then produce its own data by following a configurable **Criteria**. This behavior historically could only be achieved using a specifically trained agent, which does not provide any benefits of dynamic configurability that the Form.io platform offers. This tool is able to achieve this goal by providing a generally trained agent with the necessary "context" it needs to accurately produce its own data as part of an automated workflow. This feature is particularly helpful if you wish to utilize the UAG within an Agentic Workflow, where the AI Agent is capable of understanding structured data, and then contribute its own data by following the configured **Criteria** "context" provided by the UAG. 

package/lib/UAGFormInterface.d.ts

@@ -91,6 +91,10 @@ export declare class UAGFormInterface extends FormInterface {
     } | {
         data?: undefined;
     } | null;
+    /**
+     * Override the process methods for the UAG.
+     */
+    process(submission: Submission, auth: AuthRequest, headers?: any, findQuery?: any, additional?: any[]): Promise<any>;
     /**
      * Get the relevant fields from the current form. This will return any non-nested input components whose
      * values have not already been set within the data model. This allows the agent to know what fields still need to be

package/lib/UAGFormInterface.js

@@ -74,10 +74,10 @@ class UAGFormInterface extends appserver_1.FormInterface {
         }
         if (component.type === 'select' || component.type === 'selectboxes') {
             if (component.dataSrc === 'url') {
-                fieldInfo.options = [{ label: '** ANY VALUE IS ALLOWED **', value: 'Options are loaded from a URL.' }];
+                fieldInfo.options = [{ label: '** USE fetch_external_data TOOL **', value: `Call the \`fetch_external_data\` tool with \`field_path\`="${path}" to retrieve available options from the external URL.` }];
             }
             else if (component.dataSrc === 'resource') {
-                fieldInfo.options = [{ label: '** ANY VALUE IS ALLOWED **', value: `Options are loaded from the Form.io resource (${component.data.resource}).` }];
+                fieldInfo.options = [{ label: '** USE fetch_external_data TOOL **', value: `Call the \`fetch_external_data\` tool with \`field_path\`="${path}" to retrieve available options from the Form.io resource (${component.data.resource}).` }];
             }
             else if (component.dataSrc === 'json') {
                 fieldInfo.options = [{ label: '** ANY VALUE IS ALLOWED **', value: 'Options are not dynamically defined.' }];
@@ -95,6 +95,9 @@ class UAGFormInterface extends appserver_1.FormInterface {
                 }
             }
         }
+        if (component.type === 'datasource') {
+            fieldInfo.options = [{ label: '** USE fetch_external_data TOOL **', value: `Call the \`fetch_external_data\` tool with \`field_path\`="${path}" to retrieve data from the external datasource.` }];
+        }
         fieldInfo.nested = this.isNestedComponent(component);
         return fieldInfo;
     }
@@ -203,6 +206,13 @@ class UAGFormInterface extends appserver_1.FormInterface {
                 break;
             case 'selectboxes':
             case 'select':
+                if (component.dataSrc === 'url' || component.dataSrc === 'resource') {
+                    rule += `You MUST first call the \`fetch_external_data\` tool with the \`field_path\` set to this component's \`data_path\` to retrieve the available options, then select ${this.isMultiple(component) ? 'one or more (as comma separated values)' : 'one'} of the returned options. Use the **value** (not the label) when setting this field's data.`;
+                }
+                else {
+                    rule += `The value must be ${this.isMultiple(component) ? 'one or more (as comma separated values)' : 'one'} of the following options provided in the "**Options**" section of that component, formatted as " - Label (value)":`;
+                }
+                break;
             case 'radio':
                 rule += `The value must be ${this.isMultiple(component) ? 'one or more (as comma separated values)' : 'one'} of the following options provided in the "**Options**" section of that component, formatted as " - Label (value)":`;
                 break;
@@ -221,6 +231,20 @@ class UAGFormInterface extends appserver_1.FormInterface {
             case 'email':
                 rule += 'The value must be a valid email address.';
                 break;
+            case 'datasource':
+                rule += 'You MUST first call the `fetch_external_data` tool with the `field_path` set to this component\'s `data_path` to retrieve the external data. The value will be set automatically from the fetched data.';
+                break;
+            case 'survey':
+                rule += 'The value is an object of question/value pairs based on the following survey configuration.\n';
+                rule += '    **Keys**: The value `keys` will be the "value" property for each question in the survey configuration.';
+                component.questions.forEach((question, index) => {
+                    rule += `\n      - **${question.label}** (${question.value}): ${question.tooltip || ''}`;
+                });
+                rule += '\n\n    **Values**: Only ONE of the the following values are allowed for each question.';
+                component.values.forEach((value) => {
+                    rule += `\n      - **${value.label}** (${value.value})`;
+                });
+                break;
             default:
                 rule += '';
         }
@@ -276,6 +300,22 @@ class UAGFormInterface extends appserver_1.FormInterface {
                 return null;
         }
     }
+    /**
+     * Override the process methods for the UAG.
+     */
+    async process(submission, auth, headers = {}, findQuery = {}, additional = []) {
+        const processors = [...core_1.Processors, ...additional];
+        // Remove the 'fetch' processor since UAG handles this with the fetch_external_data tool.
+        const fetchIndex = processors.findIndex((p) => p.name === 'fetch');
+        if (fetchIndex !== -1) {
+            processors.splice(fetchIndex, 1);
+        }
+        // Return the processed submission data.
+        const context = await super.process(submission, auth, headers, findQuery, processors);
+        // Filter the "required" validation since the UAG retrieves required fields separately.
+        context.scope.errors = context.scope.errors.filter((error) => (error.ruleName !== 'required'));
+        return context;
+    }
     /**
      * Get the relevant fields from the current form. This will return any non-nested input components whose
      * values have not already been set within the data model. This allows the agent to know what fields still need to be
@@ -302,8 +342,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
             optional: { components: [], rules: {} }
         };
         const nestedPaths = [];
-        const context = await this.process(submission, authInfo, null, null, null, [
-            ...core_1.Processors,
+        const context = await this.process(submission, authInfo, null, null, [
             {
                 name: 'getFields',
                 shouldProcess: () => true,
@@ -379,11 +418,7 @@ class UAGFormInterface extends appserver_1.FormInterface {
             }
         ]);
         if (context.scope?.errors?.length) {
-            // Filter the "required" validation since those are added to the fieldInfo separately.
-            context.scope.errors = context.scope.errors.filter((error) => (error.ruleName !== 'required'));
-            if (context.scope.errors?.length) {
-                fieldInfo.errors = this.convertToFormFieldErrors((0, core_1.interpolateErrors)(context.scope.errors));
-            }
+            fieldInfo.errors = this.convertToFormFieldErrors((0, core_1.interpolateErrors)(context.scope.errors));
         }
         return fieldInfo;
     }
@@ -455,16 +490,24 @@ class UAGFormInterface extends appserver_1.FormInterface {
                 prefix += '  ';
             }
             else if (this.inputComponent(component) && (0, core_1.componentHasValue)(component, value)) {
-                if (typeof value === 'string' &&
-                    ((component.editor === 'ckeditor') ||
-                        (component.editor === 'quill'))) {
-                    value = this.htmlToMarkdown(value);
+                const modelType = core_1.Utils.getModelType(component);
+                if ((0, lodash_1.isObjectLike)(value)) {
+                    value = JSON.stringify(value);
+                }
+                else if (modelType === 'string' && (0, lodash_1.isString)(value)) {
+                    const editor = component.editor;
+                    if (editor === 'ckeditor' || editor === 'quill') {
+                        value = this.htmlToMarkdown(value);
+                    }
+                    else {
+                        value = `"${value.trim()}"`;
+                    }
                 }
                 uagData.push({
                     prefix,
                     path,
                     label: component.label || component.key || path,
-                    value: (0, lodash_1.isObjectLike)(value) ? JSON.stringify(value) : value
+                    value
                 });
             }
         }, false, false, undefined, undefined, undefined, (component, data) => {

package/lib/UAGProjectInterface.d.ts

@@ -1,7 +1,7 @@
 import { ProjectInterface, SubmissionRequest } from "@formio/appserver";
 import { UAGConfig } from "./config";
 import { Form } from "@formio/core";
-import { NextFunction, Response } from "express";
+import { NextFunction, Response, Router } from "express";
 import { UAGFormInterface } from "./UAGFormInterface";
 import { ResponseTemplate, UAGTemplate } from "./template";
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -13,8 +13,8 @@ export declare class UAGProjectInterface extends ProjectInterface {
     get config(): UAGConfig;
     constructor(endpoint?: string);
     initialize(): Promise<void>;
-    addForm(form: Form, key: string): UAGFormInterface | undefined;
-    router(): Promise<any>;
+    addForm(form: Form, machineName: string): UAGFormInterface | undefined;
+    uagRouter(): Router;
     authorizeRequest(req: SubmissionRequest, res: Response, next: NextFunction): Promise<Response<any, Record<string, any>> | undefined>;
     mcpJSONResponse(data?: object, isError?: boolean): {
         isError?: boolean | undefined;

package/lib/UAGProjectInterface.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UAGProjectInterface = void 0;
 const appserver_1 = require("@formio/appserver");
+const express_1 = require("express");
 const tools_1 = require("./tools");
 const router_1 = require("./router");
 const template_1 = require("./template");
@@ -36,25 +37,25 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
             }
         }
     }
-    addForm(form, key) {
-        const formInterface = super.addForm(form, key);
+    addForm(form, machineName) {
+        const formInterface = super.addForm(form, machineName);
         if (!formInterface)
             return;
-        key = key || formInterface?.form?.key;
+        machineName = formInterface?.form?.machineName;
         if (form.tags?.includes('uag')) {
-            debug(`Registering UAG form: ${key}`);
+            debug(`Registering UAG form: ${machineName}`);
             formInterface.uag = {
-                machineName: key,
-                name: form.name || form.path || key,
-                title: form.title || form.name || key,
+                machineName: machineName,
+                name: form.name || form.path || machineName,
+                title: form.title || form.name || machineName,
                 description: form.properties?.description || `A form to submit new ${form.title} records.`
             };
             this.formNames.push(formInterface.uag.name);
         }
         return formInterface;
     }
-    async router() {
-        const router = await super.router();
+    uagRouter() {
+        const router = (0, express_1.Router)();
         const uagRouter = (0, router_1.UAGRouter)(this);
         router.use('/mcp', (req, res, next) => this.authorizeRequest(req, res, next), uagRouter);
         return router;

package/lib/config.d.ts

@@ -44,6 +44,7 @@ export type UAGToolOverride = {
     submission_update?: ToolInfo;
     find_submissions?: ToolInfo;
     agent_provide_data?: ToolInfo;
+    fetch_external_data?: ToolInfo;
 };
 export interface UAGConfig extends ServerConfig {
     baseUrl?: string;

package/lib/index.d.ts

@@ -7,6 +7,7 @@ export type UAGModule = ServerModule & {
 };
 export declare class UAGServer extends Server {
     constructor(config?: UAGConfig);
+    router(): Promise<import("express-serve-static-core").Router>;
 }
 export * from '@formio/appserver';
 export * from './config';

package/lib/index.js

@@ -27,6 +27,7 @@ class UAGServer extends appserver_1.Server {
             baseUrl: (0, lodash_1.get)(process.env, 'BASE_URL', '').toString(),
             license: (0, lodash_1.get)(process.env, 'UAG_LICENSE', '').toString(),
             submissionProxy: true,
+            processAsClient: true,
             auth: { pkce: true }
         }));
         this.use({
@@ -34,6 +35,12 @@ class UAGServer extends appserver_1.Server {
             FormInterface: UAGFormInterface_1.UAGFormInterface
         });
     }
+    async router() {
+        const router = await super.router();
+        const uagProject = Object.values(this.projectRouter?.projects || {})[0];
+        router.use(uagProject.uagRouter());
+        return router;
+    }
 }
 exports.UAGServer = UAGServer;
 __exportStar(require("@formio/appserver"), exports);

package/lib/router.js

@@ -39,7 +39,9 @@ function UAGRouter(project) {
             const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // Use "undefined" to trigger stateless mode.
             });
-            project.mcpServer.connect(transport);
+            // Close any existing connection before connecting to a new transport (required in SDK 1.26.0+)
+            await project.mcpServer.close();
+            await project.mcpServer.connect(transport);
             if (!transport) {
                 res.status(500).json(JSON.parse(createJsonRpcErrorResponse(-32603, "Unable to create MCP transport.")));
                 return;
@@ -57,7 +59,9 @@ function UAGRouter(project) {
             const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // Use "undefined" to trigger stateless mode.
             });
-            project.mcpServer.connect(transport);
+            // Close any existing connection before connecting to a new transport (required in SDK 1.26.0+)
+            await project.mcpServer.close();
+            await project.mcpServer.connect(transport);
             if (!transport) {
                 res.status(500).json(JSON.parse(createJsonRpcErrorResponse(-32603, "Unable to create MCP transport.")));
                 return;

package/lib/template.d.ts

@@ -5,7 +5,6 @@ import { UAGTemplateConfig } from './config';
  */
 export declare enum ResponseTemplate {
     collectedData = "collectedData",
-    submittedData = "submittedData",
     fieldRules = "fieldRules",
     allFieldsCollected = "allFieldsCollected",
     getFormFieldsEmpty = "getFormFieldsEmpty",
@@ -32,10 +31,13 @@ export declare enum ResponseTemplate {
     fields = "fields",
     fieldList = "fieldList",
     fieldValues = "fieldValues",
+    formData = "formData",
     getAvailableForms = "getAvailableForms",
     noFormsAvailable = "noFormsAvailable",
     uagComponentNotFound = "uagComponentNotFound",
-    agentProcessData = "agentProcessData"
+    agentProcessData = "agentProcessData",
+    fetchExternalData = "fetchExternalData",
+    fetchExternalDataError = "fetchExternalDataError"
 }
 export declare class UAGTemplate {
     config: UAGTemplateConfig;

package/lib/template.js

@@ -43,7 +43,6 @@ const lodash_1 = require("lodash");
 var ResponseTemplate;
 (function (ResponseTemplate) {
     ResponseTemplate["collectedData"] = "collectedData";
-    ResponseTemplate["submittedData"] = "submittedData";
     ResponseTemplate["fieldRules"] = "fieldRules";
     ResponseTemplate["allFieldsCollected"] = "allFieldsCollected";
     ResponseTemplate["getFormFieldsEmpty"] = "getFormFieldsEmpty";
@@ -70,10 +69,13 @@ var ResponseTemplate;
     ResponseTemplate["fields"] = "fields";
     ResponseTemplate["fieldList"] = "fieldList";
     ResponseTemplate["fieldValues"] = "fieldValues";
+    ResponseTemplate["formData"] = "formData";
     ResponseTemplate["getAvailableForms"] = "getAvailableForms";
     ResponseTemplate["noFormsAvailable"] = "noFormsAvailable";
     ResponseTemplate["uagComponentNotFound"] = "uagComponentNotFound";
     ResponseTemplate["agentProcessData"] = "agentProcessData";
+    ResponseTemplate["fetchExternalData"] = "fetchExternalData";
+    ResponseTemplate["fetchExternalDataError"] = "fetchExternalDataError";
 })(ResponseTemplate || (exports.ResponseTemplate = ResponseTemplate = {}));
 class UAGTemplate {
     constructor(config = {}) {

package/lib/templates/collectedData.md

@@ -1,5 +1,5 @@
 ## Collected Data
-IMPORTANT: When presenting the values to the user, it must appear exactly as it will be submitted; e.g "user@example.com", "(555) 123-4560"
+Here is the data collected so far:
 
-<% data.forEach(function(item) { %><%= item.prefix %>- **<%= item.label %>**: <%= item.value %>
+<% data.forEach(function(item) { %><%= item.prefix %>- **<%= item.label %>** (`data_path`: "<%= item.path %>"): <%= item.value %>
 <% }); %>

package/lib/templates/fetchExternalData.md

@@ -0,0 +1,10 @@
+<% if (options) { %>Here are the available select options for **<%= label %>** (`data_path`: "<%= dataPath %>"):
+
+<% options.forEach(function(option) { %>
+- label: <%= option.label %>, value: `<%= typeof option.value === 'object' ? JSON.stringify(option.value) : option.value %>`<% }); %>
+
+Use the **value** (not the label) when setting this field's data via `collect_field_data`.
+<% } else if (formData) { %>The "fetched" value for **<%= label %>** (`data_path`: `<%= dataPath %>`) is included with following `form_data`:
+
+<%= formData %>
+<% } %>

package/lib/templates/fetchExternalDataError.md

@@ -0,0 +1,6 @@
+Error fetching external data for field `<%= dataPath %>`: <%= error %>
+
+Please verify:
+- The form name and `data_path` are correct
+- The field is a select component with `dataSrc` of "url" or "resource", or a datasource component
+- The external data source is accessible

package/lib/templates/fieldValues.md

@@ -1,4 +1,4 @@
 <% data.forEach(function(item) { %><%= item.prefix %>
-Question: **<%= item.label %>**:
+Question: **<%= item.label %>** (`data_path`="<%= item.path %>"):
   - Answer: `<%= item.value %>`
 <% }); %>

package/lib/templates/formData.md

@@ -0,0 +1,5 @@
+## Current `form_data`
+Here is the current value for the `form_data` property including all user provided, fetched, and calculated values.
+
+<% data.forEach(function(item) { %> - **<%= item.path %>**: <%= item.value %>
+<% }); %>

package/lib/templates/submitValidationError.md

@@ -1,4 +1,4 @@
-Cannot submit the form due to the following reasons:
+There are some validation errors in the data collected:
 <% validationErrors.forEach(function(error) { %>
  - <% if (error.label && error.path) { %>**<%= error.label %> (<%= error.path %>)**: <% } %><%= error.message %><% }); %>
 

package/lib/tools/SchemaBuilder.d.ts

@@ -83,9 +83,9 @@ export declare class SchemaBuilder {
      *
      * ```json
      * [
-     *   "email",
-     *   "firstName",
-     *   "lastName"
+     *   "employee.email",
+     *   "employee.firstName",
+     *   "employee.lastName"
      * ]
      */
     fields_requested(): this;
@@ -113,6 +113,14 @@ export declare class SchemaBuilder {
      * @returns
      */
     persona(): this;
+    /**
+     * The data_path of a specific field within the form.
+     */
+    data_path(): this;
+    /**
+     * An optional search value to filter select options server-side.
+     */
+    search_value(): this;
     /**
      * An array of field updates to apply to the `form_data`.
      * Each update specifies the `data_path` and the complete new value.
@@ -120,11 +128,11 @@ export declare class SchemaBuilder {
      * ```json
      * [
      *   {
-     *     "data_path": "firstName",
+     *     "data_path": "customer.firstName",
      *     "new_value": "John"
      *   },
      *   {
-     *     "data_path": "lastName",
+     *     "data_path": "customer.lastName",
      *     "new_value": "Doe"
      *   }
      * ]

package/lib/tools/SchemaBuilder.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchemaBuilder = void 0;
 const zod_1 = __importDefault(require("zod"));
+const DATA_PATH_DESCRIPTION = `The \`data_path\` (or "full path") to a component's instance value within a form submission (e.g., "customer.firstName"). Use \`get_form_fields\` to find the \`data_path\` of this component.`;
 /**
  * Schema builder for tool input schemas.
  */
@@ -42,7 +43,7 @@ class SchemaBuilder {
      * ```
      */
     form_data() {
-        this.schema.form_data = zod_1.default.record(zod_1.default.string().describe('The `data_path` of collected field.'), zod_1.default.any().describe(`The value collected for the field. ${this.valueRules}`)).optional().default({}).describe('The current data collected so far for the whole form without any updates applied. Include ALL previously collected field data to maintain session state.');
+        this.schema.form_data = zod_1.default.record(zod_1.default.string().describe(DATA_PATH_DESCRIPTION), zod_1.default.any().describe(`The value collected for the field. ${this.valueRules}`)).optional().default({}).describe('The current data collected so far for the whole form without any updates applied. Include ALL previously collected field data to maintain session state.');
         return this;
     }
     /**
@@ -63,7 +64,7 @@ class SchemaBuilder {
      * ```
      */
     field_paths() {
-        this.schema.field_paths = zod_1.default.array(zod_1.default.string()).describe('An array of `data_path`s to get detailed information for specific fields. Each `data_path` within the array should correlate to the fields the user has provided values for. The `data_path`s can be found using the `get_form_fields` tool.');
+        this.schema.field_paths = zod_1.default.array(zod_1.default.string().describe(DATA_PATH_DESCRIPTION)).describe("An array of `data_path`(s) to get detailed information for specific fields.");
         return this;
     }
     /**
@@ -101,10 +102,23 @@ class SchemaBuilder {
      */
     search_query() {
         this.schema.search_query = zod_1.default.array(zod_1.default.object({
-            data_path: zod_1.default.string().describe('The data path of the field used to search (e.g., "email", "customer.firstName", or "parent.email")'),
-            operator: zod_1.default.enum(['equals', 'not_equals', 'contains', 'starts_with', 'ends_with', 'regex', 'in', 'nin', 'greater_than', 'greater_than_equal', 'less_than', 'less_than_equal']).optional().default('contains').describe('The operator to use for matching. "equals" for exact match, "contains" for substring match, "starts_with" or "ends_with" for prefix/suffix match, "regex" for regular expression match, "greater_than" or "less_than" only for numeric values, "in" if searching for multiple values as comma-separated values, "nin" if excluding multiple values as comma-separated values.'),
+            data_path: zod_1.default.string().describe(DATA_PATH_DESCRIPTION),
+            operator: zod_1.default.enum([
+                'equals',
+                'not_equals',
+                'contains',
+                'starts_with',
+                'ends_with',
+                'regex',
+                'in',
+                'nin',
+                'greater_than',
+                'greater_than_equal',
+                'less_than',
+                'less_than_equal'
+            ]).optional().default('contains').describe('The operator to use for matching. "equals" for exact match, "contains" for substring match, "starts_with" or "ends_with" for prefix/suffix match, "regex" for regular expression match, "greater_than" or "less_than" only for numeric values, "in" if searching for multiple values as comma-separated values, "nin" if excluding multiple values as comma-separated values.'),
             search_value: zod_1.default.string().describe('The value of the field to use when searching.')
-        }).describe('Object containing the `data_path` and search value. Use `get_form_fields` to get all the field information to populate this search query object.')).describe('Array of search criteria to find matching submissions. All criteria must match (AND logic). Use `get_form_fields` to get `data_path`s.');
+        }).describe('Object containing the `data_path` and search value. Use `get_form_fields` to get all the field information to populate this search query object.')).describe('Array of search criteria to find matching submissions. All criteria must match (AND logic).');
         return this;
     }
     /**
@@ -113,13 +127,13 @@ class SchemaBuilder {
      *
      * ```json
      * [
-     *   "email",
-     *   "firstName",
-     *   "lastName"
+     *   "employee.email",
+     *   "employee.firstName",
+     *   "employee.lastName"
      * ]
      */
     fields_requested() {
-        this.schema.fields_requested = zod_1.default.array(zod_1.default.string()).optional().describe('An array of "data_path"(s) for values you wish to include in the result. If not provided, only submission IDs and timestamps are returned. Use `get_form_fields` to get valid `data_path`s. (e.g., ["email"] - "What is the email address for the employee Joe Smith?")');
+        this.schema.fields_requested = zod_1.default.array(zod_1.default.string().describe(DATA_PATH_DESCRIPTION)).optional().describe("An array of `data_path`(s) for values you wish to include in the result. If not provided, only submission IDs and timestamps are returned. (e.g., [\"employee.email\"] - \"What is the email address for the employee Joe Smith?\")");
         return this;
     }
     /**
@@ -161,6 +175,20 @@ class SchemaBuilder {
         this.schema.persona = zod_1.default.string().optional().describe('The agent persona "type" to use when processing the existing submission data. The persona provides context to the agent on how to interpret and understand the data within the form submission. If not provided, the default persona defined within the form\'s UAG settings will be used.');
         return this;
     }
+    /**
+     * The data_path of a specific field within the form.
+     */
+    data_path() {
+        this.schema.data_path = zod_1.default.string().describe(DATA_PATH_DESCRIPTION);
+        return this;
+    }
+    /**
+     * An optional search value to filter select options server-side.
+     */
+    search_value() {
+        this.schema.search_value = zod_1.default.string().optional().describe('An optional search string to filter the select options server-side. The component must have a `searchField` configured for this to take effect.');
+        return this;
+    }
     /**
      * An array of field updates to apply to the `form_data`.
      * Each update specifies the `data_path` and the complete new value.
@@ -168,11 +196,11 @@ class SchemaBuilder {
      * ```json
      * [
      *   {
-     *     "data_path": "firstName",
+     *     "data_path": "customer.firstName",
      *     "new_value": "John"
      *   },
      *   {
-     *     "data_path": "lastName",
+     *     "data_path": "customer.lastName",
      *     "new_value": "Doe"
      *   }
      * ]
@@ -180,7 +208,7 @@ class SchemaBuilder {
      */
     updates() {
         this.schema.updates = zod_1.default.array(zod_1.default.object({
-            data_path: zod_1.default.string().describe('The `data_path` of the field to update. To find the data_path, you can use the `get_form_fields` tool.'),
+            data_path: zod_1.default.string().describe(DATA_PATH_DESCRIPTION),
             new_value: zod_1.default.any().describe(`The complete new value for the field. ${this.valueRules}`)
         }).describe('A single field update including the `data_path` and new value.')).describe('An array of field updates to apply to the `form_data`. Each update specifies the `data_path` and the complete new value.');
         return this;

package/lib/tools/fetchExternalData.d.ts

@@ -0,0 +1,3 @@
+import { UAGProjectInterface } from "../UAGProjectInterface";
+import { ToolInfo } from "./utils";
+export declare const fetchExternalData: (project: UAGProjectInterface) => Promise<ToolInfo>;

package/lib/tools/fetchExternalData.js

@@ -0,0 +1,268 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchExternalData = void 0;
+const template_1 = require("../template");
+const core_1 = require("@formio/core");
+const SchemaBuilder_1 = require("./SchemaBuilder");
+const lodash_1 = require("lodash");
+const error = require('debug')('formio:uag:fetchExternalData:error');
+/**
+ * Strip HTML tags from a string.
+ */
+function stripHtml(str) {
+    return str.replace(/<[^>]*>/g, '').trim();
+}
+/**
+ * Extract label from an item using the component's template.
+ * For resource select items, the item is a full submission object with data nested under `item.data`.
+ * The template may reference `item.propertyName` which could be at `item.data.propertyName`.
+ */
+function extractLabel(item, component, evalContext) {
+    if (component.template) {
+        evalContext.item = item; // Add the current item to the interpolation context for template evaluation
+        const label = core_1.Evaluator.interpolateString(component.template, evalContext);
+        if (label !== undefined && label !== null) {
+            return stripHtml(String(label));
+        }
+    }
+    // Fallback: try common label properties
+    return item.label || item.name || item.title || String(item);
+}
+/**
+ * Extract value from an item using the component's valueProperty.
+ */
+function extractValue(item, component) {
+    if (component.valueProperty) {
+        return (0, lodash_1.get)(item, component.valueProperty);
+    }
+    return item;
+}
+/**
+ * Check if a component is a select-type component with external data (url or resource).
+ */
+function isExternalSelect(component) {
+    if (component.type !== 'select' && component.type !== 'selectboxes')
+        return false;
+    const dataSrc = component.dataSrc;
+    return dataSrc === 'url' || dataSrc === 'resource';
+}
+/**
+ * Check if a component is a datasource component.
+ */
+function isDatasource(component) {
+    return component.type === 'datasource';
+}
+/**
+ * Interpolate header key/value pairs, filtering out empty ones.
+ */
+function interpolateHeaders(headers, context) {
+    const result = {};
+    if (!headers || !Array.isArray(headers))
+        return result;
+    for (const header of headers) {
+        const key = header.key ? core_1.Evaluator.interpolateString(header.key, context) : '';
+        const value = header.value ? core_1.Evaluator.interpolateString(header.value, context) : '';
+        if (key && value) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+const fetchExternalData = async (project) => {
+    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.fetch_external_data || {}, {
+        name: 'fetch_external_data',
+        title: 'Fetch External Data',
+        description: 'Fetch external data for a component that loads data from an external URL, a Form.io Resource, or a DataSource. Use this tool when `get_form_fields` indicates that a field requires calling `fetch_external_data` to retrieve its data. For select components, this returns the available options. For datasource components, this returns the fetched data. You can optionally provide a `search_value` to filter results server-side. If the component\'s URL or headers contain interpolation tokens (e.g. `{{ data.someField }}`), you MUST provide `form_data` with the current collected data so the tokens can be resolved.',
+        inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
+            .form_name()
+            .data_path()
+            .form_data()
+            .search_value().schema,
+        execute: async ({ form_name, data_path, form_data, search_value }, extra) => {
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            try {
+                const component = form.getComponent(data_path);
+                if (!component) {
+                    return project.mcpResponse(template_1.ResponseTemplate.fetchExternalDataError, {
+                        dataPath: data_path,
+                        error: `No component found at path "${data_path}".`
+                    }, true);
+                }
+                // Build the interpolation context from the current form data.
+                const submission = form_data ? form.convertToSubmission(form_data) : { data: {} };
+                const evalContext = {
+                    form: form.form,
+                    component,
+                    components: form.form.components,
+                    data: submission.data || {},
+                    row: submission.data || {},
+                    submission
+                };
+                if (isDatasource(component)) {
+                    const items = await fetchDatasourceData(component, extra.authInfo, evalContext);
+                    (0, lodash_1.set)(submission.data || {}, data_path, items);
+                    const errors = await form.validateData(submission, extra.authInfo);
+                    if (errors?.length > 0) {
+                        return project.mcpResponse(template_1.ResponseTemplate.fieldValidationErrors, { invalidFields: errors });
+                    }
+                    return project.mcpResponse(template_1.ResponseTemplate.fetchExternalData, {
+                        label: component.label || component.key,
+                        dataPath: data_path,
+                        options: false,
+                        formData: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.formData, {
+                            data: form.formatData(submission.data)
+                        })
+                    });
+                }
+                if (!isExternalSelect(component)) {
+                    return project.mcpResponse(template_1.ResponseTemplate.fetchExternalDataError, {
+                        dataPath: data_path,
+                        error: `Component at "${data_path}" is of type "${component.type}" and does not load external data. This tool only supports select/selectboxes components with dataSrc "url" or "resource", and datasource components.`
+                    }, true);
+                }
+                const selectComponent = component;
+                const dataSrc = selectComponent.dataSrc;
+                if (dataSrc !== 'url' && dataSrc !== 'resource') {
+                    return project.mcpResponse(template_1.ResponseTemplate.fetchExternalDataError, {
+                        dataPath: data_path,
+                        error: `Component at "${data_path}" has dataSrc "${dataSrc}". Only "url" and "resource" are supported by this tool.`
+                    }, true);
+                }
+                let items = [];
+                if (dataSrc === 'url') {
+                    items = await fetchUrlData(selectComponent, search_value, extra.authInfo, evalContext);
+                }
+                else if (dataSrc === 'resource') {
+                    items = await fetchResourceData(selectComponent, search_value, extra.authInfo, project, evalContext);
+                }
+                const options = items.map(item => ({
+                    label: extractLabel(item, selectComponent, evalContext),
+                    value: extractValue(item, selectComponent)
+                }));
+                return project.mcpResponse(template_1.ResponseTemplate.fetchExternalData, {
+                    label: selectComponent.label || selectComponent.key,
+                    dataPath: data_path,
+                    options,
+                    formData: {}
+                });
+            }
+            catch (err) {
+                error('Error fetching external data:', err);
+                return project.mcpResponse(template_1.ResponseTemplate.fetchExternalDataError, {
+                    dataPath: data_path,
+                    error: err instanceof Error ? err.message : 'Unknown error'
+                }, true);
+            }
+        }
+    });
+};
+exports.fetchExternalData = fetchExternalData;
+async function fetchDatasourceData(component, authInfo, context) {
+    const fetchConfig = component.fetch;
+    if (!fetchConfig?.url) {
+        throw new Error('No URL configured for this datasource component.');
+    }
+    // Interpolate the URL
+    const interpolatedUrl = core_1.Evaluator.interpolateString(fetchConfig.url, context);
+    const url = new URL(interpolatedUrl);
+    // Build and interpolate headers
+    const headers = interpolateHeaders(fetchConfig.headers, context);
+    // Add auth token if forwardHeaders or authenticate is enabled
+    if ((fetchConfig.forwardHeaders || fetchConfig.authenticate) && authInfo?.token) {
+        headers['x-jwt-token'] = authInfo.token;
+    }
+    const response = await fetch(url.toString(), {
+        method: (fetchConfig.method || 'get').toUpperCase(),
+        headers
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    let result = await response.json();
+    if (!Array.isArray(result)) {
+        // If the result has a 'results' property that is an array, use that
+        if (result.results && Array.isArray(result.results)) {
+            result = result.results;
+        }
+        else {
+            // Wrap single objects in an array
+            result = [result];
+        }
+    }
+    return result;
+}
+async function fetchUrlData(component, search_value, authInfo, context) {
+    const data = component.data;
+    const baseUrl = data?.url;
+    if (!baseUrl) {
+        throw new Error('No URL configured for this component.');
+    }
+    // Interpolate the URL
+    const interpolatedUrl = core_1.Evaluator.interpolateString(baseUrl, context);
+    const url = new URL(interpolatedUrl);
+    // Add filter query string if configured (interpolate the filter string)
+    if (component.filter) {
+        const interpolatedFilter = core_1.Evaluator.interpolateString(component.filter, context);
+        const filterParams = new URLSearchParams(interpolatedFilter);
+        filterParams.forEach((value, key) => {
+            url.searchParams.set(key, value);
+        });
+    }
+    // Add search parameter if provided
+    if (search_value && component.searchField) {
+        url.searchParams.set(component.searchField, search_value);
+    }
+    // Add limit
+    const limit = component.limit || 100;
+    url.searchParams.set('limit', String(limit));
+    // Build and interpolate headers
+    const headers = interpolateHeaders(data.headers, context);
+    // Add auth token if authenticate is enabled
+    if (component.authenticate && authInfo?.token) {
+        headers['x-jwt-token'] = authInfo.token;
+    }
+    const response = await fetch(url.toString(), { headers });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    let result = await response.json();
+    // Navigate to selectValues path if configured
+    if (component.selectValues) {
+        result = (0, lodash_1.get)(result, component.selectValues, result);
+    }
+    if (!Array.isArray(result)) {
+        throw new Error('Response is not an array. Check the URL and selectValues configuration.');
+    }
+    return result;
+}
+async function fetchResourceData(component, search_value, authInfo, project, context) {
+    const data = component.data;
+    const resourceId = data?.resource;
+    if (!resourceId) {
+        throw new Error('No resource ID configured for this component.');
+    }
+    const resourceForm = await project.getFormById(resourceId);
+    if (!resourceForm) {
+        throw new Error(`Resource form with ID "${resourceId}" not found.`);
+    }
+    const query = {};
+    // Add search filter if provided
+    if (search_value && component.searchField) {
+        query[`data.${component.searchField}__regex`] = `/${search_value}/i`;
+    }
+    // Add component filter if configured (interpolate the filter string)
+    if (component.filter) {
+        const interpolatedFilter = core_1.Evaluator.interpolateString(component.filter, context);
+        const filterParams = new URLSearchParams(interpolatedFilter);
+        filterParams.forEach((value, key) => {
+            query[key] = value;
+        });
+    }
+    // Add limit
+    query.limit = component.limit || 100;
+    const result = await resourceForm.find(query, authInfo);
+    return result.items || [];
+}

package/lib/tools/index.d.ts

@@ -8,6 +8,7 @@ import { findSubmission } from "./findSubmission";
 import { submissionUpdate } from "./submissionUpdate";
 import { ToolInfo } from "./utils";
 import { UAGProjectInterface } from "../UAGProjectInterface";
+import { fetchExternalData } from "./fetchExternalData";
 export * from './utils';
-export { getForms, getFormFields, getFieldInfo, collectData, confirmSubmission, submitCompletedForm, findSubmission, submissionUpdate };
+export { getForms, getFormFields, getFieldInfo, collectData, confirmSubmission, submitCompletedForm, findSubmission, submissionUpdate, fetchExternalData };
 export declare const getTools: (project: UAGProjectInterface) => Promise<ToolInfo[]>;

package/lib/tools/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTools = exports.submissionUpdate = exports.findSubmission = exports.submitCompletedForm = exports.confirmSubmission = exports.collectData = exports.getFieldInfo = exports.getFormFields = exports.getForms = void 0;
+exports.getTools = exports.fetchExternalData = exports.submissionUpdate = exports.findSubmission = exports.submitCompletedForm = exports.confirmSubmission = exports.collectData = exports.getFieldInfo = exports.getFormFields = exports.getForms = void 0;
 const getForms_1 = require("./getForms");
 Object.defineProperty(exports, "getForms", { enumerable: true, get: function () { return getForms_1.getForms; } });
 const getFormFields_1 = require("./getFormFields");
@@ -32,6 +32,8 @@ Object.defineProperty(exports, "findSubmission", { enumerable: true, get: functi
 const submissionUpdate_1 = require("./submissionUpdate");
 Object.defineProperty(exports, "submissionUpdate", { enumerable: true, get: function () { return submissionUpdate_1.submissionUpdate; } });
 const agentProvideData_1 = require("./agentProvideData");
+const fetchExternalData_1 = require("./fetchExternalData");
+Object.defineProperty(exports, "fetchExternalData", { enumerable: true, get: function () { return fetchExternalData_1.fetchExternalData; } });
 __exportStar(require("./utils"), exports);
 const getTools = async (project) => {
     return [
@@ -43,7 +45,8 @@ const getTools = async (project) => {
         await (0, submitForm_1.submitCompletedForm)(project),
         await (0, findSubmission_1.findSubmission)(project),
         await (0, submissionUpdate_1.submissionUpdate)(project),
-        await (0, agentProvideData_1.agentProvideData)(project)
+        await (0, agentProvideData_1.agentProvideData)(project),
+        await (0, fetchExternalData_1.fetchExternalData)(project)
     ];
 };
 exports.getTools = getTools;

package/lib/tools/submitForm.js

@@ -40,20 +40,12 @@ const submitCompletedForm = async (project) => {
                 });
             }
             catch (err) {
-                const errors = [];
+                let errors = [];
                 if (err && err.name === 'ValidationError' && err.details) {
-                    for (const detail of err.details) {
-                        if (detail.message) {
-                            errors.push({
-                                label: detail.context?.label || 'Field',
-                                path: detail.context?.path,
-                                message: detail.message
-                            });
-                        }
-                    }
+                    errors = form.convertToFormFieldErrors(err.details);
                 }
                 return project.mcpResponse(template_1.ResponseTemplate.submitValidationError, {
-                    validationErrors: errors.length ? errors : [{ message: err.message || 'Unknown error during submission' }]
+                    validationErrors: errors.length ? errors : [{ message: err.message || err.toString() }]
                 }, true);
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -24,14 +24,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@formio/appserver": "^2.11.1",
+    "@formio/appserver": "^2.12.0",
     "@formio/core": "2.5.1-dev.291.6557e4e",
-    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@modelcontextprotocol/sdk": "1.27.0",
     "cors": "^2.8.6",
-    "debug": "^4.4.1",
-    "dotenv": "^17.2.1",
+    "debug": "^4.4.3",
+    "dotenv": "^17.3.1",
     "express": "^5.2.1",
-    "jsonwebtoken": "^9.0.2",
+    "jsonwebtoken": "^9.0.3",
     "lodash": "^4.17.23",
     "node-cache": "^5.1.2",
     "node-html-markdown": "^2.0.0",
@@ -46,10 +46,10 @@
     "@types/jsonwebtoken": "^9.0.10",
     "@types/lodash": "^4.17.23",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.3.0",
     "@types/supertest": "^6.0.3",
     "chai": "^6.2.2",
-    "mocha": "^11.3.0",
+    "mocha": "^11.7.5",
     "supertest": "^7.2.2",
     "terser": "^5.46.0",
     "ts-node": "^10.9.2",

package/lib/templates/submittedData.md

@@ -1,4 +0,0 @@
-**Submission Data Summary:** (IMPORTANT NOTE: When presenting the values to the user, it must appear exactly as they are in the submission; e.g "user@example.com", "(555) 123-4560")
-<% data.forEach(function(item) { %>
-- **<%= item.label %>**: <%= item.value %>
-<% }); %>