@formio/uag 1.12.2 → 1.12.4

package/README.md

@@ -2,28 +2,31 @@
   <img src="./examples/images/logo-formio-uag.png" alt="The Form.io Universal Agent Gateway (UAG)" width="40%">
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@formio/uag"><img src="https://img.shields.io/npm/v/%40formio%2Fuag?label=%40formio%2Fuag" alt="npm: @formio/uag"></a>
+  <a href="https://hub.docker.com/r/formio/uag"><img src="https://img.shields.io/docker/v/formio/uag?label=docker&sort=semver" alt="Docker: formio/uag"></a>
+  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.form/formio-uag"><img src="https://img.shields.io/badge/MCP%20Registry-io.form%2Fformio--uag-blue" alt="MCP Registry: io.form/formio-uag"></a>
+  <a href="./LICENSE.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
 The Universal Agent Gateway (UAG) leverages the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) to enable in-process agentic automation using Form.io. It provides to an AI Agent the same thing that our [JavaScript Renderer](https://github.com/formio/formio.js) provides to a human; an interpretation of the Form JSON schema into an understandable format. In the case of UAG, it transforms the Form JSON model into an AI readible markdown format so that the Agent can easily understand the purpose and structure of the data that needs to be collected.
 
 ![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 +39,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 &raquo;](examples/conversation-form)** &nbsp;|&nbsp; **[Claude Desktop &raquo;](examples/custom-module)** &nbsp;|&nbsp; **[Autonomous &raquo;](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.
@@ -169,6 +170,26 @@ These integrations can be found within the **integrations** folder. The followin
 
 Please click on one of these integration links to read how they work.
 
+### Integration Version Compatibility
+
+Integrations are **versioned independently of the UAG**. They share no code with it — each one runs its own MCP client and talks to the UAG over MCP/HTTP — so an integration release does not imply a UAG release, and vice versa. Matching version numbers between the two would be misleading rather than helpful.
+
+Use this matrix to pick a compatible pair. Each row records the UAG range an integration version is known to work against:
+
+| Integration | Version | Compatible UAG versions | Notes |
+| ----------- | ------- | ----------------------- | ----- |
+| `@formio/uag-claude` | 1.3.x | >= 1.12.0 | Current. |
+| `@formio/uag-claude` | 1.2.x | 1.10.0 – 1.11.x | |
+
+Both artifacts are published on every release where their own version changed:
+
+- npm: [`@formio/uag`](https://www.npmjs.com/package/@formio/uag), [`@formio/uag-claude`](https://www.npmjs.com/package/@formio/uag-claude)
+- Docker Hub: [`formio/uag`](https://hub.docker.com/r/formio/uag), [`formio/uag-claude`](https://hub.docker.com/r/formio/uag-claude)
+
+**When adding a row:** bump the integration's own `package.json` version. CI publishes it to npm and Docker Hub on the next release tag, and skips it automatically when that version is already published — so a core-only release does not rebuild an unchanged integration.
+
+The `examples/` compose files reference `formio/uag` and `formio/uag-claude` without a tag, so they always pull the current release and cannot drift out of date. If you need a reproducible stack, pin both images to a compatible pair from the matrix above.
+
 ---
 
 ## Technical Overview
@@ -408,7 +429,7 @@ This module can be configured in many ways. One of those ways is through the use
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| PROJECT | The API Endpoint to either an Enterprise project endpoint, or the OSS server url. | http://localhost:3000 |
+| PROJECT | **Required.** The API Endpoint to either an Enterprise project endpoint, or the OSS server url. | http://localhost:3000 |
 | PROJECT_KEY | (Enterprise Only) The API Key of the project this UAG is bound to, found in **Project Settings &rarr; API Keys**. Open Source deployments use `ADMIN_KEY` instead. | CHANGEME |
 | ADMIN_KEY | (Open Source Only) Allows you to provide the ADMIN_KEY to install and connect to the OSS Server. | CHANGEME |
 | UAG_LICENSE | The license to run the UAG against a Form.io Enterprise Deployment. | |
@@ -416,7 +437,7 @@ This module can be configured in many ways. One of those ways is through the use
 | PORT | The port you wish to run the server on. | 3200 |
 | 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 |
+| JWT_SECRET | **Required.** 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 |
 | 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. | |

package/lib/index.js

@@ -38,6 +38,16 @@ class UAGServer extends appserver_1.Server {
     async router() {
         const router = await super.router();
         const uagProject = Object.values(this.projectRouter?.projects || {})[0];
+        // Without a project there are no forms to expose, so there is nothing to
+        // serve. Say why: this used to throw "Cannot read properties of undefined
+        // (reading 'uagRouter')", which told the operator nothing about the
+        // misconfiguration that caused it.
+        if (!uagProject) {
+            throw new Error('No Form.io project could be loaded, so the UAG has nothing to serve. Check that PROJECT ' +
+                'points at a reachable Form.io deployment, and that it is paired with the right ' +
+                'credential — ADMIN_KEY for an Open Source server, or PROJECT_KEY plus UAG_LICENSE for ' +
+                'an Enterprise project. Earlier log lines report why the project load failed.');
+        }
         router.use(uagProject.uagRouter());
         return router;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formio/uag",
-  "version": "1.12.2",
-  "mcpName": "io.form/uag",
+  "version": "1.12.4",
+  "mcpName": "io.form/formio-uag",
   "description": "The Form.io Universal Agent Gateway (UAG).",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -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
+    }
+  }
 }