@formio/mcp 0.1.0 → 0.3.0

package/dist/auth.js

@@ -37,6 +37,12 @@ function buildLoginPage(loginFormUrl) {
 <script>
 var statusEl = document.getElementById('status');
 Formio.createForm(document.getElementById('formio'), '${loginFormUrl}').then(function(form) {
+  // Suppress only Formio's default success alert (to avoid a UI flash); keep login error alerts intact.
+  const baseSetAlert = form.setAlert.bind(form);
+  form.setAlert = function(type, message, options) {
+    if (type === 'success') return;
+    return baseSetAlert(type, message, options);
+  };
   form.on('submit', function(submission) {
     var token = Formio.getToken();
     statusEl.innerHTML = token ? 'Token captured, completing login...' : 'Error: No token received from Form.io SDK';
@@ -46,7 +52,10 @@ Formio.createForm(document.getElementById('formio'), '${loginFormUrl}').then(fun
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ token: token })
     }).then(function() {
-      statusEl.innerHTML = 'Login successful. You can close this tab.';
+      document.querySelector('.auth-card').innerHTML =
+        '<div class="alert alert-success text-center mb-0" role="alert">' +
+        '<i class="bi bi-check-circle-fill me-2"></i>Login successful. You may close this window.' +
+        '</div>';
     }).catch(function(err) {
       statusEl.innerHTML = 'Error sending token: ' + err.message;
     });

package/dist/revisions/browser-prompts.d.ts

@@ -0,0 +1,10 @@
+export type RevisionsConsentChoice = 'enable-original' | 'enable-current' | 'proceed-without-history' | 'cancel';
+export type RevisionsLicenseConsentChoice = 'continue' | 'cancel';
+export interface BrowserConsentOptions {
+    onReady?: (port: number) => void;
+    openBrowser?: boolean;
+}
+export type RequestRevisionsLicenseConsentOptions = BrowserConsentOptions;
+export declare function requestRevisionsLicenseConsent(deploymentLabel: string, actionLabel: string, options?: RequestRevisionsLicenseConsentOptions): Promise<RevisionsLicenseConsentChoice>;
+export type RequestRevisionsConsentOptions = BrowserConsentOptions;
+export declare function requestRevisionsConsent(formName: string, formId: string, options?: RequestRevisionsConsentOptions): Promise<RevisionsConsentChoice>;

package/dist/revisions/browser-prompts.js

@@ -0,0 +1,220 @@
+// TEMPORARY: browser-based consent prompt for MCP clients that do not yet support
+// the `elicitation` capability. Remove this module (and its call site in
+// form_update.ts) once elicitation is universally supported by the clients we
+// care about.
+import express from 'express';
+import { exec } from 'child_process';
+const esc = (s) => s.replace(/</g, '&lt;');
+const SHARED_STYLE = `
+  :root {
+    --formio-green: #67b346; --formio-green-dark: #4f9132;
+    --ink: #1f2933; --ink-soft: #52606d; --ink-mute: #7b8794;
+    --line: #e4e7eb; --line-soft: #f1f4f7;
+    --surface: #fff; --bg: #f7f9fb;
+    --danger: #b3261e; --danger-soft: #fdecea;
+    --warning-bg: #fff8e6; --warning-border: #f4d27a;
+    --shadow: 0 1px 2px rgba(15,23,42,.04), 0 8px 24px rgba(15,23,42,.06);
+  }
+  * { box-sizing: border-box; }
+  body { font-family: 'Inter', 'Helvetica Neue', Helvetica, Arial, sans-serif; background: var(--bg); margin: 0; padding: 3rem 1rem; color: var(--ink); -webkit-font-smoothing: antialiased; }
+  .shell { max-width: 600px; margin: 0 auto; }
+  .brand { display: flex; align-items: center; justify-content: center; margin-bottom: 1.5rem; }
+  .brand img { height: 32px; width: auto; }
+  .card { background: var(--surface); border: 1px solid var(--line); border-radius: 12px; box-shadow: var(--shadow); overflow: hidden; }
+  .card-header { padding: 1.5rem 1.75rem 1rem; border-bottom: 1px solid var(--line-soft); }
+  .header-title { margin: 0 0 .4rem; font-size: 1.25rem; font-weight: 600; }
+  .header-sub { margin: 0; font-size: .92rem; color: var(--ink-soft); }
+  .meta { display: flex; flex-wrap: wrap; gap: .75rem; align-items: center; margin: 1rem 1.75rem; padding: .75rem 1rem; background: var(--warning-bg); border: 1px solid var(--warning-border); border-radius: 8px; font-size: .88rem; color: var(--ink-soft); }
+  .meta-label { font-weight: 600; color: var(--ink); }
+  .meta-id { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: .82rem; color: var(--ink-mute); word-break: break-all; }
+  .section-title { margin: 1.5rem 1.75rem .5rem; font-size: .72rem; font-weight: 600; text-transform: uppercase; letter-spacing: .08em; color: var(--ink-mute); }
+  .choices { padding: 0 1.75rem 1.5rem; display: flex; flex-direction: column; gap: .75rem; }
+  .choice { display: block; width: 100%; background: var(--surface); color: var(--ink); border: 1px solid var(--line); border-radius: 10px; padding: .9rem 1.1rem; text-align: left; cursor: pointer; font: inherit; transition: border-color 120ms ease, background 120ms ease; }
+  .choice:hover { border-color: var(--ink-mute); }
+  .choice-title { font-weight: 600; font-size: .95rem; display: flex; align-items: center; gap: .5rem; }
+  .choice-desc { margin-top: .25rem; font-size: .85rem; color: var(--ink-soft); line-height: 1.4; }
+  .choice.is-recommended { border-color: var(--formio-green); background: rgba(103,179,70,.06); }
+  .choice.is-recommended:hover { background: rgba(103,179,70,.12); border-color: var(--formio-green-dark); }
+  .choice.is-recommended .choice-title { color: var(--formio-green-dark); }
+  .choice.is-danger { color: var(--danger); border-color: var(--danger); }
+  .choice.is-danger:hover { background: var(--danger-soft); }
+  .pill { font-size: .65rem; font-weight: 700; text-transform: uppercase; letter-spacing: .06em; padding: .15rem .5rem; border-radius: 999px; background: var(--formio-green); color: #fff; }
+  .status { padding: 0 1.75rem 1.5rem; text-align: center; color: var(--ink-mute); font-size: .85rem; min-height: 1.25rem; }
+  .footnote { text-align: center; color: var(--ink-mute); font-size: .78rem; margin-top: 1.25rem; }
+`;
+const SHARED_SCRIPT = `
+  var statusEl = document.getElementById('status');
+  document.querySelectorAll('button[data-choice]').forEach(function (btn) {
+    btn.addEventListener('click', function () {
+      var choice = btn.getAttribute('data-choice');
+      statusEl.textContent = 'Sending choice…';
+      document.querySelectorAll('button[data-choice]').forEach(function (b) { b.disabled = true; b.style.opacity = '0.6'; b.style.cursor = 'not-allowed'; });
+      fetch('/callback', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ choice: choice }) })
+        .then(function () { statusEl.textContent = 'Choice captured. You can close this tab.'; })
+        .catch(function (err) { statusEl.textContent = 'Error: ' + err.message; });
+    });
+  });
+`;
+function renderChoice(c) {
+    const cls = c.variant ? `choice is-${c.variant}` : 'choice';
+    const pill = c.pill ? ` <span class="pill">${esc(c.pill)}</span>` : '';
+    return `<button class="${cls}" data-choice="${esc(c.value)}">
+    <div class="choice-title">${esc(c.title)}${pill}</div>
+    <div class="choice-desc">${esc(c.desc)}</div>
+  </button>`;
+}
+function renderPage(opts) {
+    const metaIdHtml = opts.meta.id ? `<span class="meta-id">${esc(opts.meta.id)}</span>` : '';
+    const sectionsHtml = opts.sections
+        .map((s) => {
+        const title = s.title ? `<div class="section-title">${esc(s.title)}</div>` : '';
+        return `${title}<div class="choices">${s.choices.map(renderChoice).join('')}</div>`;
+    })
+        .join('');
+    return `<!DOCTYPE html>
+<html><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(opts.title)}</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter:400,500,600,700&display=swap">
+<style>${SHARED_STYLE}</style>
+</head><body>
+<div class="shell">
+  <div class="brand"><img src="https://portal.form.io/template/images/formio-logo-with-slogan.png" alt="Form.io"></div>
+  <div class="card">
+    <div class="card-header">
+      <h1 class="header-title">${esc(opts.headerTitle)}</h1>
+      <p class="header-sub">${esc(opts.headerSub)}</p>
+    </div>
+    <div class="meta">
+      <span class="meta-label">${esc(opts.meta.label)}:</span>
+      <strong>${esc(opts.meta.value)}</strong>
+      ${metaIdHtml}
+    </div>
+    ${sectionsHtml}
+    <div class="status" id="status">&nbsp;</div>
+  </div>
+  <div class="footnote">Form.io MCP local consent prompt · You can close this tab after choosing.</div>
+</div>
+<script>${SHARED_SCRIPT}</script>
+</body></html>`;
+}
+// Shared runner: spins up a local express server on an ephemeral port, renders
+// the consent page, opens the browser, and waits for the browser to POST the
+// user's choice back to `/callback`.
+async function runBrowserConsent(page, normalize, options = {}) {
+    const app = express();
+    app.use(express.json());
+    let resolveChoice;
+    const choicePromise = new Promise((resolve) => {
+        resolveChoice = resolve;
+    });
+    app.get('/', (_req, res) => res.send(page()));
+    app.post('/callback', (req, res) => {
+        const raw = req.body.choice;
+        res.send('Choice captured. You can close this tab.');
+        resolveChoice(normalize(raw));
+    });
+    const server = app.listen(0, '127.0.0.1', () => {
+        const addr = server.address();
+        if (addr && typeof addr !== 'string') {
+            const consentUrl = `http://127.0.0.1:${addr.port}/`;
+            if (options.openBrowser !== false) {
+                const openCmd = process.platform === 'darwin'
+                    ? 'open'
+                    : process.platform === 'win32'
+                        ? 'start'
+                        : 'xdg-open';
+                exec(`${openCmd} "${consentUrl}"`);
+            }
+            options.onReady?.(addr.port);
+        }
+    });
+    try {
+        return await choicePromise;
+    }
+    finally {
+        server.close();
+    }
+}
+export async function requestRevisionsLicenseConsent(deploymentLabel, actionLabel, options = {}) {
+    const page = () => renderPage({
+        title: 'Form.io — Security Module Required',
+        headerTitle: 'Form revisions are not available on this deployment',
+        headerSub: `The Security Module is required for revision tracking. You can still ${actionLabel}, but history will not be preserved.`,
+        meta: { label: 'Deployment', value: deploymentLabel },
+        sections: [
+            {
+                choices: [
+                    {
+                        value: 'continue',
+                        title: 'Continue without revision tracking',
+                        desc: 'Proceed with the action. Remembered for this deployment across future sessions.',
+                        variant: 'recommended',
+                    },
+                    {
+                        value: 'cancel',
+                        title: 'Cancel',
+                        desc: 'Abort the action. No changes are made.',
+                        variant: 'danger',
+                    },
+                ],
+            },
+        ],
+    });
+    return runBrowserConsent(page, (raw) => (raw === 'continue' ? 'continue' : 'cancel'), options);
+}
+const REVISIONS_CHOICES = [
+    'enable-original',
+    'enable-current',
+    'proceed-without-history',
+    'cancel',
+];
+export async function requestRevisionsConsent(formName, formId, options = {}) {
+    const page = () => renderPage({
+        title: 'Form.io — Revisions Disabled',
+        headerTitle: 'Revisions are disabled for this form',
+        headerSub: 'Choose how Form.io should track this update. It is recommended to enable revisions. They track every update so you can audit changes, roll back, or pin submissions to a prior form version.',
+        meta: { label: 'Form', value: formName, id: formId },
+        sections: [
+            {
+                title: 'Recommended',
+                choices: [
+                    {
+                        value: 'enable-original',
+                        title: 'Enable revisions',
+                        pill: 'Original',
+                        desc: 'Track revision history; submissions render against the form version active when they were submitted.',
+                        variant: 'recommended',
+                    },
+                    {
+                        value: 'enable-current',
+                        title: 'Enable revisions',
+                        pill: 'Current',
+                        desc: 'Track revision history; submissions always render against the latest form version.',
+                        variant: 'recommended',
+                    },
+                ],
+            },
+            {
+                title: 'Other',
+                choices: [
+                    {
+                        value: 'proceed-without-history',
+                        title: 'Update without history',
+                        desc: 'Proceed with the update — no audit trail. The form will continue to operate without revision history.',
+                    },
+                    {
+                        value: 'cancel',
+                        title: 'Cancel',
+                        desc: 'Make no changes. The pending update is discarded.',
+                        variant: 'danger',
+                    },
+                ],
+            },
+        ],
+    });
+    return runBrowserConsent(page, (raw) => REVISIONS_CHOICES.includes(raw)
+        ? raw
+        : 'cancel', options);
+}

package/dist/revisions/flows.d.ts

@@ -0,0 +1,18 @@
+import { ResolvedFormioConfig } from '../config.js';
+export declare const DRAFT_FIELDS: readonly ["components", "settings", "tags", "properties", "controller", "esign", "display"];
+export declare const REVERT_FIELDS: readonly ["components", "tags", "properties", "display"];
+export interface DraftFlowOptions {
+    formId: string;
+    form: Record<string, unknown>;
+    _vnote: string;
+    cfg: ResolvedFormioConfig;
+}
+export interface RevertOptions {
+    formId: string;
+    version: string;
+    _vnote: string;
+    cfg: ResolvedFormioConfig;
+}
+export declare function saveDraft({ formId, form, _vnote, cfg }: DraftFlowOptions): Promise<unknown>;
+export declare function publishDraft({ formId, _vnote, cfg }: Omit<DraftFlowOptions, 'form'>): Promise<unknown>;
+export declare function revertToRevision({ formId, version, _vnote, cfg }: RevertOptions): Promise<unknown>;

package/dist/revisions/flows.js

@@ -0,0 +1,68 @@
+import { formioFetch } from '../formio-client.js';
+import { prefixVnote } from './helpers.js';
+export const DRAFT_FIELDS = [
+    'components',
+    'settings',
+    'tags',
+    'properties',
+    'controller',
+    'esign',
+    'display',
+];
+export const REVERT_FIELDS = ['components', 'tags', 'properties', 'display'];
+function pickFields(source, fields) {
+    return Object.fromEntries(Object.entries(source).filter(([k]) => fields.includes(k)));
+}
+// Draft body must be a subset of DRAFT_FIELDS — anything outside that set is
+// Reject up front so the LLM picks the right tool
+// path (standard form_update for identity/policy edits) instead of staging
+// changes that will vanish.
+function rejectNonDraftFields(form) {
+    const allowed = new Set(DRAFT_FIELDS);
+    const offending = Object.keys(form).filter((k) => !allowed.has(k));
+    if (offending.length === 0)
+        return;
+    throw new Error(`Draft body contains fields that cannot be staged: ${offending.join(', ')}. ` +
+        `Drafts only stage these fields: ${DRAFT_FIELDS.join(', ')}. ` +
+        `For identity (title, name, path), policy (access, submissionAccess, revisions), ` +
+        `or other fields, call form_update WITHOUT draft: true to apply them immediately. ` +
+        `Do NOT retry this call with draft: true.`);
+}
+export async function saveDraft({ formId, form, _vnote, cfg }) {
+    rejectNonDraftFields(form);
+    // if no draft exists, the endpoint returns the live form
+    const base = (await formioFetch(`form/${formId}/draft`, {}, cfg));
+    await formioFetch(`form/${formId}/draft`, {}, cfg, {
+        method: 'PUT',
+        body: { ...base, ...form, _vnote: prefixVnote(_vnote) },
+    });
+    // fresh GET since PUT returns stale body
+    return await formioFetch(`form/${formId}/draft`, {}, cfg);
+}
+export async function publishDraft({ formId, _vnote, cfg }) {
+    // GET /draft falls back to the live form when no draft exists, so distinguish
+    // by _vid: only the draft revision has _vid === 'draft'.
+    const draft = (await formioFetch(`form/${formId}/draft`, {}, cfg));
+    if (draft._vid !== 'draft') {
+        throw new Error(`No draft exists for form "${formId}". Create one via form_update with draft: true.`);
+    }
+    const live = (await formioFetch(`form/${formId}`, {}, cfg));
+    await formioFetch(`form/${formId}`, {}, cfg, {
+        method: 'PUT',
+        body: { ...live, ...pickFields(draft, DRAFT_FIELDS), _vnote: prefixVnote(_vnote) },
+    });
+    return await formioFetch(`form/${formId}`, {}, cfg);
+}
+export async function revertToRevision({ formId, version, _vnote, cfg }) {
+    const revision = (await formioFetch(`form/${formId}/v/${version}`, {}, cfg));
+    const live = (await formioFetch(`form/${formId}`, {}, cfg));
+    await formioFetch(`form/${formId}`, {}, cfg, {
+        method: 'PUT',
+        body: {
+            ...live,
+            ...pickFields(revision, REVERT_FIELDS),
+            _vnote: prefixVnote(_vnote),
+        },
+    });
+    return await formioFetch(`form/${formId}`, {}, cfg);
+}

package/dist/revisions/helpers.d.ts

@@ -0,0 +1,5 @@
+export declare const VNOTE_PREFIX = "@formio/mcp:";
+export declare function prefixVnote(note: string): string;
+export declare const stripRevisions: ({ revisions: _revisions, ...rest }: Record<string, unknown>) => {
+    [x: string]: unknown;
+};

package/dist/revisions/helpers.js

@@ -0,0 +1,7 @@
+export const VNOTE_PREFIX = '@formio/mcp:';
+export function prefixVnote(note) {
+    return `${VNOTE_PREFIX} ${note}`;
+}
+export const stripRevisions = ({ 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+revisions: _revisions, ...rest }) => rest;

package/dist/revisions/index.d.ts

@@ -0,0 +1,4 @@
+export { saveDraft, publishDraft, revertToRevision } from './flows.js';
+export { gateRevisionsLicense } from './license.js';
+export { gateRevisionsTracking } from './tracking.js';
+export { prefixVnote } from './helpers.js';

package/dist/revisions/index.js

@@ -0,0 +1,4 @@
+export { saveDraft, publishDraft, revertToRevision } from './flows.js';
+export { gateRevisionsLicense } from './license.js';
+export { gateRevisionsTracking } from './tracking.js';
+export { prefixVnote } from './helpers.js';

package/dist/revisions/license.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ResolvedFormioConfig } from '../config.js';
+import { RevisionsLicenseConsentChoice } from './browser-prompts.js';
+export declare function checkRevisionsLicensed(cfg: ResolvedFormioConfig): Promise<boolean>;
+export declare function getRevisionsLicenseConsent(server: McpServer, cfg: ResolvedFormioConfig, actionLabel: string): Promise<RevisionsLicenseConsentChoice>;
+export declare function confirmProceedWithoutRevisions(server: McpServer, cfg: ResolvedFormioConfig, actionLabel: string): Promise<void>;
+export declare function gateRevisionsLicense(server: McpServer, cfg: ResolvedFormioConfig, { actionLabel, requiresRevisions, form, }: {
+    actionLabel: string;
+    requiresRevisions: boolean;
+    form: Record<string, unknown>;
+}): Promise<{
+    licensed: boolean;
+    form: Record<string, unknown>;
+}>;

package/dist/revisions/license.js

@@ -0,0 +1,137 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { requestRevisionsLicenseConsent, } from './browser-prompts.js';
+import { stripRevisions } from './helpers.js';
+// ─── License detection ──────────────────────────────────────────────────────
+// Resolves the deployment's Security Module flag (`sac`) from the anonymous
+// `/config.js`. Cached per `baseUrl` — license is deployment-wide.
+const revisionsLicensedByBaseUrl = new Map();
+const SAC_PATTERN = /\bsac\s*=\s*(true|false)\b/i;
+export async function checkRevisionsLicensed(cfg) {
+    const cached = revisionsLicensedByBaseUrl.get(cfg.baseUrl);
+    if (cached !== undefined)
+        return cached;
+    let revisionsLicensed = false;
+    try {
+        const url = new URL('config.js', `${cfg.baseUrl.replace(/\/*$/, '/')}`);
+        const response = await fetch(url);
+        if (response.ok) {
+            const body = await response.text();
+            const match = body.match(SAC_PATTERN);
+            revisionsLicensed = match?.[1]?.toLowerCase() === 'true';
+        }
+    }
+    catch {
+        revisionsLicensed = false;
+    }
+    revisionsLicensedByBaseUrl.set(cfg.baseUrl, revisionsLicensed);
+    return revisionsLicensed;
+}
+// ─── Persistent consent store ───────────────────────────────────────────────
+// `~/.formio/revisions-license-consent.json`, keyed by `baseUrl`. Only
+// positive consent ("continue") is persisted; cancel is transient.
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), '.formio');
+const CACHE_FILE = 'revisions-license-consent.json';
+async function readCache(cacheDir) {
+    const filePath = path.join(cacheDir, CACHE_FILE);
+    try {
+        const contents = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(contents);
+        const result = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (v === true)
+                result[k] = true;
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+async function writeCache(cacheDir, data) {
+    await fs.mkdir(cacheDir, { recursive: true });
+    const filePath = path.join(cacheDir, CACHE_FILE);
+    await fs.writeFile(filePath, JSON.stringify(data), { mode: 0o600 });
+}
+async function readRevisionsLicenseConsent(baseUrl, cacheDir = DEFAULT_CACHE_DIR) {
+    const data = await readCache(cacheDir);
+    return data[baseUrl] === true;
+}
+async function saveRevisionsLicenseConsent(baseUrl, cacheDir = DEFAULT_CACHE_DIR) {
+    const data = await readCache(cacheDir);
+    data[baseUrl] = true;
+    await writeCache(cacheDir, data);
+}
+// ─── In-memory consent layered over the persistent store ───────────────────
+// Lookup order: memory → disk → prompt.
+const revisionsLicenseConsentByBaseUrl = new Map();
+export async function getRevisionsLicenseConsent(server, cfg, actionLabel) {
+    const cached = revisionsLicenseConsentByBaseUrl.get(cfg.baseUrl);
+    if (cached)
+        return cached;
+    if (await readRevisionsLicenseConsent(cfg.baseUrl)) {
+        revisionsLicenseConsentByBaseUrl.set(cfg.baseUrl, 'continue');
+        return 'continue';
+    }
+    const supportsElicitation = Boolean(server.server.getClientCapabilities()?.elicitation);
+    let choice;
+    if (supportsElicitation) {
+        const result = await server.server.elicitInput({
+            message: `Form revisions are not available on this Form.io deployment (the Security Module is required on the license). You can still ${actionLabel}, but history will not be saved. Continue?`,
+            requestedSchema: {
+                type: 'object',
+                properties: {
+                    choice: {
+                        type: 'string',
+                        title: 'How to proceed',
+                        enum: ['continue', 'cancel'],
+                        enumNames: [
+                            'Continue without revision tracking (remembered for this deployment across future sessions)',
+                            'Cancel',
+                        ],
+                    },
+                },
+                required: ['choice'],
+            },
+        });
+        if (result.action !== 'accept' || !result.content?.choice) {
+            choice = 'cancel';
+        }
+        else {
+            choice = result.content.choice === 'continue' ? 'continue' : 'cancel';
+        }
+    }
+    else {
+        // TEMPORARY: browser-consent fallback for MCP clients that do not yet support elicitation.
+        choice = await requestRevisionsLicenseConsent(cfg.baseUrl, actionLabel);
+    }
+    // Only cache positive consent — cancel is transient so users can change their mind.
+    if (choice === 'continue') {
+        revisionsLicenseConsentByBaseUrl.set(cfg.baseUrl, choice);
+        await saveRevisionsLicenseConsent(cfg.baseUrl);
+    }
+    return choice;
+}
+// Prompts the user if they want to proceed when revisions are not enabled on the license
+export async function confirmProceedWithoutRevisions(server, cfg, actionLabel) {
+    const consent = await getRevisionsLicenseConsent(server, cfg, actionLabel);
+    if (consent === 'cancel') {
+        throw new Error(`USER CANCELLED. The user explicitly chose to cancel: ${actionLabel}. Do NOT retry. Do NOT suggest workarounds, alternative projects, or enabling the Security Module. Do NOT offer to switch deployments. Simply acknowledge the cancellation to the user in one short sentence and stop. The user is aware of why they cancelled.`);
+    }
+}
+// Top-level license gate. Throws when the action requires revisions on an
+// unlicensed deployment; otherwise prompts for "continue without history"
+// consent when unlicensed. Returns the resolved licensed flag and the form
+// body with `revisions` stripped when unlicensed (passthrough when licensed).
+export async function gateRevisionsLicense(server, cfg, { actionLabel, requiresRevisions, form, }) {
+    const licensed = await checkRevisionsLicensed(cfg);
+    if (!licensed && requiresRevisions) {
+        throw new Error(`Cannot ${actionLabel} — the Security Module is required to use revisions, so drafts, publishes, and reverts are unavailable. Drop the draft/publish/revert flag and call form_update as a standard update to apply your changes.`);
+    }
+    // for standard creates/updates, confirm with the user that they don't care if history is not preserved
+    if (!licensed) {
+        await confirmProceedWithoutRevisions(server, cfg, actionLabel);
+    }
+    return { licensed, form: licensed ? form : stripRevisions(form) };
+}

package/dist/revisions/tracking.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ResolvedFormioConfig } from '../config.js';
+export interface RevisionsTrackingGateOptions {
+    formId: string;
+    form: Record<string, unknown>;
+    /** Whether the deployment is licensed for revisions. When false, skip the per-form prompt. */
+    licensed: boolean;
+    cfg: ResolvedFormioConfig;
+}
+export declare function gateRevisionsTracking(server: McpServer, opts: RevisionsTrackingGateOptions): Promise<Record<string, unknown>>;

package/dist/revisions/tracking.js

@@ -0,0 +1,103 @@
+import { formioFetch } from '../formio-client.js';
+import { requestRevisionsConsent } from './browser-prompts.js';
+import { stripRevisions } from './helpers.js';
+// Session-scoped set of formIds the user already approved "without history" for.
+// Module-level so per-form approval persists across calls
+const approvedWithoutHistory = new Set();
+// Per-form revisions-tracking mode gate. Distinct from the deployment-level
+// license gate in license.ts: this prompt asks "for THIS specific form, how
+// should revisions be tracked" (original / current / off), not "is the
+// deployment licensed at all."
+//
+// The prompt fires ONLY when ALL of the following hold:
+//   1. Deployment IS licensed for revisions (`licensed` is true).
+//   2. The targeted form has revisions disabled (`stored.revisions` is falsy).
+//   3. The caller did not opt in by passing `revisions: 'original' | 'current'`
+//      on the body.
+//   4. The user has not already approved "proceed without history" for this
+//      form in the current session.
+//
+// If any of those fail, the gate is a no-op and returns the body unchanged.
+async function promptRevisionsMode(server, stored, formId) {
+    const supportsElicitation = Boolean(server.server.getClientCapabilities()?.elicitation);
+    if (supportsElicitation) {
+        const result = await server.server.elicitInput({
+            message: `Form "${stored.name ?? formId}" has revisions disabled. It is recommended to enable revisions. They track every update so you can audit changes, roll back, or pin submissions to a prior form version. How would you like to proceed?`,
+            requestedSchema: {
+                type: 'object',
+                properties: {
+                    choice: {
+                        type: 'string',
+                        title: 'Revision mode for this update',
+                        enum: ['enable-original', 'enable-current', 'proceed-without-history'],
+                        enumNames: [
+                            'Enable revisions (original) and update',
+                            'Enable revisions (current) and update',
+                            'Proceed without history (not tracked)',
+                        ],
+                        description: 'original = submissions render against the form version active when they were submitted; current = submissions always render against the latest form version; proceed-without-history = no audit trail.',
+                    },
+                },
+                required: ['choice'],
+            },
+        });
+        if (result.action !== 'accept' || !result.content?.choice)
+            return 'cancel';
+        const c = result.content.choice;
+        if (c === 'enable-original' || c === 'enable-current' || c === 'proceed-without-history') {
+            return c;
+        }
+        return 'cancel';
+    }
+    // TEMPORARY: browser-consent fallback for MCP clients that do not yet support elicitation.
+    // Remove once elicitation is universally supported by the clients we care about.
+    const formName = typeof stored.name === 'string' ? stored.name : formId;
+    return requestRevisionsConsent(formName, formId);
+}
+// Returns the stored form when a per-form revisions prompt is required;
+// returns null when the gate should be bypassed.
+//
+// Bypass rule: only treat the caller as having supplied `revisions` when they
+// opted IN to tracking (`original` / `current`). Passing `revisions: ''`
+// mirrors the disabled stored state and must NOT bypass the prompt — that
+// loophole lets an LLM silently skip the audit-trail decision on every form
+// by always echoing the disabled value.
+async function shouldPromptForRevisions(opts) {
+    const { formId, form, licensed, cfg } = opts;
+    const callerOptedIn = form.revisions === 'original' || form.revisions === 'current';
+    // Skip when the deployment doesn't have revisions enabled on the license — the user's "continue without
+    // revision tracking" choice is captured at the license-gate layer, so
+    // re-prompting per-form is redundant.
+    if (callerOptedIn || !licensed)
+        return null;
+    const stored = (await formioFetch(`form/${formId}`, {}, cfg));
+    if (stored.revisions || approvedWithoutHistory.has(formId))
+        return null;
+    return stored;
+}
+// Returns the PUT body for the standard form_update path with the user's
+// per-form revisions-mode choice applied. Throws on cancel so the calling
+// tool's outer try/catch surfaces it via toMcpError.
+export async function gateRevisionsTracking(server, opts) {
+    const { formId, form } = opts;
+    let putBody = { ...form };
+    const stored = await shouldPromptForRevisions(opts);
+    if (!stored)
+        return putBody;
+    const choice = await promptRevisionsMode(server, stored, formId);
+    if (choice === 'cancel') {
+        throw new Error(`User declined to update form "${formId}". No changes were made.`);
+    }
+    if (choice === 'enable-original' || choice === 'enable-current') {
+        putBody = {
+            ...putBody,
+            revisions: choice === 'enable-original' ? 'original' : 'current',
+        };
+        return putBody;
+    }
+    // proceed-without-history: drop any caller-supplied `revisions: ''` so the
+    // PUT body matches "no revisions change". Remember for the rest of the
+    // session so the user is asked only once per form.
+    approvedWithoutHistory.add(formId);
+    return stripRevisions(putBody);
+}

package/dist/tools/form_create.js

@@ -2,8 +2,9 @@ import { z } from 'zod';
 import { formioFetch } from '../formio-client.js';
 import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
 import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+import { gateRevisionsLicense, prefixVnote } from '../revisions/index.js';
 export function registerFormCreateTool(server, config) {
-    server.tool('form_create', "Create a new form in the Form.io project mapped to the user's current working directory. IMPORTANT: Before calling this tool, use the formio-form skill to construct a properly structured Form.io form JSON definition based on the user's requirements. The skill documents all component types, validation options, layout patterns, and conditional logic available in Form.io.", {
+    server.tool('form_create', 'Create a new form in the Form.io project mapped to the user\'s current working directory. IMPORTANT: Before calling this tool, use the formio-schema skill to construct a properly structured Form.io form JSON definition based on the user\'s requirements. The skill documents all component types, validation options, layout patterns, and conditional logic available in Form.io. New forms default to `revisions: \'original\'` so form change history is preserved. NOT for: creating a draft revision of an existing form. When the user says "create/save a draft", "draft <change>", call form_update with `formId` and `draft: true` instead.', {
         cwd: cwdSchema,
         form: z
             .looseObject({
@@ -19,15 +20,30 @@ export function registerFormCreateTool(server, config) {
                 .optional()
                 .describe('Display mode (default: "form")'),
             tags: z.array(z.string()).optional().describe('Tags for categorization'),
+            revisions: z
+                .enum(['current', 'original', ''])
+                .optional()
+                .describe('Revision mode (default: "original"). Pass "" to disable'),
         })
             .catchall(z.unknown())
             .describe('Form.io form JSON definition'),
-    }, async ({ cwd, form }) => {
+        note: z.string().optional().describe('Note describing the initial revision'),
+    }, async ({ cwd, form: rawForm, note }) => {
         try {
             const cfg = resolveProjectConfig(cwd, config);
+            const { licensed, form } = await gateRevisionsLicense(server, cfg, {
+                actionLabel: 'create this form',
+                requiresRevisions: false,
+                form: rawForm,
+            });
             const created = await formioFetch('form', {}, cfg, {
                 method: 'POST',
-                body: form,
+                body: {
+                    // gate already stripped `revisions` on unlicensed deployments; on
+                    // licensed ones default to 'original' unless the caller overrode.
+                    ...(licensed ? { revisions: 'original', ...form } : form),
+                    ...(note && { _vnote: prefixVnote(note) }),
+                },
             });
             return toMcpTextResult(created);
         }

package/dist/tools/form_get.js

@@ -3,19 +3,29 @@ import { formioFetch, isMongoId } from '../formio-client.js';
 import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
 import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
 export function registerFormGetTool(server, config) {
-    server.tool('form_get', "Fetch a single form definition from the Form.io project mapped to the user's current working directory, by form ID or path.", {
+    server.tool('form_get', "Fetch a single form definition from the Form.io project mapped to the user's current working directory, by form ID or path. Pass `draft: true` to fetch the form's current in-flight draft instead of the published form.", {
         cwd: cwdSchema,
         formIdOrPath: z.string().describe('Form ID (_id) or path (e.g. "user/login")'),
         select: z
             .string()
             .optional()
             .describe('Comma-separated fields to return (omit for full form JSON)'),
-    }, async ({ cwd, formIdOrPath, select }) => {
+        draft: z
+            .boolean()
+            .optional()
+            .describe("When true, fetch the form's current draft (GET /<form>/draft)"),
+    }, async ({ cwd, formIdOrPath, select, draft }) => {
         try {
             const cfg = resolveProjectConfig(cwd, config);
             const params = { select };
-            const path = isMongoId(formIdOrPath) ? `form/${formIdOrPath}` : formIdOrPath;
-            const form = await formioFetch(path, params, cfg);
+            const base = isMongoId(formIdOrPath) ? `form/${formIdOrPath}` : formIdOrPath;
+            const path = draft ? `${base}/draft` : base;
+            const form = (await formioFetch(path, params, cfg));
+            // GET /draft falls back to the live form when no draft exists, so
+            // distinguish by _vid: only the draft revision has _vid === 'draft'.
+            if (draft && form._vid !== 'draft') {
+                throw new Error(`No draft exists for form "${formIdOrPath}". Create one via form_update with draft: true.`);
+            }
             return toMcpTextResult(form);
         }
         catch (error) {

package/dist/tools/form_revision_get.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FormioConfig } from '../config.js';
+export declare function registerFormRevisionGetTool(server: McpServer, config: FormioConfig): void;

package/dist/tools/form_revision_get.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { formioFetch, isMongoId } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerFormRevisionGetTool(server, config) {
+    server.tool('form_revision_get', 'Fetch a single immutable form revision from the Form.io project mapped to the current working directory. `version` accepts either the revision `_vid` (e.g. "3") or the revision document `_id` (24-character hex). To revert the live form to this revision, pass its `form` body to `form_update` with a `note` like `Revert to v<vid>`.', {
+        cwd: cwdSchema,
+        formIdOrPath: z.string().describe('Form ID (_id) or path alias (e.g. "user/login")'),
+        version: z.string().describe('Revision _vid (e.g. "3") or revision document _id'),
+    }, async ({ cwd, formIdOrPath, version }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const base = isMongoId(formIdOrPath) ? `form/${formIdOrPath}` : formIdOrPath;
+            const revision = await formioFetch(`${base}/v/${version}`, {}, cfg);
+            return toMcpTextResult(revision);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/form_revisions_list.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FormioConfig } from '../config.js';
+export declare function registerFormRevisionsListTool(server: McpServer, config: FormioConfig): void;

package/dist/tools/form_revisions_list.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { formioFetch, isMongoId } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerFormRevisionsListTool(server, config) {
+    server.tool('form_revisions_list', 'List immutable published revision summaries for a single form in the Form.io project mapped to the current working directory. Returns compact revision metadata (_vid, _id, modified, user, _vnote) for the form identified by `formIdOrPath`. To inspect a specific revision body, call `form_revision_get` with the desired `_vid`. To revert the live form to a prior revision, pass that revision body to `form_update` with a `note` like `Revert to v<vid>`.', {
+        cwd: cwdSchema,
+        formIdOrPath: z.string().describe('Form ID (_id) or path alias (e.g. "user/login")'),
+    }, async ({ cwd, formIdOrPath }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const base = isMongoId(formIdOrPath) ? `form/${formIdOrPath}` : formIdOrPath;
+            const revisions = await formioFetch(`${base}/v`, {}, cfg);
+            return toMcpTextResult(revisions);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/form_update.js

@@ -2,8 +2,13 @@ import { z } from 'zod';
 import { formioFetch, MONGO_ID_PATTERN } from '../formio-client.js';
 import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
 import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+import { gateRevisionsLicense, gateRevisionsTracking, prefixVnote, publishDraft, revertToRevision, saveDraft, } from '../revisions/index.js';
 export function registerFormUpdateTool(server, config) {
-    server.tool('form_update', "Update an existing form in the Form.io project mapped to the user's current working directory. IMPORTANT: Before calling this tool, first use form_get to fetch the current form definition, then use the formio-form skill to apply the requested modifications (add, remove, or modify fields and settings), and finally call this tool with the complete updated form JSON.", {
+    server.tool('form_update', [
+        "Update an existing form in the Form.io project mapped to the user's current working directory. IMPORTANT: Before calling this tool, first use form_get to fetch the current form definition, then use the formio-schema skill to understand the schema so that you can apply the requested modifications (add, remove, or modify fields and settings), and finally call this tool with the complete updated form JSON.",
+        '`draft`, `publish`, and `revert` are mutually exclusive — pass at most one.',
+        'If `revisions` in the response differs from the stored value, the per-form revisions-mode gate prompted the USER and they chose.',
+    ].join(' '), {
         cwd: cwdSchema,
         formId: z
             .string()
@@ -20,17 +25,69 @@ export function registerFormUpdateTool(server, config) {
             type: z.enum(['form', 'resource']).optional().describe('Form type'),
             display: z.enum(['form', 'wizard', 'pdf']).optional().describe('Display mode'),
             tags: z.array(z.string()).optional().describe('Tags for categorization'),
+            revisions: z
+                .enum(['current', 'original', ''])
+                .optional()
+                .describe('Revision mode. Pass "" to disable; omit to leave the stored value unchanged.'),
         })
             .catchall(z.unknown())
             .describe('Complete updated Form.io form JSON definition'),
-    }, async ({ cwd, formId, form }) => {
+        note: z
+            .string()
+            .describe('Required note describing the diff (live form vs updated body) — no action preambles ("Published draft:", "Saved draft:", "Reverted:"). For `revert: true`, default to "Reverted to version {version}" unless the user explicitly provides a different note.'),
+        draft: z
+            .boolean()
+            .optional()
+            .describe('When true, create or update a draft (PUT /form/{formId}/draft) instead of publishing. Caller `form` fields merge on top of existing draft fields, preserving prior unpublished draft edits.'),
+        publish: z
+            .boolean()
+            .optional()
+            .describe('When true, publish the current draft. Caller `form` body is ignored; only allowlisted revision fields flow from existing draft to live (PUT /form/{formId}).'),
+        revert: z
+            .boolean()
+            .optional()
+            .describe('When true, revert the live form to a prior revision. Requires `version`. Caller `form` body is ignored; only allowlisted revision fields flow from the revision to live.'),
+        version: z
+            .string()
+            .optional()
+            .describe('Revision identifier for `revert: true` — either the revision `_vid` (e.g. "3") or the revision document `_id` (24-char hex).'),
+    }, async ({ cwd, formId, form: rawForm, note, draft, publish, revert, version }) => {
         try {
+            const exclusiveFlags = [draft, publish, revert].filter(Boolean);
+            if (exclusiveFlags.length > 1) {
+                throw new Error('`draft`, `publish`, and `revert` flags are mutually exclusive — pass only one.');
+            }
+            if (revert && !version) {
+                throw new Error('`revert: true` requires `version` (revision `_vid` or document `_id`).');
+            }
             const cfg = resolveProjectConfig(cwd, config);
-            const updated = await formioFetch(`form/${formId}`, {}, cfg, {
-                method: 'PUT',
-                body: form,
+            const actionLabel = `${revert ? 'revert' : publish ? 'publish' : draft ? 'save a draft of' : 'update'} this form`;
+            const { licensed, form } = await gateRevisionsLicense(server, cfg, {
+                actionLabel,
+                requiresRevisions: Boolean(draft || publish || revert),
+                form: rawForm,
             });
-            return toMcpTextResult(updated);
+            if (revert || publish || draft) {
+                const args = { formId, _vnote: note, cfg };
+                return toMcpTextResult(await (revert && version
+                    ? revertToRevision({ ...args, version })
+                    : publish
+                        ? publishDraft(args)
+                        : saveDraft({ ...args, form })));
+            }
+            // Standard PUT path. Apply per-form revisions consent (prompts when
+            // the stored form has revisions disabled and the caller did not opt
+            // in via `revisions: 'original'|'current'`).
+            const putBody = await gateRevisionsTracking(server, {
+                formId,
+                form,
+                licensed,
+                cfg,
+            });
+            return toMcpTextResult(await formioFetch(`form/${formId}`, {}, cfg, {
+                method: 'PUT',
+                body: { ...putBody, _vnote: prefixVnote(note) },
+            }));
         }
         catch (error) {
             return toMcpError(error);

package/dist/tools/index.js

@@ -8,6 +8,8 @@ import { registerActionUpdateTool } from './action_update.js';
 import { registerFormCreateTool } from './form_create.js';
 import { registerFormGetTool } from './form_get.js';
 import { registerFormListTool } from './form_list.js';
+import { registerFormRevisionGetTool } from './form_revision_get.js';
+import { registerFormRevisionsListTool } from './form_revisions_list.js';
 import { registerFormUpdateTool } from './form_update.js';
 import { registerHelloTool } from './hello.js';
 import { registerProjectExportTool } from './project_export.js';
@@ -21,6 +23,8 @@ export function registerAllTools(server, config, options = {}) {
     registerFormCreateTool(server, config);
     registerFormGetTool(server, config);
     registerFormListTool(server, config);
+    registerFormRevisionGetTool(server, config);
+    registerFormRevisionsListTool(server, config);
     registerFormUpdateTool(server, config);
     registerProjectExportTool(server, config);
     registerProjectImportTool(server, config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formio/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Form.io MCP Server",
   "type": "module",
   "license": "MIT",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Form.io LLC
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.