@formio/uag 1.12.1 → 1.12.3

package/README.md

@@ -6,24 +6,20 @@ The Universal Agent Gateway (UAG) leverages the [Model Context Protocol (MCP)](h
 
 ![Diagram showing how the UAG provides an AI Agent the ability to read and understand a Form.io Form JSON. Similar to how the JavaScript renderer provides a Human the ability to visually see a rendered form.](./examples/images/uag-agent-rendering.png)
 
-Official Documentation
---------------------------
-For the latest documentation, release information, and guides, always refer to the official Form.io Help Documentation available here:
-
-**[https://help.form.io](https://help.form.io/dev/ai/uag)**
-
 --------------------------
 There are two primary scenarios that the UAG enables:
 
  - **Unstructured 'chat' input to deterministic form submission**:  This capability uses the JSON schema of a Form.io form to produce a deterministic structured data object provided natural language conversational input. 
 
  ![Conversion of natural language to structured data using UAG.](./examples/images/uag-natural-language.png)
+ 
+For a working example of this flow, please try out the [Conversation Form Example](./examples/conversation-form).
 
  - **Agentic Form.io Workflows**: UAG provides an AI Agent the ability to take existing submission data + "context" criteria in order to prompt an AI Agent to provide its own data and analysis within a workflow scenario. The following example, which shows a college application process using a Form.io application form, shows how this primary scenario works.
 
   ![Agentic workflow automation example diagram using UAG](./examples/images/uag-agent-provide-data.png)
 
-  For more information on Agentic workflows, checkout the dedicated [Agentic Workflows](#agentic-workflows) section
+For more information on Agentic workflows, checkout the dedicated [Agentic Workflows](#agentic-workflows) section. For a working example of this flow, please try out the [Agentic Workflow Example](./examples/agentic-workflow).
 
 ---
 
@@ -36,12 +32,10 @@ There are three working examples in this repo, each spinning up a Form.io server
 |---------|---------|-----------|
 | **[Custom Module](examples/custom-module)** | **Conversational, existing client.** Connect Claude Desktop to your forms and talk to them: "I would like to add a new customer." Built as a custom module, so roles and permissions decide what the agent may do. | Open Source — free |
 | **[Conversation Form](examples/conversation-form)** | **Conversational, your own UI.** A chat application whose questions come entirely from a form. About 200 lines, no field names in the code — edit the form and the conversation changes. | Open Source — free |
-| **[Agentic Workflow](examples/agentic-workflow)** | **Autonomous.** A submission triggers an agent that scores it against a rubric and writes its decision back, which in turn triggers a second agent. No human, no chat window. | Enterprise — the trigger needs a Webhook action that can set headers and transform its payload |
+| **[Agentic Workflow](examples/agentic-workflow)** | **Autonomous.** A submission triggers an agent that scores it against a rubric and writes its decision back, which in turn triggers a second agent. No human, no chat window. | Enterprise |
 
 There is also a [Flow Viewer](examples/flow-viewer) — a small proxy that shows every leg of an agentic run live, which is the fastest way to see what an agent is actually doing.
 
-**[Conversation »](examples/conversation-form)**  |  **[Claude Desktop »](examples/custom-module)**  |  **[Autonomous »](examples/agentic-workflow)**
-
 ## Documentation in this repository
 
 This file is the main reference: what the UAG is, how to configure a form for it, how to deploy it, and how to troubleshoot it. The rest of the documentation lives next to the code it describes.

package/lib/tools/fetchExternalData.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchExternalData = void 0;
 const template_1 = require("../template");
+const utils_1 = require("./utils");
 const core_1 = require("@formio/core");
 const SchemaBuilder_1 = require("./SchemaBuilder");
 const lodash_1 = require("lodash");
@@ -251,7 +252,7 @@ async function fetchResourceData(component, search_value, authInfo, project, con
     const query = {};
     // Add search filter if provided
     if (search_value && component.searchField) {
-        query[`data.${component.searchField}__regex`] = `/${search_value}/i`;
+        query[`data.${component.searchField}__regex`] = `/${(0, utils_1.escapeSearchPattern)(search_value)}/i`;
     }
     // Add component filter if configured (interpolate the filter string)
     if (component.filter) {

package/lib/tools/findSubmission.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findSubmission = void 0;
 const template_1 = require("../template");
+const utils_1 = require("./utils");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
 const error = require('debug')('formio:uag:findSubmission:error');
@@ -34,19 +35,33 @@ const findSubmission = async (project) => {
                         }, true);
                     }
                     if (criterion.operator === 'regex') {
+                        // The value is a pattern by request here, so it is passed through
+                        // unescaped. It is still compiled first: the server drops a filter
+                        // it cannot compile, which would widen the search instead of
+                        // failing it, so a bad pattern is better reported back.
+                        try {
+                            new RegExp(criterion.search_value);
+                        }
+                        catch (err) {
+                            return project.mcpResponse(template_1.ResponseTemplate.submissionSearchError, {
+                                form: form.form,
+                                searchQuery: search_query,
+                                error: `"${criterion.search_value}" is not a valid regular expression for "${criterion.data_path}". Use the "contains" operator to search for it literally.`
+                            }, true);
+                        }
                         query[`data.${criterion.data_path}__regex`] = `/${criterion.search_value}/i`;
                     }
                     else if (criterion.operator === 'equals') {
                         query[`data.${criterion.data_path}`] = criterion.search_value;
                     }
                     else if (criterion.operator === 'contains') {
-                        query[`data.${criterion.data_path}__regex`] = `/${criterion.search_value}/i`;
+                        query[`data.${criterion.data_path}__regex`] = `/${(0, utils_1.escapeSearchPattern)(criterion.search_value)}/i`;
                     }
                     else if (criterion.operator === 'starts_with') {
-                        query[`data.${criterion.data_path}__regex`] = `/^${criterion.search_value}/i`;
+                        query[`data.${criterion.data_path}__regex`] = `/^${(0, utils_1.escapeSearchPattern)(criterion.search_value)}/i`;
                     }
                     else if (criterion.operator === 'ends_with') {
-                        query[`data.${criterion.data_path}__regex`] = `/${criterion.search_value}$/i`;
+                        query[`data.${criterion.data_path}__regex`] = `/${(0, utils_1.escapeSearchPattern)(criterion.search_value)}$/i`;
                     }
                     else if (criterion.operator === 'greater_than') {
                         query[`data.${criterion.data_path}__gt`] = criterion.search_value;

package/lib/tools/utils.d.ts

@@ -1,4 +1,24 @@
 import { ZodRawShape } from "zod";
+/**
+ * Escape a literal value so it can be carried in a `__regex` query parameter.
+ *
+ * Operators like "contains" promise a literal match, so every regular expression
+ * metacharacter in the value has to be neutered first. Left raw, a search for
+ * "joe.thompson@example.com" becomes a pattern whose dots match any character,
+ * and a value such as "[" is not a valid pattern at all — the server compiles
+ * these with a try/catch and silently drops the filter when compilation fails,
+ * which turns a narrow search into one that matches everything.
+ *
+ * Forward slashes get a further step. The server reads the parameter as
+ * `/pattern/flags` and takes the pattern with `[^/]+`, so an embedded slash
+ * truncates the pattern and the remainder is parsed as flags — again dropping
+ * the filter. Writing it as the equivalent `\x2f` escape keeps the character
+ * out of the transport while still matching a literal slash.
+ *
+ * @param value - The literal text to search for.
+ * @returns The value as a regular expression pattern that matches it literally.
+ */
+export declare const escapeSearchPattern: (value: string) => string;
 export type ToolInfo = {
     name?: string;
     title?: string;

package/lib/tools/utils.js

@@ -1,2 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeSearchPattern = void 0;
+const lodash_1 = require("lodash");
+/**
+ * Escape a literal value so it can be carried in a `__regex` query parameter.
+ *
+ * Operators like "contains" promise a literal match, so every regular expression
+ * metacharacter in the value has to be neutered first. Left raw, a search for
+ * "joe.thompson@example.com" becomes a pattern whose dots match any character,
+ * and a value such as "[" is not a valid pattern at all — the server compiles
+ * these with a try/catch and silently drops the filter when compilation fails,
+ * which turns a narrow search into one that matches everything.
+ *
+ * Forward slashes get a further step. The server reads the parameter as
+ * `/pattern/flags` and takes the pattern with `[^/]+`, so an embedded slash
+ * truncates the pattern and the remainder is parsed as flags — again dropping
+ * the filter. Writing it as the equivalent `\x2f` escape keeps the character
+ * out of the transport while still matching a literal slash.
+ *
+ * @param value - The literal text to search for.
+ * @returns The value as a regular expression pattern that matches it literally.
+ */
+const escapeSearchPattern = (value) => (0, lodash_1.escapeRegExp)(value).replace(/\//g, '\\x2f');
+exports.escapeSearchPattern = escapeSearchPattern;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formio/uag",
-  "version": "1.12.1",
-  "mcpName": "io.form/uag",
+  "version": "1.12.3",
+  "mcpName": "io.form/formio-uag",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -30,7 +30,7 @@
   "author": "Form.io Developers",
   "license": "MIT",
   "dependencies": {
-    "@formio/appserver": "^2.13.1",
+    "@formio/appserver": "^2.13.2",
     "@formio/core": "2.8.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "cors": "^2.8.6",
@@ -70,5 +70,13 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2"
   },
-  "packageManager": "yarn@4.17.1"
+  "packageManager": "yarn@4.17.1",
+  "dependenciesMeta": {
+    "esbuild": {
+      "built": true
+    },
+    "isolated-vm": {
+      "built": true
+    }
+  }
 }