@formio/mcp 0.1.0

package/dist/tools/project_set.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { readProjectEntry, writeProjectEntry } from '../project-map.js';
+function normalizeProjectUrl(input) {
+    let parsed;
+    try {
+        parsed = new URL(input);
+    }
+    catch {
+        throw new Error(`projectUrl must be a valid URL, got: ${input}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`projectUrl must use http or https, got: ${parsed.protocol}`);
+    }
+    return input.replace(/\/+$/, '');
+}
+export function registerProjectSetTool(server, options = {}) {
+    const getServerCwd = options.cwd ?? (() => process.cwd());
+    server.tool('project_set', [
+        'Set the active Form.io project for the given working directory by writing the URL to project.json file in formio configuration folder',
+        'You MUST call this tool whenever the user asks to set, change, or switch the active Form.io project — do not merely acknowledge the request in text. Persisting the choice requires the tool call.',
+        "The chosen URL is persisted to project.json file in the formio configuration folder keyed by the cwd argument when provided (or the MCP server process cwd otherwise). Pass the `cwd` argument whenever you know the user's current working directory — the server process cwd is fixed at spawn and may not match where the user actually is.",
+        'Every Form.io tool resolves its project URL from this map on each call, so the new mapping takes effect immediately for subsequent tool calls from the same cwd.',
+    ].join(' '), {
+        projectUrl: z
+            .url({ protocol: /^https?$/ })
+            .describe('Full URL of the Form.io project to activate, e.g. https://api.form.io/my-project'),
+        cwd: z
+            .string()
+            .optional()
+            .describe("User's current working directory to key the persisted mapping against. Pass whenever known (e.g. from UserPromptSubmit hook context). Falls back to the MCP server's process.cwd() when omitted."),
+    }, async ({ projectUrl, cwd }) => {
+        const normalized = normalizeProjectUrl(projectUrl);
+        const entryCwd = cwd ?? getServerCwd();
+        const existing = readProjectEntry(entryCwd);
+        const previousMapped = existing?.env.FORMIO_PROJECT_URL;
+        if (previousMapped === normalized) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Active project is already ${normalized} and persisted for ${entryCwd}; no change`,
+                    },
+                ],
+            };
+        }
+        writeProjectEntry(entryCwd, { FORMIO_PROJECT_URL: normalized });
+        const message = previousMapped
+            ? `Active project set to ${normalized} (was ${previousMapped}; persisted for ${entryCwd})`
+            : `Active project set to ${normalized}; mapping persisted for ${entryCwd}`;
+        return {
+            content: [{ type: 'text', text: message }],
+        };
+    });
+}

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

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export declare const roleFields: {
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    default: z.ZodOptional<z.ZodBoolean>;
+    admin: z.ZodOptional<z.ZodBoolean>;
+};

package/dist/tools/role-schema.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+export const roleFields = {
+    title: z.string().optional().describe('Role title'),
+    description: z.string().optional().describe('Role description'),
+    default: z
+        .boolean()
+        .optional()
+        .describe('When true, role is assigned to every new authenticated user'),
+    admin: z.boolean().optional().describe('When true, holders bypass access checks'),
+};

package/dist/tools/role_create.d.ts

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

package/dist/tools/role_create.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { formioFetch } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { roleFields } from './role-schema.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerRoleCreateTool(server, config) {
+    server.tool('role_create', "Create a new role in the Form.io project mapped to the user's current working directory.", {
+        cwd: cwdSchema,
+        ...roleFields,
+        title: z.string().describe('Role title'),
+    }, async ({ cwd, ...role }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const created = await formioFetch('role', {}, cfg, {
+                method: 'POST',
+                body: role,
+            });
+            return toMcpTextResult(created);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/role_list.d.ts

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

package/dist/tools/role_list.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 registerRoleListTool(server, config) {
+    server.tool('role_list', "List all roles defined in the Form.io project mapped to the user's current working directory.", {
+        cwd: cwdSchema,
+        select: z.string().optional().describe('Comma-separated fields to return'),
+    }, async ({ cwd, select }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const params = { select };
+            const roles = await formioFetch('role', params, cfg);
+            return toMcpTextResult(roles);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/dist/tools/role_update.d.ts

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

package/dist/tools/role_update.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { formioFetch, MONGO_ID_PATTERN } from '../formio-client.js';
+import { toMcpTextResult, toMcpError } from '../mcp-responses.js';
+import { roleFields } from './role-schema.js';
+import { cwdSchema, resolveProjectConfig } from '../project-resolver.js';
+export function registerRoleUpdateTool(server, config) {
+    server.tool('role_update', "Update an existing role in the Form.io project mapped to the user's current working directory. This is a full replacement — include all fields you want to preserve.", {
+        cwd: cwdSchema,
+        roleId: z
+            .string()
+            .regex(MONGO_ID_PATTERN, 'Must be a 24-character MongoDB ObjectId')
+            .describe('The _id of the role to update'),
+        role: z
+            .object(roleFields)
+            .catchall(z.unknown())
+            .describe('Role document with updated fields'),
+    }, async ({ cwd, roleId, role }) => {
+        try {
+            const cfg = resolveProjectConfig(cwd, config);
+            const updated = await formioFetch(`role/${roleId}`, {}, cfg, {
+                method: 'PUT',
+                body: role,
+            });
+            return toMcpTextResult(updated);
+        }
+        catch (error) {
+            return toMcpError(error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@formio/mcp",
+  "version": "0.1.0",
+  "description": "Form.io MCP Server",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/formio/ai#readme",
+  "bugs": {
+    "url": "https://github.com/formio/ai/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formio/ai.git",
+    "directory": "packages/mcp-server"
+  },
+  "main": "./dist/server.js",
+  "bin": {
+    "formio-mcp": "./dist/stdio.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "express": "^4.21.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.19.17",
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:dev": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src && tsc --noEmit",
+    "clean": "rm -rf dist coverage"
+  }
+}