@formio/uag 1.13.0 → 1.13.2

package/lib/UAGProjectInterface.js

@@ -38,7 +38,11 @@ class UAGProjectInterface extends appserver_1.ProjectInterface {
                 server.registerTool(tool.name, {
                     title: tool.title,
                     description: tool.description,
-                    inputSchema: tool.inputSchema
+                    inputSchema: tool.inputSchema,
+                    // Carries readOnly/destructive/idempotent/openWorld through to the
+                    // client. Tools from config.tools may omit them, so this stays
+                    // conditional rather than sending `annotations: undefined`.
+                    ...(tool.annotations && { annotations: tool.annotations })
                 }, tool.execute);
             }
         }

package/lib/tools/agentProvideData.js

@@ -4,11 +4,13 @@ exports.agentProvideData = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 const agentProvideData = async (project) => {
     return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.agent_provide_data || {}, {
         name: 'agent_provide_data',
         title: 'Agent Provide Data',
         description: 'Provides a mechanism for agents to process existing submission data, understand it, and then to provide additional data values provided a criteria and form context.',
+        annotations: (0, annotations_1.reads)('Process submission data'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .submission_id()

package/lib/tools/annotations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP tool annotations, as presets rather than per-tool literals.
+ *
+ * Annotations are how a client knows whether a call is safe to make speculatively,
+ * safe to retry, and whether it can change data — the difference between an agent
+ * that asks before overwriting someone's submission and one that just does it.
+ * Spelling the four hints out in ten tool files would guarantee drift, so each tool
+ * picks the preset matching its verb and supplies only a human-readable title.
+ *
+ * `openWorldHint` is true throughout: every tool here resolves forms or submissions
+ * against a Form.io deployment, so results depend on a system outside this process.
+ */
+export interface ToolAnnotations {
+    title: string;
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/**
+ * Reads, or shapes data in the response without persisting it. Repeatable, and
+ * nothing on the server changes — which covers the conversational tools too:
+ * `collect_field_data` and `confirm_form_submission` validate and echo back the
+ * caller's `form_data`, they do not save it.
+ */
+export declare function reads(title: string): ToolAnnotations;
+/** Creates a record. Calling it twice creates two, so not idempotent. */
+export declare function creates(title: string): ToolAnnotations;
+/**
+ * Overwrites an existing record. Destructive because the previous values are gone
+ * once it returns; idempotent because applying the same updates again lands the
+ * same result.
+ */
+export declare function overwrites(title: string): ToolAnnotations;

package/lib/tools/annotations.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * MCP tool annotations, as presets rather than per-tool literals.
+ *
+ * Annotations are how a client knows whether a call is safe to make speculatively,
+ * safe to retry, and whether it can change data — the difference between an agent
+ * that asks before overwriting someone's submission and one that just does it.
+ * Spelling the four hints out in ten tool files would guarantee drift, so each tool
+ * picks the preset matching its verb and supplies only a human-readable title.
+ *
+ * `openWorldHint` is true throughout: every tool here resolves forms or submissions
+ * against a Form.io deployment, so results depend on a system outside this process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reads = reads;
+exports.creates = creates;
+exports.overwrites = overwrites;
+/**
+ * Reads, or shapes data in the response without persisting it. Repeatable, and
+ * nothing on the server changes — which covers the conversational tools too:
+ * `collect_field_data` and `confirm_form_submission` validate and echo back the
+ * caller's `form_data`, they do not save it.
+ */
+function reads(title) {
+    return {
+        title,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    };
+}
+/** Creates a record. Calling it twice creates two, so not idempotent. */
+function creates(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    };
+}
+/**
+ * Overwrites an existing record. Destructive because the previous values are gone
+ * once it returns; idempotent because applying the same updates again lands the
+ * same result.
+ */
+function overwrites(title) {
+    return {
+        title,
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    };
+}

package/lib/tools/collectData.js

@@ -4,11 +4,13 @@ exports.collectData = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 const collectData = async (project) => {
     return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.collect_field_data || {}, {
         name: 'collect_field_data',
         title: 'Collect Field Data',
         description: 'Collect data for a form, or a specific field with nested components. Identify the component by its path, validate the provided value, and update the form_data object. After updating, determine the next required field to collect or indicate if all required fields are complete. PREREQUISITE: This tool should only be called after the `get_form_fields` tool AND subsequentially the `get_field_info` tool have been called to understand the structure and validation rules of the fields.',
+        annotations: (0, annotations_1.reads)('Collect field data'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .form_data()

package/lib/tools/confirmSubmission.js

@@ -4,11 +4,13 @@ exports.confirmSubmission = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 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 if the user wishes to see a summary of the collected data',
+        annotations: (0, annotations_1.reads)('Summarise before submitting'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .form_data().schema,

package/lib/tools/fetchExternalData.js

@@ -6,6 +6,7 @@ const utils_1 = require("./utils");
 const core_1 = require("@formio/core");
 const SchemaBuilder_1 = require("./SchemaBuilder");
 const lodash_1 = require("lodash");
+const annotations_1 = require("./annotations");
 const error = require('debug')('formio:uag:fetchExternalData:error');
 /**
  * Strip HTML tags from a string.
@@ -74,6 +75,7 @@ const fetchExternalData = async (project) => {
         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.',
+        annotations: (0, annotations_1.reads)('Fetch external field data'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .data_path()

package/lib/tools/findSubmission.js

@@ -5,12 +5,14 @@ const template_1 = require("../template");
 const utils_1 = require("./utils");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 const error = require('debug')('formio:uag:findSubmission:error');
 const findSubmission = async (project) => {
     return (0, lodash_1.defaultsDeep)(project.config?.toolOverrides?.find_submissions || {}, {
         name: 'find_submissions',
         title: 'Find submissions within a form',
         description: 'Find existing form submissions based on field values (search query). Use this to search for people, records, or data by name, email, phone, position, company, or other field values. Examples: find a contact by name, find someone who works at a company, find records with specific criteria. To retrieve the total count of records within a form, use this tool without providing a `search_query`.',
+        annotations: (0, annotations_1.reads)('Find submissions'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .search_query()

package/lib/tools/getFieldInfo.js

@@ -4,12 +4,14 @@ exports.getFieldInfo = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 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.',
+        annotations: (0, annotations_1.reads)('Get field details'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .field_paths()

package/lib/tools/getFormFields.js

@@ -4,12 +4,14 @@ exports.getFormFields = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 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.',
+        annotations: (0, annotations_1.reads)('Get form fields'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .criteria()

package/lib/tools/getForms.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getForms = void 0;
 const lodash_1 = require("lodash");
 const template_1 = require("../template");
+const annotations_1 = require("./annotations");
 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.',
+        annotations: (0, annotations_1.reads)('Get available forms'),
         inputSchema: {},
         execute: async ({}, extra) => {
             const forms = Object.values(project.forms).filter(form => form.uag);

package/lib/tools/index.d.ts

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

package/lib/tools/index.js

@@ -35,6 +35,7 @@ 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);
+__exportStar(require("./annotations"), exports);
 const getTools = async (project) => {
     return [
         await (0, getForms_1.getForms)(project),

package/lib/tools/submissionUpdate.js

@@ -4,12 +4,14 @@ exports.submissionUpdate = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 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.',
+        annotations: (0, annotations_1.overwrites)('Update a submission'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .submission_id()

package/lib/tools/submitForm.js

@@ -4,12 +4,14 @@ exports.submitCompletedForm = void 0;
 const template_1 = require("../template");
 const lodash_1 = require("lodash");
 const SchemaBuilder_1 = require("./SchemaBuilder");
+const annotations_1 = require("./annotations");
 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. 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)',
+        annotations: (0, annotations_1.creates)('Submit a completed form'),
         inputSchema: (new SchemaBuilder_1.SchemaBuilder(project))
             .form_name()
             .form_data().schema,

package/lib/tools/utils.d.ts

@@ -1,4 +1,5 @@
 import { ZodRawShape } from "zod";
+import { ToolAnnotations } from "./annotations";
 /**
  * Escape a literal value so it can be carried in a `__regex` query parameter.
  *
@@ -24,6 +25,7 @@ export type ToolInfo = {
     title?: string;
     description?: string;
     inputSchema?: ZodRawShape | undefined;
+    annotations?: ToolAnnotations;
     execute?: any;
 };
 export type ParentInfo = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/uag",
-  "version": "1.13.0",
+  "version": "1.13.2",
   "mcpName": "io.form/formio-uag",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
@@ -30,7 +30,7 @@
   "author": "Form.io Developers",
   "license": "MIT",
   "dependencies": {
-    "@formio/appserver": "^2.14.0",
+    "@formio/appserver": "^2.14.1",
     "@formio/core": "2.8.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "cors": "^2.8.6",
@@ -59,15 +59,15 @@
     "@types/dotenv": "^8.2.3",
     "@types/express": "^5.0.6",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/lodash": "^4.17.24",
+    "@types/lodash": "^4.17.25",
     "@types/mocha": "^10.0.10",
     "@types/node": "^26.1.2",
     "@types/supertest": "^7.2.1",
     "chai": "^6.2.2",
-    "mocha": "^11.7.6",
+    "mocha": "^11.8.0",
     "supertest": "^7.2.2",
-    "terser": "^5.49.0",
-    "tsx": "^4.23.1",
+    "terser": "^5.49.1",
+    "tsx": "^4.23.5",
     "typescript": "^7.0.2"
   },
   "packageManager": "yarn@4.17.1",