@formio/uag 1.3.0

package/lib/tools/getFieldInfo.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFieldInfo = void 0;
+const template_1 = require("../template");
+const lodash_1 = require("lodash");
+const SchemaBuilder_1 = require("./SchemaBuilder");
+const error = require('debug')('formio:uag:getFieldInfo:error');
+const getFieldInfo = async (project) => {
+    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.get_field_info || {}, {
+        name: 'get_field_info',
+        title: 'Get Field(s) Info',
+        description: 'Get detailed information about a specific field(s) that have been provided from the user. It is used to understand the properties, validation rules, and options of the specific field(s) the user has provided values for. This purpose of this tool is to provide detailed information for any field(s) (provided using the `field_paths` parameter) to help understand the structure and requirements of a form. PREREQUISITE: This tool should be called after the `get_form_fields` tool has been called AND once the user has provided some values for the provided fields.',
+        inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
+            .form_name()
+            .field_paths().schema,
+        execute: async ({ form_name, field_paths }, extra) => {
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            try {
+                // Get the fields at the specified data path (or root if not provided).
+                const fields = await form.getFields({ data: {} }, extra.authInfo, field_paths);
+                // Show the form fields based on the criteria.
+                return project.mcpResponse(template_1.ResponseTemplate.getFormFieldsInfo, {
+                    fields: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.fields, {
+                        fields: fields.required.components.concat(fields.optional.components)
+                    }),
+                });
+            }
+            catch (err) {
+                error('Error extracting form fields:', err);
+                return project.mcpResponse(template_1.ResponseTemplate.getFormFieldsError, {
+                    form: form.form,
+                    error: err instanceof Error ? err.message : 'Unknown error'
+                }, true);
+            }
+        }
+    });
+};
+exports.getFieldInfo = getFieldInfo;

package/lib/tools/getFormFields.d.ts

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

package/lib/tools/getFormFields.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFormFields = 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:getFormFields:error');
+const getFormFields = async (project) => {
+    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.get_form_fields || {}, {
+        name: 'get_form_fields',
+        title: 'Get Form Fields',
+        description: 'Get high level overview of the fields that are present in a form, and to understand the "rules" on how the data for each field type should be collected. The purpose of this tool is to determine what fields the user is requesting (and to understand how to format that values for that data), and use that to create a list of field data_path\'s that the user is providing context for. This list can then be provided to the `get_field_info` tool to determine the specific field level information for those fields (validation, required, collection rules, etc). PREREQUISITE: You must call the `get_forms` tool first to understand what forms are available to submit and the permissions associated with those forms.',
+        inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
+            .form_name()
+            .form_data()
+            .criteria()
+            .parent().schema,
+        execute: async ({ form_name, form_data, criteria, parent }, extra) => {
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            try {
+                // Ensure the parent is null if the type or data_path is missing.
+                if (!parent?.data_path || !parent.type) {
+                    parent = undefined;
+                }
+                // Get the submission data.
+                const submission = form.convertToSubmission(form_data);
+                // Get the fields at the specified data path (or root if not provided).
+                const fields = await form.getFields(submission, extra.authInfo, parent?.data_path);
+                // If the agent requests optional fields, but there are still requird fields to fill out, then force required
+                // and inform the agent of this change.
+                let message = '';
+                if (criteria == 'optional' && fields.required.components.length > 0) {
+                    criteria = 'required';
+                    message = 'You requested "optional" fields, but the user is not finished collecting required information. Please finish collecting the following required fields first.\n\n';
+                }
+                // Determine which fields to show based on the criteria.
+                const criteriaFields = criteria === 'all' ?
+                    [...fields.required.components, ...fields.optional.components] :
+                    criteria === 'required' ? fields.required.components : fields.optional.components;
+                if (criteriaFields.length === 0) {
+                    return project.mcpResponse(template_1.ResponseTemplate.getFormFieldsEmpty, {
+                        parent,
+                        parentLabel: (0, utils_1.getParentLabel)(parent),
+                        type: (0, lodash_1.upperFirst)(criteria),
+                        form: form.form,
+                    });
+                }
+                // Determine the rules based on the criteria.
+                const criteriaRules = criteria === 'all' ?
+                    { ...fields.required.rules, ...fields.optional.rules } :
+                    criteria === 'required' ? fields.required.rules : fields.optional.rules;
+                let totalType = fields.total;
+                if (criteria === 'required') {
+                    totalType = fields.totalRequired;
+                }
+                else if (criteria === 'optional') {
+                    totalType = fields.total - fields.totalRequired;
+                }
+                const totalCollected = Object.keys(form_data || {}).length;
+                let totalTypeCollected = 0;
+                if (criteria === 'required') {
+                    totalTypeCollected = fields.totalRequiredCollected;
+                }
+                else if (criteria === 'optional') {
+                    totalTypeCollected = totalCollected - fields.totalRequiredCollected;
+                }
+                else {
+                    totalTypeCollected = totalCollected;
+                }
+                // Show the form fields based on the criteria.
+                return project.mcpResponse(template_1.ResponseTemplate.getFormFields, {
+                    message,
+                    parent,
+                    parentLabel: (0, utils_1.getParentLabel)(parent, form.form),
+                    parentDataPath: (0, utils_1.getParentDataPath)(parent, fields.rowIndex),
+                    type: (0, lodash_1.upperFirst)(criteria),
+                    rules: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.fieldRules, { rules: Object.entries(criteriaRules) }),
+                    fieldList: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.fieldList, { fields: criteriaFields }),
+                    totalFields: fields.total,
+                    totalType,
+                    totalCollected,
+                    totalTypeCollected
+                });
+            }
+            catch (err) {
+                error('Error extracting form fields:', err);
+                return project.mcpResponse(template_1.ResponseTemplate.getFormFieldsError, {
+                    form: form.form,
+                    error: err instanceof Error ? err.message : 'Unknown error'
+                }, true);
+            }
+        }
+    });
+};
+exports.getFormFields = getFormFields;

package/lib/tools/getForms.d.ts

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

package/lib/tools/getForms.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getForms = void 0;
+const lodash_1 = require("lodash");
+const template_1 = require("../template");
+const getForms = async (project) => {
+    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.get_forms || {}, {
+        name: 'get_forms',
+        title: 'Get Available Forms',
+        description: 'Get a list of all available forms with their descriptions. Use this tool when a user expresses intent to add, create, submit, fill out, register for something (e.g., "I want to add a new Contact", "I need to submit a User Registration", "I met a contact who was the CMO", "What was the email of the contact"). This tool can also be used when they ask what forms are available.',
+        inputSchema: {},
+        execute: async ({}, extra) => {
+            const forms = Object.values(project.forms).filter(form => form.uag);
+            if (forms.length === 0) {
+                return project.mcpResponse(template_1.ResponseTemplate.noFormsAvailable, {
+                    message: 'No forms are currently available in this project.'
+                });
+            }
+            // Check the forms to ensure the user can submit them.
+            return project.mcpResponse(template_1.ResponseTemplate.getAvailableForms, {
+                forms: forms.map(form => {
+                    const perms = extra.authInfo.formPermissions(form);
+                    const hasAccess = perms.create || perms.update || perms.read;
+                    const uagForm = form.uag;
+                    return {
+                        name: uagForm?.name,
+                        title: uagForm?.title,
+                        description: uagForm?.description || `Form for ${uagForm?.title} data entry`,
+                        permissions: perms,
+                        hasAccess
+                    };
+                }),
+                totalForms: forms.length
+            });
+        }
+    });
+};
+exports.getForms = getForms;

package/lib/tools/index.d.ts

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

package/lib/tools/index.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+const getForms_1 = require("./getForms");
+Object.defineProperty(exports, "getForms", { enumerable: true, get: function () { return getForms_1.getForms; } });
+const getFormFields_1 = require("./getFormFields");
+Object.defineProperty(exports, "getFormFields", { enumerable: true, get: function () { return getFormFields_1.getFormFields; } });
+const getFieldInfo_1 = require("./getFieldInfo");
+Object.defineProperty(exports, "getFieldInfo", { enumerable: true, get: function () { return getFieldInfo_1.getFieldInfo; } });
+const collectData_1 = require("./collectData");
+Object.defineProperty(exports, "collectData", { enumerable: true, get: function () { return collectData_1.collectData; } });
+const confirmSubmission_1 = require("./confirmSubmission");
+Object.defineProperty(exports, "confirmSubmission", { enumerable: true, get: function () { return confirmSubmission_1.confirmSubmission; } });
+const submitForm_1 = require("./submitForm");
+Object.defineProperty(exports, "submitCompletedForm", { enumerable: true, get: function () { return submitForm_1.submitCompletedForm; } });
+const findSubmission_1 = require("./findSubmission");
+Object.defineProperty(exports, "findSubmission", { enumerable: true, get: function () { return findSubmission_1.findSubmission; } });
+const submissionUpdate_1 = require("./submissionUpdate");
+Object.defineProperty(exports, "submissionUpdate", { enumerable: true, get: function () { return submissionUpdate_1.submissionUpdate; } });
+__exportStar(require("./utils"), exports);
+const getTools = async (project) => {
+    return [
+        await (0, getForms_1.getForms)(project),
+        await (0, getFormFields_1.getFormFields)(project),
+        await (0, getFieldInfo_1.getFieldInfo)(project),
+        await (0, collectData_1.collectData)(project),
+        await (0, confirmSubmission_1.confirmSubmission)(project),
+        await (0, submitForm_1.submitCompletedForm)(project),
+        await (0, findSubmission_1.findSubmission)(project),
+        await (0, submissionUpdate_1.submissionUpdate)(project)
+    ];
+};
+exports.getTools = getTools;

package/lib/tools/submissionUpdate.d.ts

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

package/lib/tools/submissionUpdate.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submissionUpdate = void 0;
+const template_1 = require("../template");
+const lodash_1 = require("lodash");
+const SchemaBuilder_1 = require("./SchemaBuilder");
+const error = require('debug')('formio:uag:submissionUpdate:error');
+const submissionUpdate = async (project) => {
+    return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.submission_update || {}, {
+        name: 'submission_update',
+        title: 'Submission Update',
+        description: 'Apply multiple planned field updates to a selected submission after the user confirmed they wish to update the record.',
+        inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
+            .form_name()
+            .submission_id()
+            .updates().schema,
+        execute: async ({ form_name, submission_id, updates }, extra) => {
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            try {
+                // Get the current submission
+                const currentSubmission = await form.loadSubmission(submission_id, extra.authInfo);
+                if (!currentSubmission) {
+                    return project.mcpResponse(template_1.ResponseTemplate.submissionNotFound, {
+                        form: form.form,
+                        submissionId: submission_id
+                    }, true);
+                }
+                // Apply all field updates and track changes
+                const updatedData = { ...currentSubmission.data };
+                const updateSummary = [];
+                for (const update of updates) {
+                    const previousValue = (0, lodash_1.get)(updatedData, update.data_path);
+                    (0, lodash_1.set)(updatedData, update.data_path, update.new_value);
+                    updateSummary.push({
+                        data_path: update.data_path,
+                        new_value: update.new_value,
+                        previous_value: previousValue || ''
+                    });
+                }
+                // Update the submission via API with all changes
+                const submission = await form.submit({
+                    ...currentSubmission,
+                    data: updatedData
+                }, extra.authInfo);
+                if (!submission) {
+                    return project.mcpResponse(template_1.ResponseTemplate.submissionUpdateError, {
+                        form: form.form,
+                        submissionId: submission_id,
+                        error: 'Unknown error during update'
+                    }, true);
+                }
+                // Format the updated submission for display
+                return project.mcpResponse(template_1.ResponseTemplate.submissionUpdated, {
+                    form: form.form,
+                    submissionId: submission_id,
+                    created: submission.created,
+                    modified: submission.modified,
+                    updateSummary: updateSummary,
+                    totalFieldsUpdated: updateSummary.length,
+                    dataSummary: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.collectedData, {
+                        data: form.formatData(submission.data)
+                    }),
+                });
+            }
+            catch (err) {
+                error('Error updating submission:', err);
+                return project.mcpResponse(template_1.ResponseTemplate.submissionUpdateError, {
+                    form: form.form,
+                    submissionId: submission_id,
+                    error: err instanceof Error ? err.message : 'Unknown error'
+                }, true);
+            }
+        }
+    });
+};
+exports.submissionUpdate = submissionUpdate;

package/lib/tools/submitForm.d.ts

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

package/lib/tools/submitForm.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitCompletedForm = void 0;
+const template_1 = require("../template");
+const lodash_1 = require("lodash");
+const SchemaBuilder_1 = require("./SchemaBuilder");
+const debug = require('debug')('formio:uag:submitForm');
+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.)',
+        inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
+            .form_name()
+            .form_data().schema,
+        execute: async ({ form_name, form_data }, extra) => {
+            const form = await project.getForm(form_name);
+            if (!form) {
+                return project.mcpResponse(template_1.ResponseTemplate.formNotFound, { formName: form_name }, true);
+            }
+            try {
+                let submission = form.convertToSubmission(form_data);
+                const submitted = await form.submit(submission, extra.authInfo);
+                if (submitted)
+                    submission = submitted;
+                if (!submission) {
+                    return project.mcpResponse(template_1.ResponseTemplate.submitValidationError, {
+                        validationErrors: ['Unknown error during submission']
+                    }, true);
+                }
+                debug(`Form submitted: ${form_name} with submission ID: ${submission._id}`);
+                return project.mcpResponse(template_1.ResponseTemplate.formSubmitted, {
+                    form: form.form,
+                    data: submission.data,
+                    submissionId: submission._id,
+                    submittedFieldsCount: Object.keys(form_data).length,
+                    dataSummary: project.uagTemplate?.renderTemplate(template_1.ResponseTemplate.collectedData, {
+                        data: form.formatData(submission.data)
+                    }),
+                });
+            }
+            catch (err) {
+                const 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
+                            });
+                        }
+                    }
+                }
+                return project.mcpResponse(template_1.ResponseTemplate.submitValidationError, {
+                    validationErrors: errors.length ? errors : [{ message: err.message || 'Unknown error during submission' }]
+                }, true);
+            }
+        }
+    });
+};
+exports.submitCompletedForm = submitCompletedForm;

package/lib/tools/utils.d.ts

@@ -0,0 +1,28 @@
+import { ZodRawShape } from "zod";
+import { Form } from '@formio/core';
+export type ToolInfo = {
+    name?: string;
+    title?: string;
+    description?: string;
+    inputSchema?: ZodRawShape | undefined;
+    execute?: any;
+};
+export type ParentInfo = {
+    type: string;
+    label?: string;
+    data_path?: string;
+    isForm?: boolean;
+    isTable?: boolean;
+    isContainer?: boolean;
+};
+export type DataUpdate = {
+    data_path: string;
+    new_value: any;
+};
+export type SearchQuery = {
+    data_path: string;
+    search_value: string;
+    operator: string;
+};
+export declare function getParentLabel(parent?: ParentInfo, form?: Form): string;
+export declare function getParentDataPath(parent?: ParentInfo, rowIndex?: number): string;

package/lib/tools/utils.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getParentLabel = getParentLabel;
+exports.getParentDataPath = getParentDataPath;
+function getParentLabel(parent, form) {
+    let parentLabel = form ? `the **${form.title} (${form.name})** form` : 'this form';
+    if (parent?.isTable) {
+        parentLabel = `this row within the **${parent.label}** component`;
+    }
+    else if (parent?.isForm) {
+        parentLabel = `the **${parent.label}** nested form`;
+    }
+    else if (parent?.isContainer) {
+        parentLabel = `the **${parent.label}** container component`;
+    }
+    return parentLabel;
+}
+function getParentDataPath(parent, rowIndex = -1) {
+    let parentDataPath = parent?.data_path || '';
+    if (parentDataPath && (rowIndex >= 0)) {
+        parentDataPath += `[${rowIndex}]`;
+    }
+    if (parent?.isForm) {
+        parentDataPath += '.data';
+    }
+    return parentDataPath;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@formio/uag",
+  "version": "1.3.0",
+  "description": "The Form.io Universal Agent Gateway (UAG).",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build:ts": "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:rc --platform=linux/amd64 .",
+    "test": "TS_NODE_PROJECT=tsconfig.test.json mocha --no-node-snapshot",
+    "dev": "tsx --no-node-snapshot index.js",
+    "start": "node --no-node-snapshot index.js"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@formio/appserver": "^2.3.1",
+    "@formio/core": "2.5.1-dev.291.6557e4e",
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "cors": "^2.8.5",
+    "debug": "^4.4.1",
+    "dotenv": "^17.2.1",
+    "express": "^5.1.0",
+    "jsonwebtoken": "^9.0.2",
+    "lodash": "^4.17.21",
+    "node-cache": "^5.1.2",
+    "zod": "^3.25.76"
+  },
+  "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/jsonwebtoken": "^9.0.10",
+    "@types/lodash": "^4.17.20",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.10.0",
+    "@types/supertest": "^6.0.3",
+    "chai": "^6.0.1",
+    "mocha": "^11.7.4",
+    "supertest": "^7.1.4",
+    "terser": "^5.43.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.4",
+    "typescript": "^5.9.3"
+  }
+}