ai

# The Form.io Agentic Coding Toolset <!-- omit from toc -->

[![CI](https://github.com/formio/ai/actions/workflows/ci.yml/badge.svg)](https://github.com/formio/ai/actions/workflows/ci.yml)
[![npm: @formio/ai](https://img.shields.io/npm/v/%40formio%2Fai?label=%40formio%2Fai)](https://www.npmjs.com/package/@formio/ai)
[![npm: @formio/mcp](https://img.shields.io/npm/v/%40formio%2Fmcp?label=%40formio%2Fmcp)](https://www.npmjs.com/package/@formio/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

`@formio/ai` is what brings Form.io into your agentic coding environment. It provides a series of tools that enable any developer to perform a number of complex actions against the Form.io Enterprise Server using their favorite Agentic Coding toolsets (starting with Claude Code). This turns the Form.io Enterprise Server into a **Composable Backend for Agentically Coded Applications**.

- [Getting Started](#getting-started)
- [What you get](#what-you-get)
- [Why this exists](#why-this-exists)
- [Agentic Skill Library](#agentic-skill-library)
  - [Orchestration skills](#orchestration-skills)
  - [All skills](#all-skills)
- [Examples and Use Cases](#examples-and-use-cases)
  - [Build complete applications](#build-complete-applications)
  - [Build forms and wizards](#build-forms-and-wizards)
  - [Embed forms in existing applications](#embed-forms-in-existing-applications)
  - [Work the REST API via prompt](#work-the-rest-api-via-prompt)
- [Using the MCP server without the skills](#using-the-mcp-server-without-the-skills)
- [MCP server tools](#mcp-server-tools)
  - [Forms](#forms)
  - [Roles](#roles)
  - [Actions](#actions)
  - [Project](#project)
  - [Diagnostic](#diagnostic)
- [Authentication](#authentication)
  - [Login-form auto-resolution](#login-form-auto-resolution)
- [Environment variables](#environment-variables)
- [Contributing](#contributing)
- [License](#license)

## Getting Started
Getting started is easy.  First install Claude Code as follows:

 1. [Install Claude Code](https://github.com/anthropics/claude-code#get-started)
 2. Run `claude` in your Terminal.
 3. Run the following command within **Claude Code**.

```bash
/plugin marketplace add https://github.com/formio/ai.git
/plugin install formio-ai@formio
```

Claude Code prompts for the `Project URL` and the `Base URL` on install. These are described as follows:

 - **Project URL**: This is the endpoint for your 'project'. If you are using our SaaS environment (https://portal.form.io), then your project URL will be a sub-domain, such as https://myproject.form.io. However, for most use cases, when Form.io is deployed in your own environment, then the project url is typically a 'sub-directory' structure like https://forms.mysite.com/myproject.
 - **Base URL**: This is the endpoint for the deployment. If you are using the SaaS environment (https://portal.form.io), then this is always going to be https://api.form.io. However, for most use cases, when Form.io is deployed in your own environment, then this is the URL of the deployment like https://forms.mysite.com.

## What you get

- **Claude Code plugin: `@formio/ai`.** One-command install. Bundles the MCP server and skill library, registers them with Claude Code.
- **MCP server: `@formio/mcp`.** Form.io operations (`form_*`, `role_*`, `action_*`, `project_*`) as MCP tools. Works with any MCP-aware client: Claude Code, Claude Desktop, VS Copilot, and whatever comes next.
- **Skills library:** Ten activatable skills covering app orchestration, form building (webforms and wizards), form embedding, resource planning, JSON-schema authoring, action configuration, authentication & authorization, the `@formio/js` SDK surface, and the full Form.io REST surface.

## Why this exists

Form.io has been the data standardization layer for enterprise data for a decade. With the proliferation of AI coding agents, that standardization matters more, not less.

**Build on the Form.io platform, not from scratch.** The agent builds complete applications including the data models, forms, workflows, and business logic. Form.io is the platform it builds on. The APIs, data patterns, RBAC, audit infrastructure, and form management capabilities are production-grade and already there. The agent uses them as tools to build applications better.

**Standardization across every AI-built app.** One model, one set of rules, one audit trail, regardless of which team or which agent built it. With a standardization layer, multiple teams ship multiple applications, all with defensible, reconcilable data layers across the enterprise.

**Governance built in.** RBAC, group permissions, change history, audit trails — all emitted on the first pass. Every app lands inside the same compliance envelope the enterprise already runs on.

## Agentic Skill Library

The plugin ships an activatable skill library. Claude loads the relevant skill on demand based on what you ask — you rarely need to name one explicitly.

### Orchestration skills

Orchestration skills are special skills that serve as the **entry point** for most prompts. Rather than covering a single capability, they coordinate the other skills (planning, schema authoring, actions, deployment, framework scaffolding) to fulfill a broad, plain-language request end to end. When you describe *what you want* instead of *which tool to use*, an orchestration skill picks it up and drives the whole pipeline.

| Skill | What it does |
| --- | --- |
| `formio-application` | Framework-agnostic "build me an app" orchestrator. Turns plain-language intent into a running application backed by a Form.io project — planning resources, importing the template, and handing off to a framework implementor. Also handles adding new features to an existing app. |
| `formio-form-builder` | "Build me a form" orchestrator. Builds a single form end to end — webform or multi-page wizard — from intent through schema authoring to a saved form in your deployment, with an optional embed handoff. Also handles field edits to an existing form. |

### All skills

| Skill | What it does |
| --- | --- |
| `formio-application` | Orchestration entry point for building or extending an application on the Form.io platform (see above). |
| `formio-form-builder` | Orchestration entry point for building a single form — webform or wizard — end to end (see above). |
| `formio-form` | Embeds and renders Form.io forms in any web application with the `@formio/js` renderer — pre-fill, conditional fields, calculated values, custom validation, and conditional wizard pages. |
| `formio-resource-planner` | Plans the resource structure, field configuration, and access/permission model from high-level requirements, then emits a ready-to-import `template.json`. |
| `formio-schema` | Reference for Form.io JSON schema — the document shapes for projects, forms/resources, and submissions. Used when constructing, editing, or interpreting any Form.io JSON. |
| `formio-actions` | Reference for configuring Form.io actions — the server-side behavior layer for email notifications, authentication, webhooks, role assignment, and form-to-form saves. |
| `formio-auth` | Authentication and authorization specialist — login/registration, RBAC, SSO (OIDC/SAML/LDAP), Token Swap, Custom JWT, passwordless email tokens, and JWT/session mechanics. |
| `formio-api` | Comprehensive Form.io REST API reference — every endpoint across platform admin, project admin, runtime, and PDF scopes. |
| `formio-sdk` | Reference for the `@formio/js` JavaScript SDK and `@formio/js/utils` Utilities — static and instance methods, VanillaJS rendering, plugins, and helpers. |
| `formio-angular` | Angular framework implementor. Turns an approved `template.json` plus a target project into a working Angular app using `@formio/angular`. Delegated to by `formio-application`. |

## Examples and Use Cases

Ready-to-paste example prompts live in [`examples/`](./examples/) — each file is one self-contained prompt plus notes on what it should exercise. To try one, create a new folder, start Claude Code inside it, and paste the prompt:

```bash
mkdir form-app
cd form-app
claude
```

### Build complete applications

Create a brand-new 'greenfield' form-based application — or introduce a new form-based feature within an existing one — using the `formio-application` orchestration skill. The agent plans the data model, imports it into your Form.io project, and scaffolds the front end, using the Form.io platform as the composable backend for the full application logic.

- [CRM Application](./examples/apps/crm.md) — clients, deals, and activity logs with owner-scoped access.
- [Help Desk](./examples/apps/help-desk.md) — customer tickets, agent workflows, internal notes, and email notifications.
- [Storyboard](./examples/apps/storyboard.md) — production → scene → shot hierarchy with collaborative crew access.

***This library currently only supports the Angular application framework for new 'greenfield' applications. It generally supports other frameworks using the Vanilla JS `@formio/js` javascript renderer. Full support for other frameworks are coming soon.***

### Build forms and wizards

Create complex forms and multi-page conditional wizards with the `formio-form-builder` skill. The agent authors the form JSON and automatically creates the form within any stage of your deployment — including forms whose submission data must adhere to well-defined external schemas such as [FHIR](https://hl7.org/fhir).

- [College Application Wizard](./examples/forms/college-application.md) — multi-page wizard with program-driven conditional pages.
- [FHIR-Compliant Patient Form](./examples/forms/fhir-patient.md) — submission data that conforms to the FHIR Patient resource.
- [Customer Feedback Form](./examples/forms/customer-feedback.md) — conditional follow-up fields and a conditional email notification.
- [Student Onboarding Wizard](./examples/forms/student-onboarding-embed.md) — create a wizard and e