@formio/uag 1.6.0 → 1.8.0

package/README.md

@@ -1,4 +1,4 @@
-# The Form.io "Universal Agent Gateway" (UAG)
+# The Form.io Universal Agent Gateway (UAG)
 The Universal Agent Gateway (UAG) introduces the power of [Form.io](https://form.io) forms to AI agents.  
 
 The Form.io UAG uses the [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/docs/getting-started/intro) to enable Form.io interaction through an AI agent workflow. By providing AI agents with the **dynamic context** of how to use Form.io JSON forms,  the UAG allows a user to interact with any aspect of their enterprise system served by the Form.io Platform directly through their AI agent.
@@ -7,7 +7,7 @@ The Form.io UAG uses the [**Model Context Protocol (MCP)**](https://modelcontext
 
 ## Table of Contents
 
-- [The Form.io "Universal Agent Gateway" (UAG)](#the-formio-universal-agent-gateway-uag)
+- [The Form.io Universal Agent Gateway (UAG)](#the-formio-universal-agent-gateway-uag)
   - [Introduction](#introduction)  
     - [The Model Context Protocol (MCP)](#the-model-context-protocol-mcp)  
     - [Dynamic Context](#dynamic-context)  
@@ -27,7 +27,7 @@ The Form.io UAG uses the [**Model Context Protocol (MCP)**](https://modelcontext
 ---
 
 ## Introduction
-The core purpose of the UAG is to equip AI agents with the ability to fluidly apply a user's natural language instructions to the Form.io platform's capabilities as defined by selected forms and fields.
+The core purpose of the UAG is to equip AI agents with the ability to forward a user's inputs to the Form.io platform. It allows the AI agent to apply natural language requests, scanned documents, and any other input it can parse into Form.io functionality, as defined by selected forms and fields.
 
   ### The Model Context Protocol (MCP)
   The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems.  
@@ -37,7 +37,7 @@ The core purpose of the UAG is to equip AI agents with the ability to fluidly ap
   ### Dynamic Context
   What does it mean to say MCP provides a dynamic context for how to use these tools?
 
-  The power of AI agents is their ability to parse natural language and infer a user's intent rather than  take rote input like a command line. The dynamic context delivered by MCP gives the AI agent guidance on how to correlate the user's prompt to the tools and data available. When the AI agent receives a prompt, it uses this dynamic context to determine what tool it should use, what elements of the prompt are inputs to that tool, and what additional input might be necessary.
+  The power of AI agents is their ability to parse free-form inputs, like natural language, and infer a user's intent rather than  take rote input like a command line. The dynamic context delivered by MCP gives the AI agent guidance on how to correlate the user's prompt to the tools and data available within Form.io. When the AI agent receives a prompt, it uses this dynamic context to determine what tool it should use, what elements of the prompt are inputs to that tool, and what additional input might be necessary. 
 
   ### The Role of the UAG
   The UAG is the package that contains everything sitting between the Form.io Platform and the AI agent.
@@ -47,9 +47,11 @@ The core purpose of the UAG is to equip AI agents with the ability to fluidly ap
   Form.io's drag-and-drop Form Builder simultaneously defines the look of the form and the structure of the data. This makes it easy to use data collected through Form.io forms elsewhere in an application or as an input to other enterprise systems.  
   ![](./examples/images/form-interfaces.png)
  
-  When the UAG is able to map the natural language inputs that an AI agent receives to the data model defined by a form, it means that data can be quickly supplied to the enterprise tools that depend on the Form.io platform without additional interpretation or transformation.  
+  When the UAG is able to map the freeform inputs that an AI agent receives to the data model defined by a form, it means that data can be quickly supplied to the enterprise tools that depend on the Form.io platform without additional interpretation or transformation.  
   This allows the UAG and Form.io to serve as a reliable middleware between an AI agent and countless other systems.
 
+ The same role-based access control that governs all Form.io forms and submissions still applies to any interaction through the UAG. This addresses many potential issues some users may have with connecting AI agents to enterprise systems.
+
   Here is a visual graphic of the layers provided by the UAG to achieve a trusted and deterministic interface between AI Agents to external systems through the UAG + Form.io Server.
 
   ![](./examples/images/agents_to_formio.png)
@@ -79,8 +81,8 @@ The following tools provided by the UAG can be described as follows:
 | get_form_fields | When the AI agent infers the user intends to use a specific form, this tool provides the agent with a high level overview of all the fields needed (along with the field data path) to submit that form. |
 | get_field_info | Once the fields have been determined using `get_form_fields`, this tool provides specific information about the requested fields, such as validation, conditionals, input formats, etc. <br/>This tool instructs the AI agent on how to format and structure the data that is sent to the MCP server. |
 | collect_field_data  | Provides the AI agent with a mechanism to dynamically collect the required information from the user. It can parse the user's input into multiple fields at once, and will identify additional inputs from the user if needed. <br/>This tool supports complex and structured data collection and is compatible with nested or multi-value fields like nested forms, data grids, etc.       |
-| confirm_form_submission     | When the AI agent is ready to submit a form, this tool allows it to confirm all the information it has collected before a submission has been made to the form. |
-| submit_completed_form    | Provides the AI agent with the ability to submit all of the data collected from the user to create the form submission. |
+| confirm_form_submission | This tool is used to provide a summary of all data collected before a submission is made to the form. |
+| submit_completed_form | Provides the AI agent with the ability to submit all of the data collected from the user to create the form submission. |
 | 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. | 
 
@@ -277,11 +279,10 @@ This module can be configured in many ways. One of those ways is through the use
 | DEBUG | Variable used to perform debug logs of server activity | formio.* |
 | PORTAL_SECRET | Enterprise Only:  Allows you to connect to the UAG from the Form.io Enterprise Portal. | CHANGEME |
 | JWT_SECRET | A secret used to generate and validate JWT tokens generated through the authentication process of the UAG. This does not need to match the JWT_SECRET of the Enterprise Server that it is connected to. | CHANGEME |
-| PORTAL_SECRET | (Enterprise Only) Used to connect the UAG server with the Enterprise Portal | CHANGEME |
 | JWT_EXPIRE_TIME | The expiration for the jwt secret. | 3600 |
 | MONGO | (Enterprise Only) Allows you to connect the UAG directly to a mongo database, rather than having to redirect the submissions to the Form.io Submission APIs. | |
 | MONGO_CONFIG | JSON configuration for the Node.js Mongo Driver. | |
-| BASE_URL | The public URL that the UAG is hosted on. This allows for proper OIDC authentication and allows for the authentication callbacks to point to the correct url. | https://ai.onform.io |
+| BASE_URL | The public URL that the UAG is hosted on. This allows for proper OIDC authentication and allows for the authentication callbacks to point to the correct url. | https://forms.yoursite.com |
 | LOGIN_FORM | The public URL to the Login Form JSON endpoint. | https://mysite.com/project/user/login |
 | CORS | The cors domain, or the JSON configuration to configure the "cors" node.js module cross domain resource sharing. | *.* |
 

package/lib/UAGFormInterface.d.ts

@@ -76,6 +76,13 @@ export declare class UAGFormInterface extends FormInterface {
      * @returns { boolean } - True if the component is an input component, false otherwise.
      */
     inputComponent(component: Component): boolean;
+    getEmptyValue(component: Component): {}[] | {
+        data: {};
+    }[] | {
+        data: {};
+    } | {
+        data?: undefined;
+    } | null;
     /**
      * 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

@@ -223,6 +223,22 @@ class UAGFormInterface extends appserver_1.FormInterface {
         }
         return true;
     }
+    getEmptyValue(component) {
+        const modelType = core_1.Utils.getModelType(component);
+        switch (modelType) {
+            case 'nestedArray':
+                return [{}];
+            case 'nestedDataArray':
+                return [{ data: {} }];
+            case 'dataObject':
+                return { data: {} };
+            case 'object':
+            case 'map':
+                return {};
+            default:
+                return null;
+        }
+    }
     /**
      * 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
@@ -255,8 +271,16 @@ class UAGFormInterface extends appserver_1.FormInterface {
                 name: 'getFields',
                 shouldProcess: () => true,
                 process: async (context) => {
-                    const { component, path, value } = context;
+                    const { component, path, value, data } = context;
                     if (this.isNestedComponent(component)) {
+                        // For nested components, we need to always have a value so that the child components
+                        // are added to the list of fields needing data.
+                        if (core_1.Utils.isComponentDataEmpty(component, data, path)) {
+                            const emptyValue = this.getEmptyValue(component);
+                            if (emptyValue !== null) {
+                                (0, lodash_1.set)(data, path, emptyValue);
+                            }
+                        }
                         nestedPaths.push(path);
                     }
                 },
@@ -301,8 +325,10 @@ class UAGFormInterface extends appserver_1.FormInterface {
                     if (component.validate?.required) {
                         fieldInfo.totalRequired++;
                     }
-                    // If the component hass a value, then skip it.
-                    if ((0, core_1.componentHasValue)(component, value)) {
+                    // If the value is not empty, then we can skip this field.
+                    const emptyValue = this.getEmptyValue(component);
+                    const hasValue = emptyValue === null ? (0, core_1.componentHasValue)(component, value) : !(0, lodash_1.isEqual)(value, emptyValue);
+                    if (hasValue) {
                         if (component.validate?.required) {
                             fieldInfo.totalRequiredCollected++;
                         }

package/lib/templates/allFieldsCollected.md

@@ -9,7 +9,8 @@
 4. If they do not wish to "Add Another", then use the `get_form_fields` tool to determine if there are any more fields that need to be collected outside of the **<%= parent.label %>** component. If so, use the `collect_field_data` tool to collect that information (make sure to change the `parent_path` parameter to the level above the **<%= parent.label %>** field, or leave empty if we are at the root of the form).
 <% } else if (parent && (parent.isForm || parent.isContainer)) { %>
 1. Use the `get_form_fields` tool with `parent_path`="<%= parent.data_path %>" and `criteria`="optional" to check if there are any optional fields. If so, ask the user if they wish to fill any of them out.
-2. If there are no optional fields, or the user declines, then use the `get_form_fields` tool to determine if there are any more fields that need to be collected outside of the <%= parent.label %> component. If so, use the `collect_field_data` tool to collect that information (make sure to change the parent parameter to the level above the <%= parent.label %> field, or leave empty if we are at the root of the form).
+2. If there are no optional fields, or the user does not wish to add any more values to the <%= parent.label %> component, then use the `get_form_fields` tool to determine if there are any more fields that need to be collected outside of the <%= parent.label %> component. If so, use the `collect_field_data` tool to collect that information (make sure to change the parent parameter to the level above the <%= parent.label %> field, or leave empty if we are at the root of the form).
 <% } else { %>
 1. Use the `get_form_fields` tool with `criteria`="optional" to check if there are optional fields. If so, ask the user if they wish to fill any of them out.
-2. If there are no optional fields, or the user declines, then use the `confirm_form_submission` tool to show summary and get confirmation to submit the form.<% } %>
+2. If there are no optional fields then use the `submit_completed_form` tool to submit the data. If necessary, use the `confirm_form_submission` tool to provide them a summary of the collected values before submission.
+3. If there are optional fields, but the user does not want to add anything else, use the `submit_completed_form` tool to submit the data. If necessary, use the `confirm_form_submission` tool to provide them a summary of the collected values.<% } %>

package/lib/templates/getFormFieldsEmpty.md

@@ -6,9 +6,9 @@ No fields were found matching `criteria`="<%= criteria %>" for <%= parentLabel %
 <% } else if (parent) { %>
  - Considering the search was made using a `parent_path` context, try the search again at a higher `parent_path` context.
 <% } else if (criteria === "optional") { %>
- - Since there are no more "optional" fields, use the `confirm_form_submission` tool to ensure all the collected information is correct.
+ - Since there are no more "optional" fields, use the `submit_completed_form` tool to submit all the information if the user confirms they wish to do so, if necessary use the `confirm_form_submission` tool to ensure all the collected information is correct.
 <% } else if (criteria === "required") { %>
  - Use the `get_form_fields` tool, with `criteria`="optional" to determine if there are any optional fields they wish to provide information for.
 <% } else { %>
- - Use the `confirm_form_submission` tool to ensure all the collected information is correct.
+ - Use the `submit_completed_form` tool to submit all the information if the user confirms they wish to do so, if necessary use the `confirm_form_submission` tool to ensure all the collected information is correct.
 <% } %>

package/lib/tools/confirmSubmission.js

@@ -8,7 +8,7 @@ const confirmSubmission = async (project) => {
     return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.confirm_form_submission || {}, {
         name: 'confirm_form_submission',
         title: 'Confirm Form Submission',
-        description: 'Show a summary of the collected form data and ask the user for confirmation before submitting',
+        description: 'Show a summary of the collected form data if the user wishes to see a summary of the collected data',
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .form_data().schema,

package/lib/tools/submitForm.js

@@ -9,7 +9,7 @@ const submitCompletedForm = async (project) => {
     return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.submit_completed_form || {}, {
         name: 'submit_completed_form',
         title: 'Submit Completed Form',
-        description: 'Submit the completed form data to Form.io API ONLY after the user has explicitly confirmed submission (said "yes", "confirm", etc.)',
+        description: 'Submit the completed form data. Should only be used once all the required fields have been collected, and the user has explicitly confirmed submission (e.g. has said "submit", "send", "done", etc)',
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .form_data().schema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "clean": "rm -rf lib",
-    "build:ts": "tsc",
+    "build:ts": "npx tsc",
     "build:copy-templates": "mkdir -p lib/templates && cp src/templates/*.md lib/templates/",
     "build": "npm run clean && npm run build:ts && npm run build:copy-templates",
     "build:docker": "npm run build && docker build -t formio/uag --platform=linux/amd64 .",
@@ -23,26 +23,26 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@formio/appserver": "^2.5.0",
+    "@formio/appserver": "^2.8.0",
     "@formio/core": "2.5.1-dev.291.6557e4e",
-    "@modelcontextprotocol/sdk": "^1.22.0",
+    "@modelcontextprotocol/sdk": "^1.23.0",
     "cors": "^2.8.5",
     "debug": "^4.4.1",
     "dotenv": "^17.2.1",
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "jsonwebtoken": "^9.0.2",
     "lodash": "^4.17.21",
     "node-cache": "^5.1.2",
-    "zod": "^3.25.76"
+    "zod": "^4.1.13"
   },
   "devDependencies": {
     "@types/chai": "^5.2.3",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
     "@types/dotenv": "^8.2.3",
-    "@types/express": "^5.0.5",
+    "@types/express": "^5.0.6",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/lodash": "^4.17.20",
+    "@types/lodash": "^4.17.21",
     "@types/mocha": "^10.0.10",
     "@types/node": "^24.10.1",
     "@types/supertest": "^6.0.3",
@@ -51,7 +51,7 @@
     "supertest": "^7.1.4",
     "terser": "^5.44.1",
     "ts-node": "^10.9.2",
-    "tsx": "^4.20.4",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }
 }