@formio/mcp 0.1.0

package/dist/token-cache.js

@@ -0,0 +1,34 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), '.formio');
+const CACHE_FILE = 'mcp-tokens.json';
+async function readCache(cacheDir) {
+    const filePath = path.join(cacheDir, CACHE_FILE);
+    try {
+        const contents = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(contents);
+    }
+    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 });
+}
+export async function saveToken(baseUrl, jwt, cacheDir = DEFAULT_CACHE_DIR) {
+    const cache = await readCache(cacheDir);
+    cache[baseUrl] = jwt;
+    await writeCache(cacheDir, cache);
+}
+export async function readToken(baseUrl, cacheDir = DEFAULT_CACHE_DIR) {
+    const cache = await readCache(cacheDir);
+    return cache[baseUrl] ?? null;
+}
+export async function clearToken(baseUrl, cacheDir = DEFAULT_CACHE_DIR) {
+    const cache = await readCache(cacheDir);
+    delete cache[baseUrl];
+    await writeCache(cacheDir, cache);
+}

package/dist/token-validation.d.ts

@@ -0,0 +1,2 @@
+import { FormioConfig } from './config.js';
+export declare function validateToken(config: FormioConfig): Promise<boolean>;

package/dist/token-validation.js

@@ -0,0 +1,6 @@
+import { getAuthHeader } from './auth-header.js';
+export async function validateToken(config) {
+    const url = `${config.baseUrl}/current`;
+    const response = await fetch(url, { headers: getAuthHeader(config) });
+    return response.ok;
+}

package/dist/tools/action-schema.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export declare const actionDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodString;
+    handler: z.ZodArray<z.ZodString>;
+    method: z.ZodArray<z.ZodString>;
+    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    condition: z.ZodOptional<z.ZodObject<{
+        conjunction: z.ZodEnum<{
+            all: "all";
+            any: "any";
+        }>;
+        conditions: z.ZodArray<z.ZodObject<{
+            component: z.ZodString;
+            operator: z.ZodEnum<{
+                includes: "includes";
+                endsWith: "endsWith";
+                startsWith: "startsWith";
+                isEqual: "isEqual";
+                isNotEqual: "isNotEqual";
+                isEmpty: "isEmpty";
+                isNotEmpty: "isNotEmpty";
+                greaterThan: "greaterThan";
+                greaterThanOrEqual: "greaterThanOrEqual";
+                lessThan: "lessThan";
+                lessThanOrEqual: "lessThanOrEqual";
+                notIncludes: "notIncludes";
+                isDateEqual: "isDateEqual";
+                isNotDateEqual: "isNotDateEqual";
+                dateGreaterThan: "dateGreaterThan";
+                dateGreaterThanOrEqual: "dateGreaterThanOrEqual";
+                dateLessThan: "dateLessThan";
+                dateLessThanOrEqual: "dateLessThanOrEqual";
+            }>;
+            value: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    priority: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;

package/dist/tools/action-schema.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+const conditionOperator = z.enum([
+    'isEqual',
+    'isNotEqual',
+    'isEmpty',
+    'isNotEmpty',
+    'greaterThan',
+    'greaterThanOrEqual',
+    'lessThan',
+    'lessThanOrEqual',
+    'startsWith',
+    'endsWith',
+    'includes',
+    'notIncludes',
+    'isDateEqual',
+    'isNotDateEqual',
+    'dateGreaterThan',
+    'dateGreaterThanOrEqual',
+    'dateLessThan',
+    'dateLessThanOrEqual',
+]);
+const actionCondition = z
+    .object({
+    conjunction: z.enum(['all', 'any']),
+    conditions: z.array(z.object({
+        component: z.string(),
+        operator: conditionOperator,
+        value: z.unknown().optional(),
+    })),
+})
+    .optional()
+    .describe('Condition for when action runs');
+export const actionDefinitionSchema = z
+    .object({
+    name: z.string().describe('Action type name'),
+    title: z.string().describe('Action title'),
+    handler: z.array(z.string()).describe('Handler phases (e.g. ["before"], ["after"])'),
+    method: z.array(z.string()).describe('Methods (e.g. ["create"], ["update"])'),
+    settings: z.record(z.string(), z.unknown()).optional().describe('Action settings'),
+    condition: actionCondition,
+    priority: z.number().optional().describe('Action priority'),
+})
+    .passthrough()
+    .describe('Action definition');

package/dist/tools/action_create.d.ts

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

package/dist/tools/action_create.js

@@ -0,0 +1,37 @@
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { actionDefinitionSchema } from './action-schema.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+import { z } from 'zod';
+export function registerActionCreateTool(server, config) {
+    server.tool('action_create', 'Create a new action on a form. Call action_type_get first to discover the required settings schema for the action type.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID to attach the action to'),
+        action: actionDefinitionSchema,
+    }, async ({ cwd, formId, action }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const catalog = (await formioFetch(`form/${formId}/actions`, {}, cfg));
+            const availableNames = catalog.map((t) => t.name);
+            if (!availableNames.includes(action.name)) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Action type '${action.name}' is not available on this server. Available types: ${availableNames.join(', ')}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const created = await formioFetch(`form/${formId}/action`, {}, cfg, {
+                method: 'POST',
+                body: action,
+            });
+            return toMcpTextResult(created);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/action_delete.d.ts

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

package/dist/tools/action_delete.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerActionDeleteTool(server, config) {
+    server.tool('action_delete', 'Delete an action from a form.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID the action belongs to'),
+        actionId: z.string().describe('The action ID to delete'),
+    }, async ({ cwd, formId, actionId }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            await formioFetch(`form/${formId}/action/${actionId}`, {}, cfg, {
+                method: 'DELETE',
+            });
+            return { content: [{ type: 'text', text: 'OK' }] };
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/action_get.d.ts

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

package/dist/tools/action_get.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerActionGetTool(server, config) {
+    server.tool('action_get', 'Get a single action by ID from a form.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID the action belongs to'),
+        actionId: z.string().describe('The action ID to retrieve'),
+    }, async ({ cwd, formId, actionId }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const action = await formioFetch(`form/${formId}/action/${actionId}`, {}, cfg);
+            return toMcpTextResult(action);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/action_list.d.ts

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

package/dist/tools/action_list.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerActionListTool(server, config) {
+    server.tool('action_list', 'List actions configured on a form.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID to list actions for'),
+    }, async ({ cwd, formId }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const actions = await formioFetch(`form/${formId}/action`, {}, cfg);
+            return toMcpTextResult(actions);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/action_type_get.d.ts

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

package/dist/tools/action_type_get.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerActionTypeGetTool(server, config) {
+    server.tool('action_type_get', 'Get action type info and settings form schema. Call this before action_create to discover the required settings for the action type.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID to get the action type for'),
+        actionName: z.string().describe('The action type name (e.g. "email", "save", "login")'),
+    }, async ({ cwd, formId, actionName }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            try {
+                const typeInfo = await formioFetch(`form/${formId}/actions/${actionName}`, {}, cfg);
+                return toMcpTextResult(typeInfo);
+            }
+            catch (error) {
+                const catalog = (await formioFetch(`form/${formId}/actions`, {}, cfg).catch(() => {
+                    throw error;
+                }));
+                const availableTypes = catalog.map((t) => t.name).join(', ');
+                throw new Error(`Action type '${actionName}' is not available on this server. Available types: ${availableTypes}`);
+            }
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/action_types_list.d.ts

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

package/dist/tools/action_types_list.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerActionTypesListTool(server, config) {
+    server.tool('action_types_list', 'List available action types for a form. Returns the catalog of action types the server supports.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID to list available action types for'),
+    }, async ({ cwd, formId }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const catalog = await formioFetch(`form/${formId}/actions`, {}, cfg);
+            return toMcpTextResult(catalog);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/action_update.d.ts

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

package/dist/tools/action_update.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { actionDefinitionSchema } from './action-schema.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerActionUpdateTool(server, config) {
+    server.tool('action_update', 'Update an existing action on a form.', {
+        cwd: cwdSchema,
+        formId: z.string().describe('The form ID the action belongs to'),
+        actionId: z.string().describe('The action ID to update'),
+        action: actionDefinitionSchema,
+    }, async ({ cwd, formId, actionId, action }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const updated = await formioFetch(`form/${formId}/action/${actionId}`, {}, cfg, {
+                method: 'PUT',
+                body: action,
+            });
+            return toMcpTextResult(updated);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/form_create.d.ts

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

package/dist/tools/form_create.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.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.", {
+        cwd: cwdSchema,
+        form: z
+            .looseObject({
+            title: z.string().describe('Human-readable form title'),
+            name: z.string().describe('Machine name for API references'),
+            path: z.string().describe('URL path segment for the form'),
+            components: z
+                .array(z.record(z.string(), z.unknown()))
+                .describe('Array of form components'),
+            type: z.enum(['form', 'resource']).optional().describe('Form type (default: "form")'),
+            display: z
+                .enum(['form', 'wizard', 'pdf'])
+                .optional()
+                .describe('Display mode (default: "form")'),
+            tags: z.array(z.string()).optional().describe('Tags for categorization'),
+        })
+            .catchall(z.unknown())
+            .describe('Form.io form JSON definition'),
+    }, async ({ cwd, form }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const created = await formioFetch('form', {}, cfg, {
+                method: 'POST',
+                body: form,
+            });
+            return toMcpTextResult(created);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/form_get.d.ts

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

package/dist/tools/form_get.js

@@ -0,0 +1,25 @@
+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 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.", {
+        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 }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const params = { select };
+            const path = isMongoId(formIdOrPath) ? `form/${formIdOrPath}` : formIdOrPath;
+            const form = await formioFetch(path, params, cfg);
+            return toMcpTextResult(form);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/form_list.d.ts

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

package/dist/tools/form_list.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+const DEFAULT_SELECT = '_id,title,name,path,type,tags';
+const DEFAULT_LIMIT = 20;
+export function registerFormListTool(server, config) {
+    server.tool('form_list', "List forms from the Form.io project mapped to the user's current working directory with optional filtering and pagination.", {
+        cwd: cwdSchema,
+        type: z.enum(['form', 'resource']).optional().describe('Filter by form type'),
+        limit: z.number().optional().describe('Maximum number of forms to return (default: 20)'),
+        skip: z.number().optional().describe('Number of forms to skip for pagination'),
+        sort: z.string().optional().describe('Sort field and direction (e.g. "-created")'),
+        select: z
+            .string()
+            .optional()
+            .describe('Comma-separated fields to return (default: _id,title,name,path,type,tags)'),
+        tags: z.array(z.string()).optional().describe('Filter by tags'),
+    }, async ({ cwd, type, limit, skip, sort, select, tags }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const params = {
+                select: select ?? DEFAULT_SELECT,
+                limit: String(limit ?? DEFAULT_LIMIT),
+                skip: skip !== undefined ? String(skip) : undefined,
+                sort,
+                type,
+                tags: tags?.join(','),
+            };
+            const forms = await formioFetch('form', params, cfg);
+            return toMcpTextResult(forms);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/form_update.d.ts

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

package/dist/tools/form_update.js

@@ -0,0 +1,39 @@
+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';
+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.", {
+        cwd: cwdSchema,
+        formId: z
+            .string()
+            .regex(MONGO_ID_PATTERN, 'Must be a 24-character MongoDB ObjectId')
+            .describe('The _id of the form to update'),
+        form: z
+            .looseObject({
+            title: z.string().optional().describe('Human-readable form title'),
+            name: z.string().optional().describe('Machine name for API references'),
+            path: z.string().optional().describe('URL path segment for the form'),
+            components: z
+                .array(z.record(z.string(), z.unknown()))
+                .describe('Array of form components'),
+            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'),
+        })
+            .catchall(z.unknown())
+            .describe('Complete updated Form.io form JSON definition'),
+    }, async ({ cwd, formId, form }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const updated = await formioFetch(`form/${formId}`, {}, cfg, {
+                method: 'PUT',
+                body: form,
+            });
+            return toMcpTextResult(updated);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/hello.d.ts

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

package/dist/tools/hello.js

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+export function registerHelloTool(server) {
+    server.tool('hello', 'Say hello — used to verify the server is working', { name: z.string().optional().describe('Name to greet') }, async ({ name }) => ({
+        content: [{ type: 'text', text: `Hello from formio-mcp, ${name ?? 'world'}!` }],
+    }));
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FormioConfig } from '../config.js';
+export interface RegisterAllToolsOptions {
+    cwd?: () => string;
+}
+export declare function registerAllTools(server: McpServer, config: FormioConfig, options?: RegisterAllToolsOptions): void;

package/dist/tools/index.js

@@ -0,0 +1,44 @@
+import { registerActionCreateTool } from './action_create.js';
+import { registerActionDeleteTool } from './action_delete.js';
+import { registerActionGetTool } from './action_get.js';
+import { registerActionListTool } from './action_list.js';
+import { registerActionTypeGetTool } from './action_type_get.js';
+import { registerActionTypesListTool } from './action_types_list.js';
+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 { registerFormUpdateTool } from './form_update.js';
+import { registerHelloTool } from './hello.js';
+import { registerProjectExportTool } from './project_export.js';
+import { registerProjectImportTool } from './project_import.js';
+import { registerProjectSetTool } from './project_set.js';
+import { registerRoleCreateTool } from './role_create.js';
+import { registerRoleListTool } from './role_list.js';
+import { registerRoleUpdateTool } from './role_update.js';
+export function registerAllTools(server, config, options = {}) {
+    registerHelloTool(server);
+    registerFormCreateTool(server, config);
+    registerFormGetTool(server, config);
+    registerFormListTool(server, config);
+    registerFormUpdateTool(server, config);
+    registerProjectExportTool(server, config);
+    registerProjectImportTool(server, config);
+    // project_set is only useful when the SessionStart/PreToolUse hook drives
+    // per-cwd project mapping — i.e. plugin context. Standalone .mcp.json users
+    // bind the server to a project via FORMIO_PROJECT_URL instead, so exposing
+    // project_set there just invites drift between the env and the map.
+    if (process.env.FORMIO_PLUGIN_CONTEXT === '1') {
+        registerProjectSetTool(server, { cwd: options.cwd });
+    }
+    registerRoleCreateTool(server, config);
+    registerRoleListTool(server, config);
+    registerRoleUpdateTool(server, config);
+    registerActionTypesListTool(server, config);
+    registerActionTypeGetTool(server, config);
+    registerActionCreateTool(server, config);
+    registerActionListTool(server, config);
+    registerActionGetTool(server, config);
+    registerActionUpdateTool(server, config);
+    registerActionDeleteTool(server, config);
+}

package/dist/tools/project_export.d.ts

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

package/dist/tools/project_export.js

@@ -0,0 +1,17 @@
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerProjectExportTool(server, config) {
+    server.tool('project_export', "Export the complete template (roles, resources, forms, actions) of the Form.io project mapped to the user's current working directory as a portable JSON document. Use this to snapshot a project before importing changes.", {
+        cwd: cwdSchema,
+    }, async ({ cwd }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const template = await formioFetch('export', {}, cfg);
+            return toMcpTextResult(template);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/project_import.d.ts

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

package/dist/tools/project_import.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpError } from '../mcp-responses.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerProjectImportTool(server, config) {
+    server.tool('project_import', "Import a template JSON into the existing Form.io project mapped to the user's current working directory, merging roles, resources, forms, and actions in one call. Use the formio-resource-planner skill to construct the template before calling this tool. WARNING: import merges into the existing project — use project_export first to snapshot.", {
+        cwd: cwdSchema,
+        template: z.looseObject({}).describe('The template JSON object to import'),
+    }, async ({ cwd, template }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const result = await formioFetch('import', {}, cfg, {
+                method: 'POST',
+                body: { template },
+                responseType: 'text',
+            });
+            return { content: [{ type: 'text', text: String(result) }] };
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/project_set.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ProjectSetOptions {
+    cwd?: () => string;
+}
+export declare function registerProjectSetTool(server: McpServer, options?: ProjectSetOptions): void;