@formio/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,146 @@
+## Formio MCP server
+
+The MCP server (`@formio/mcp`) is independently usable from any MCP-aware client. From a clone of this repo:
+
+```bash
+pnpm install
+pnpm --filter @formio/mcp dev
+```
+
+The server starts on port 3000. Override with the `PORT` env var.
+
+### Transports
+
+| Transport | Endpoint | Compatible with |
+| --- | --- | --- |
+| Streamable HTTP | `POST /mcp` | Claude Code, VS Copilot, modern MCP clients |
+| SSE | `GET /sse` + `POST /messages` | Claude Desktop, legacy MCP clients |
+| stdio | `node dist/stdio.js` | `.mcp.json` spawn-mode clients |
+
+### Connect to Claude Code
+
+```json
+{
+  "mcpServers": {
+    "formio-mcp": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+### Connect to Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "formio-mcp": {
+      "url": "http://localhost:3000/sse"
+    }
+  }
+}
+```
+
+### Spawn via `.mcp.json` (stdio)
+
+```json
+{
+  "mcpServers": {
+    "formio-mcp": {
+      "command": "npx",
+      "args": ["-y", "@formio/mcp"],
+      "env": {
+        "FORMIO_BASE_URL": "https://api.form.io",
+        "FORMIO_PROJECT_URL": "https://your-project.form.io"
+      }
+    }
+  }
+}
+```
+
+In standalone (non-plugin) mode, `FORMIO_BASE_URL` and `FORMIO_PROJECT_URL` are required env vars. In plugin mode, the plugin manages both via Claude Code's user-config + per-cwd `~/.formio/projects.json` mapping.
+
+---
+
+## MCP server tools
+
+The bundled `@formio/mcp` server exposes these tools. Skills prefer these over raw HTTP whenever an operation is covered.
+
+### Forms
+
+| Tool | Purpose |
+| --- | --- |
+| `form_create` | Create a new form. Use the `formio-form` skill first to build the JSON definition. |
+| `form_get` | Fetch a single form definition by ID or path. |
+| `form_list` | List forms with optional filtering and pagination. |
+| `form_update` | Update an existing form. Call `form_get` first, edit with `formio-form`, then update. |
+
+### Roles
+
+| Tool | Purpose |
+| --- | --- |
+| `role_create` | Create a new project role. |
+| `role_list` | List all project roles. |
+| `role_update` | Full-replacement update of a role. Include all fields you want preserved. |
+
+### Actions
+
+| Tool | Purpose |
+| --- | --- |
+| `action_types_list` | List all action types available on the server. |
+| `action_type_get` | Get an action type's settings schema. |
+| `action_create` | Attach a new action to a form. |
+| `action_list` | List actions on a form. |
+| `action_get` | Get a single action by ID. |
+| `action_update` | Update an action. |
+| `action_delete` | Detach an action from a form. |
+
+### Project
+
+| Tool | Purpose |
+| --- | --- |
+| `project_export` | Export the project's complete template (roles, resources, forms, actions) as a portable JSON document. Use before `project_import` to snapshot. |
+| `project_import` | Import a template JSON — additively merges roles, resources, forms, and actions in one call. **Same-machine-name items are overwritten in place; everything else is preserved.** |
+| `project_set` | Plugin-mode only — persist a per-cwd Project URL mapping in `~/.formio/projects.json`. Never exposed standalone (the standalone server binds to `FORMIO_PROJECT_URL` via env instead). |
+
+### Diagnostic
+
+| Tool | Purpose |
+| --- | --- |
+| `hello` | Smoke-test tool. Returns a static greeting; useful for verifying MCP wiring before any authenticated call. |
+
+---
+
+## Authentication
+
+The MCP server supports two authentication modes:
+
+- **JWT mode (default).** A short-lived local Express server renders the Form.io portal login form; the user signs in once, the JWT comes back via a `/callback` endpoint, and `formioFetch` attaches `x-jwt-token` on every subsequent request. The flow is implicit — the **first authenticated tool call** triggers it on a cache miss. No explicit `authenticate` tool exists.
+- **API-key mode.** Set `FORMIO_API_KEY`. All requests attach `x-token`; the browser flow is skipped entirely.
+
+### Login-form auto-resolution
+
+When `FORMIO_LOGIN_FORM` is unset, the server probes these candidates on the first login attempt and caches the first one that responds (1.5-second timeout per candidate):
+
+1. `${FORMIO_BASE_URL}/formio/user/login` (portal-base)
+2. `${FORMIO_PROJECT_URL}/admin/login` (project admin)
+3. `${FORMIO_PROJECT_URL}/user/login` (project user)
+
+The probe runs lazily — only when the local auth page is actually served.
+
+---
+
+## Environment variables
+
+| Name | Required | Default | Purpose | Hosted SaaS example | Self-hosted example |
+| --- | :-: | --- | --- | --- | --- |
+| `FORMIO_BASE_URL` | yes | — | Full base URL of your Form.io deployment. | `https://api.form.io` | `https://forms.example.com` |
+| `FORMIO_PROJECT_URL` | yes\* | — | Full URL of your Form.io project. In plugin mode, only used as the pre-filled default offered when prompting for an unmapped cwd. | `https://myproject.form.io` | `https://forms.example.com/myproject` |
+| `FORMIO_API_KEY` | no | `undefined` | Long-lived project API key. When set, the server skips the browser login flow. | `CHANGEME` | `CHANGEME` |
+| `FORMIO_LOGIN_FORM` | no | Auto-resolved | Override the portal login form URL used by the JWT login flow. | `https://formio.form.io/user/login` | `https://forms.example.com/formio/user/login` |
+| `FORMIO_PLUGIN_CONTEXT` | no | `0` | Set by the plugin manifest. When `1`, the server enables `project_set` and reads `FORMIO_PROJECT_URL` from `~/.formio/projects.json` per cwd instead of env. |  |  |
+
+\* In plugin context, `FORMIO_PROJECT_URL` is captured per-cwd by the `project_set` tool and persisted to `~/.formio/projects.json`. The `verify-project-url` `SessionStart`/`PreToolUse` hook offers `formio_default_project_url` (from plugin user-config) as the default the first time you enter a workspace.

package/dist/auth-header.d.ts

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

package/dist/auth-header.js

@@ -0,0 +1,9 @@
+export function getAuthHeader(config) {
+    if (config.jwt) {
+        return { 'x-jwt-token': config.jwt };
+    }
+    if (config.apiKey) {
+        return { 'x-token': config.apiKey };
+    }
+    return {};
+}

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import { ResolvedFormioConfig } from './config.js';
+export interface AuthenticateOptions {
+    onReady?: (port: number) => void;
+}
+export declare function resetLoginFormCache(): void;
+export declare function authenticate(config: ResolvedFormioConfig, options?: AuthenticateOptions): Promise<string>;

package/dist/auth.js

@@ -0,0 +1,148 @@
+import express from 'express';
+import { exec } from 'child_process';
+import { formioRawFetch } from './formio-client.js';
+function buildLoginPage(loginFormUrl) {
+    const domain = new URL(loginFormUrl).hostname;
+    return `<!DOCTYPE html>
+<html>
+<head>
+<title>Form.IO Login</title>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,400italic,700">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap/dist/css/bootstrap.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons/font/bootstrap-icons.css">
+<link rel="stylesheet" href="https://cdn.form.io/js/5.2.2/formio.full.min.css">
+<style>
+  body { font-family: 'Open Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif; background: #fff; margin: 0; padding: 2rem 1rem; color: #333; }
+  .logo-wrap { text-align: center; margin-bottom: 1rem; }
+  .logo-wrap img { max-width: 300px; height: auto; }
+  .page-title { text-align: center; margin-bottom: 2rem; font-weight: 300; color: #333; }
+  .auth-card { max-width: 480px; margin: 0 auto; background: #fff; padding: 2rem; border: 1px solid #e5e5e5; border-radius: 4px; box-shadow: 0 2px 4px rgba(0,0,0,0.05); }
+  .auth-title { text-align: center; margin-bottom: 1.5rem; font-size: 1.1rem; letter-spacing: 0.5px; color: #555; }
+  .btn-primary, .btn-success { background-color: #67b346; border-color: #67b346; }
+  .btn-primary:hover, .btn-success:hover { background-color: #57a036; border-color: #57a036; }
+  #status { text-align: center; margin-top: 1rem; color: #666; font-size: 0.9rem; }
+</style>
+</head>
+<body>
+<div class="logo-wrap">
+  <img src="https://portal.form.io/template/images/formio-logo-with-slogan.png" alt="Form.io">
+</div>
+<h2 class="page-title">Logging in to ${domain}</h2>
+<div class="auth-card">
+  <h4 class="auth-title">RETURNING USER LOGIN</h4>
+  <div id="formio"></div>
+  <div id="status"></div>
+</div>
+<script src="https://cdn.form.io/js/5.2.2/formio.form.min.js"></script>
+<script>
+var statusEl = document.getElementById('status');
+Formio.createForm(document.getElementById('formio'), '${loginFormUrl}').then(function(form) {
+  form.on('submit', function(submission) {
+    var token = Formio.getToken();
+    statusEl.innerHTML = token ? 'Token captured, completing login...' : 'Error: No token received from Form.io SDK';
+    if (!token) return;
+    fetch('/callback', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token: token })
+    }).then(function() {
+      statusEl.innerHTML = 'Login successful. You can close this tab.';
+    }).catch(function(err) {
+      statusEl.innerHTML = 'Error sending token: ' + err.message;
+    });
+  });
+}).catch(function(err) {
+  statusEl.innerHTML = 'Error loading form: ' + err.message;
+});
+</script>
+</body>
+</html>`;
+}
+const LOGIN_FORM_PROBE_TIMEOUT_MS = 1500;
+const resolvedLoginFormCache = new Map();
+function loginFormCacheKey(config) {
+    return `${config.baseUrl ?? ''}|${config.projectUrl}`;
+}
+export function resetLoginFormCache() {
+    resolvedLoginFormCache.clear();
+}
+async function checkLoginForm(loginFormUrl, config) {
+    const url = new URL(loginFormUrl);
+    url.searchParams.set('select', '_id');
+    const loginForm = await formioRawFetch(url, config, {
+        signal: AbortSignal.timeout(LOGIN_FORM_PROBE_TIMEOUT_MS),
+    }).catch(() => null);
+    return loginForm?._id ? true : false;
+}
+async function resolveDefaultLoginFormUrl(config) {
+    const cacheKey = loginFormCacheKey(config);
+    const cached = resolvedLoginFormCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const candidates = [];
+    if (config.baseUrl) {
+        candidates.push(`${config.baseUrl}/formio/user/login`);
+    }
+    candidates.push(`${config.projectUrl}/admin/login`);
+    candidates.push(`${config.projectUrl}/user/login`);
+    for (const candidate of candidates) {
+        if (await checkLoginForm(candidate, config)) {
+            resolvedLoginFormCache.set(cacheKey, candidate);
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+export async function authenticate(config, options) {
+    const app = express();
+    app.use(express.json());
+    let resolveJwt;
+    let rejectJwt;
+    const jwtPromise = new Promise((resolve, reject) => {
+        resolveJwt = resolve;
+        rejectJwt = reject;
+    });
+    app.get('/', async (_req, res) => {
+        try {
+            const loginFormUrl = config.loginFormUrl ?? (await resolveDefaultLoginFormUrl(config));
+            res.send(buildLoginPage(loginFormUrl));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            res.status(500).send(`Login form resolution failed: ${message}`);
+            rejectJwt(err instanceof Error ? err : new Error(message));
+        }
+    });
+    app.post('/callback', (req, res) => {
+        const token = req.body.token;
+        if (!token) {
+            process.stderr.write('Auth callback received but token is empty\n');
+            res.status(400).send('No token received');
+            return;
+        }
+        process.stderr.write('Auth callback received token successfully\n');
+        res.send('Login successful. You can close this tab.');
+        resolveJwt(token);
+    });
+    const server = app.listen(0, '127.0.0.1', () => {
+        const addr = server.address();
+        if (addr && typeof addr !== 'string') {
+            const port = addr.port;
+            const loginUrl = `http://127.0.0.1:${port}/`;
+            const openCmd = process.platform === 'darwin'
+                ? 'open'
+                : process.platform === 'win32'
+                    ? 'start'
+                    : 'xdg-open';
+            exec(`${openCmd} "${loginUrl}"`);
+            options?.onReady?.(port);
+        }
+    });
+    try {
+        return await jwtPromise;
+    }
+    finally {
+        server.close();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export interface FormioConfig {
+    baseUrl?: string;
+    projectUrl?: string;
+    apiKey?: string;
+    loginFormUrl?: string;
+    jwt?: string;
+}
+export interface ResolvedFormioConfig extends FormioConfig {
+    baseUrl: string;
+    projectUrl: string;
+}
+export declare function getConfig(): FormioConfig;

package/dist/config.js

@@ -0,0 +1,29 @@
+export function getConfig() {
+    const apiKey = process.env.FORMIO_API_KEY;
+    const loginFormUrl = process.env.FORMIO_LOGIN_FORM;
+    // Standalone-use fallback: when the server is launched outside the plugin
+    // (e.g. via .mcp.json), FORMIO_PROJECT_URL lets users skip project_set
+    // entirely. Plugin context leaves this unset — the SessionStart hook
+    // drives per-cwd project_set instead.
+    const pluginContext = process.env.FORMIO_PLUGIN_CONTEXT === '1';
+    // Plugin always collects FORMIO_BASE_URL via user-config, so require it
+    // there. Standalone falls back to the hosted cloud default.
+    const baseUrl = pluginContext
+        ? process.env.FORMIO_BASE_URL
+        : process.env.FORMIO_BASE_URL || 'https://api.form.io';
+    if (!baseUrl) {
+        throw new Error('FORMIO_BASE_URL is required');
+    }
+    // standalone mcp server (outside of claude plugin) needs to set project url from process.env
+    const projectUrl = pluginContext ? null : process.env.FORMIO_PROJECT_URL;
+    if (!projectUrl && !pluginContext) {
+        throw new Error('FORMIO_PROJECT_URL is required');
+    }
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        projectUrl: projectUrl?.replace(/\/+$/, ''),
+        apiKey: apiKey || undefined,
+        loginFormUrl: loginFormUrl || undefined,
+        jwt: undefined,
+    };
+}

package/dist/ensure-auth.d.ts

@@ -0,0 +1,4 @@
+import { ResolvedFormioConfig } from './config.js';
+export declare function ensureAuthenticated(config: ResolvedFormioConfig): Promise<void>;
+export declare function resetAuthState(): void;
+export declare function invalidateJwtCache(baseUrl: string): void;

package/dist/ensure-auth.js

@@ -0,0 +1,56 @@
+import { readToken, saveToken, clearToken } from './token-cache.js';
+import { validateToken } from './token-validation.js';
+import { authenticate } from './auth.js';
+// Keyed by baseUrl: one JWT is valid for every project on the same Form.io
+// deployment, so caching per-project would over-partition.
+const jwtCache = new Map();
+const pendingAuthByBaseUrl = new Map();
+async function runAuthFlow(config) {
+    // API key mode: tool calls themselves will validate the key
+    if (config.apiKey) {
+        return;
+    }
+    // JWT mode: check cache
+    const cachedToken = await readToken(config.baseUrl);
+    if (cachedToken) {
+        config.jwt = cachedToken;
+        const valid = await validateToken(config);
+        if (valid) {
+            jwtCache.set(config.baseUrl, cachedToken);
+            return;
+        }
+        // Expired — clear and re-auth
+        await clearToken(config.baseUrl);
+        config.jwt = undefined;
+    }
+    // No valid token — login
+    const jwt = await authenticate(config);
+    config.jwt = jwt;
+    await saveToken(config.baseUrl, jwt);
+    jwtCache.set(config.baseUrl, jwt);
+}
+export async function ensureAuthenticated(config) {
+    // Short-circuit: already authenticated in this process
+    const cached = jwtCache.get(config.baseUrl);
+    if (cached) {
+        config.jwt = cached;
+        return;
+    }
+    // Single-flight per baseUrl: reuse an in-flight auth promise if one exists
+    const existing = pendingAuthByBaseUrl.get(config.baseUrl);
+    if (existing) {
+        return existing;
+    }
+    const pending = runAuthFlow(config).finally(() => {
+        pendingAuthByBaseUrl.delete(config.baseUrl);
+    });
+    pendingAuthByBaseUrl.set(config.baseUrl, pending);
+    return pending;
+}
+export function resetAuthState() {
+    jwtCache.clear();
+    pendingAuthByBaseUrl.clear();
+}
+export function invalidateJwtCache(baseUrl) {
+    jwtCache.delete(baseUrl);
+}

package/dist/formio-client.d.ts

@@ -0,0 +1,11 @@
+import { ResolvedFormioConfig } from './config.js';
+export declare const MONGO_ID_PATTERN: RegExp;
+export declare function isMongoId(value: string): boolean;
+export interface FormioFetchOptions {
+    method?: string;
+    body?: unknown;
+    responseType?: 'text' | 'json';
+    signal?: AbortSignal;
+}
+export declare function formioRawFetch(url: URL, config: ResolvedFormioConfig, options?: FormioFetchOptions): Promise<unknown>;
+export declare function formioFetch(path: string, params: Record<string, string | undefined>, config: ResolvedFormioConfig, options?: FormioFetchOptions): Promise<unknown>;

package/dist/formio-client.js

@@ -0,0 +1,60 @@
+import { getAuthHeader } from './auth-header.js';
+import { ensureAuthenticated, invalidateJwtCache } from './ensure-auth.js';
+import { clearToken } from './token-cache.js';
+if (process.env.FORMIO_INSECURE_TLS === 'true') {
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+}
+export const MONGO_ID_PATTERN = /^[0-9a-fA-F]{24}$/;
+export function isMongoId(value) {
+    return MONGO_ID_PATTERN.test(value);
+}
+function formatApiError(status, url) {
+    return `Form.io API error: ${status} | URL: ${url.toString()}`;
+}
+function buildFetchInit(config, options) {
+    const hasBody = options?.body !== undefined;
+    const headers = {
+        ...getAuthHeader(config),
+        ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+    };
+    const init = { headers };
+    if (options?.method) {
+        init.method = options.method;
+    }
+    if (hasBody) {
+        init.body = JSON.stringify(options.body);
+    }
+    if (options?.signal) {
+        init.signal = options.signal;
+    }
+    return init;
+}
+export async function formioRawFetch(url, config, options) {
+    const response = await fetch(url, buildFetchInit(config, options));
+    const parseResponse = (res) => options?.responseType === 'text' ? res.text() : res.json();
+    if (!response.ok) {
+        if (response.status === 401 && config.jwt) {
+            invalidateJwtCache(config.baseUrl);
+            await clearToken(config.baseUrl);
+            config.jwt = undefined;
+            await ensureAuthenticated(config);
+            const retryResponse = await fetch(url, buildFetchInit(config, options));
+            if (!retryResponse.ok) {
+                throw new Error(formatApiError(retryResponse.status, url));
+            }
+            return parseResponse(retryResponse);
+        }
+        throw new Error(formatApiError(response.status, url));
+    }
+    return parseResponse(response);
+}
+export async function formioFetch(path, params, config, options) {
+    await ensureAuthenticated(config);
+    const base = config.projectUrl.replace(/\/*$/, '/');
+    const url = new URL(path.replace(/^\//, ''), base);
+    const entries = Object.entries(params).filter((entry) => entry[1] !== undefined);
+    for (const [key, value] of entries) {
+        url.searchParams.set(key, value);
+    }
+    return formioRawFetch(url, config, options);
+}

package/dist/mcp-responses.d.ts

@@ -0,0 +1,13 @@
+export declare function toMcpTextResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toMcpError(error: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/mcp-responses.js

@@ -0,0 +1,12 @@
+export function toMcpTextResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function toMcpError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}

package/dist/project-map.d.ts

@@ -0,0 +1,5 @@
+export interface ProjectEntry {
+    env: Record<string, string>;
+}
+export declare function readProjectEntry(cwd: string, cacheDir?: string): ProjectEntry | null;
+export declare function writeProjectEntry(cwd: string, env: Record<string, string>, cacheDir?: string): void;

package/dist/project-map.js

@@ -0,0 +1,29 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), '.formio');
+const PROJECTS_FILE = 'projects.json';
+function readMap(cacheDir) {
+    const filePath = path.join(cacheDir, PROJECTS_FILE);
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeMap(cacheDir, data) {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    fs.writeFileSync(path.join(cacheDir, PROJECTS_FILE), JSON.stringify(data), {
+        mode: 0o600,
+    });
+}
+export function readProjectEntry(cwd, cacheDir = DEFAULT_CACHE_DIR) {
+    const map = readMap(cacheDir);
+    return map[cwd] ?? null;
+}
+export function writeProjectEntry(cwd, env, cacheDir = DEFAULT_CACHE_DIR) {
+    const map = readMap(cacheDir);
+    map[cwd] = { env };
+    writeMap(cacheDir, map);
+}

package/dist/project-resolver.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import { FormioConfig, ResolvedFormioConfig } from './config.js';
+export declare const cwdSchema: z.ZodString;
+export declare function resolveProjectConfig(cwd: string, baseConfig: FormioConfig): ResolvedFormioConfig;

package/dist/project-resolver.js

@@ -0,0 +1,35 @@
+import path from 'path';
+import { z } from 'zod';
+import { readProjectEntry } from './project-map.js';
+export const cwdSchema = z
+    .string()
+    .min(1, 'cwd is required')
+    .refine((value) => path.isAbsolute(value), {
+    message: 'cwd must be an absolute path',
+})
+    .describe("User's current working directory as an absolute path. Required — the tool looks up the mapped Form.io project from ~/.formio/projects.json[cwd]. Call project_set first if the cwd is not yet mapped.");
+export function resolveProjectConfig(cwd, baseConfig) {
+    if (typeof cwd !== 'string' || cwd.length === 0) {
+        throw new Error('cwd is required and must be a non-empty string.');
+    }
+    if (!path.isAbsolute(cwd)) {
+        throw new Error(`cwd must be an absolute path (received: ${cwd}).`);
+    }
+    // Plugin context: the hook drives per-cwd project_set, so the map is
+    // authoritative. Standalone context: the map is at best stale leftover from
+    // prior plugin use in this cwd — ignore it so the user's .mcp.json env wins.
+    const pluginContext = process.env.FORMIO_PLUGIN_CONTEXT === '1';
+    const mapped = pluginContext ? readProjectEntry(cwd)?.env.FORMIO_PROJECT_URL : undefined;
+    const projectUrl = mapped ?? baseConfig.projectUrl;
+    if (!projectUrl) {
+        throw new Error(`No Form.io project is mapped for cwd=${cwd}. Call project_set with projectUrl and cwd=${cwd}, or set the FORMIO_PROJECT_URL environment variable, before invoking Form.io tools.`);
+    }
+    if (!baseConfig.baseUrl) {
+        throw new Error('baseUrl is missing on config. getConfig() should always populate it.');
+    }
+    return {
+        ...baseConfig,
+        baseUrl: baseConfig.baseUrl,
+        projectUrl: projectUrl.replace(/\/+$/, ''),
+    };
+}

package/dist/server.d.ts

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

package/dist/server.js

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getConfig } from './config.js';
+import { registerAllTools } from './tools/index.js';
+export function createServer(config) {
+    const resolvedConfig = config ?? getConfig();
+    const server = new McpServer({ name: 'formio-mcp', version: '0.1.0' });
+    registerAllTools(server, resolvedConfig);
+    return server;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getConfig } from './config.js';
+import { createServer } from './server.js';
+const config = getConfig();
+const server = createServer(config);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/token-cache.d.ts

@@ -0,0 +1,3 @@
+export declare function saveToken(baseUrl: string, jwt: string, cacheDir?: string): Promise<void>;
+export declare function readToken(baseUrl: string, cacheDir?: string): Promise<string | null>;
+export declare function clearToken(baseUrl: string, cacheDir?: string): Promise<void>;