@formio/uag 1.12.3 → 1.13.0

package/README.md

@@ -2,6 +2,13 @@
   <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)
@@ -163,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
@@ -402,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. | |
@@ -410,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

@@ -26,6 +26,10 @@ class UAGServer extends appserver_1.Server {
         super((0, lodash_1.defaultsDeep)(config || {}, {
             baseUrl: (0, lodash_1.get)(process.env, 'BASE_URL', '').toString(),
             license: (0, lodash_1.get)(process.env, 'UAG_LICENSE', '').toString(),
+            // A project that is still starting up (a Form.io server in the same compose
+            // file, for example) is retried with backoff before the load is given up on.
+            retries: parseInt((0, lodash_1.get)(process.env, 'PROJECT_RETRIES', 5).toString(), 10),
+            retryDelay: parseInt((0, lodash_1.get)(process.env, 'PROJECT_RETRY_DELAY', 5000).toString(), 10),
             submissionProxy: true,
             processAsClient: true,
             auth: { pkce: true }
@@ -38,6 +42,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,6 +1,6 @@
 {
   "name": "@formio/uag",
-  "version": "1.12.3",
+  "version": "1.13.0",
   "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.13.2",
+    "@formio/appserver": "^2.14.0",
     "@formio/core": "2.8.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "cors": "^2.8.6",