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)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.form%2Fformio--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.form/formio-mcp)
[![Smithery](https://img.shields.io/badge/Smithery-formio%2Fmcp-blue)](https://smithery.ai/servers/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. 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)
  - [How it all works together](#how-it-all-works-together)
  - [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

To get started, open up your Terminal within your application folder, and then use one of the following methods to install this plugin within your application folder.

### Option 1: Skills.sh Installation

```bash
npx skills add formio/ai
```

The command installs the skill library into `.agents/skills/` folder within your application, which every skills-capable agent reads. It installs **skills only** — the Form.io MCP server, which is what gives the agent tools like `form_create`, `form_list`, and `project_import`, is connected on first use by the bundled `formio-mcp-setup` skill: it writes the MCP configuration for your client, asks you to approve it, and tells you to reload.

### Option 2: Agent Plugin Installation

If your agent supports plugins, installing the plugin is an **alternative** to the command above. A plugin install already includes the skills *and* the MCP server:

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

#### Cursor
Plugin installation coming soon

#### Codex
Plugin installation coming soon

#### Copilot
Plugin installation coming soon

### Project Setup <!-- omit from toc -->

Neither install route asks for a URL. Both are resolved per working directory, so one install can serve several projects, and the answer travels with the code rather than with your machine. The first Form.io tool call that needs a project reports what is missing and names the command that supplies it:

```bash
# What does this directory resolve to?
npx -y @formio/mcp@0.14.0 project get --cwd "$(pwd)"

# Record it for this machine…
npx -y @formio/mcp@0.14.0 project set --project-url "<project url>" --cwd "$(pwd)"

# …or commit it with the application, tracked in git and shared with everyone who clones it:
# write a formio.json in the application's own folder (the server reads it, never writes it)
echo '{ "projectUrl": "<project url>" }' > formio.json
```

The skills do this for you: each one calls the `project_get` tool before its first call — over the connection the server already has, not through a shell — and asks only for whichever value the server says is missing. Two values can be involved:

- **Project URL** — the endpoint for your project. On our SaaS environment (https://portal.form.io) that is a sub-domain such as `https://myproject.form.io`. Self-hosted, it depends on how your deployment routes projects: a sub-directory (`https://forms.mysite.com/myproject`) or a sub-domain of your own domain (`https://myproject.mysite.com`).
- **Base URL** — the endpoint for the deployment. On our SaaS environment it is **always** `https://api.form.io` — never your project's `*.form.io` sub-domain. Self-hosted, it is the deployment host, often a sub-domain of your own domain, e.g. `https://forms.mysite.com`.

You usually only supply the first. The Base URL is worked out from the Project URL wherever it can be — `https://api.form.io` for a `*.form.io` project, and the parent path for a sub-directory-routed one. The exception is the sub-domain routing case, where the project host and the deployment host differ by design and neither can be derived from the other; there the server asks for the Base URL explicitly rather than guessing.

Those derivations are also enforced: a `*.form.io` project paired with anything but `https://api.form.io` is refused, because for every project on our SaaS environment that pairing is a mistake that surfaces later as unexplained 404s or a portal login sent to a deployment you do not use. One deployment shape is indistinguishable from that mistake — an internal, non-SaaS deployment served from a `*.form.io` domain, which our QA team tests — so `project set` takes a `--force` flag for it:

```bash
npx -y @formio/mcp@0.14.0 project set --force \
  --project-url "https://myproject.form.io" --base-url "https://api.internal.example" --cwd "$(pwd)"
```

`--force` requires **both** URLs in the same call: it records the pair you state, never one half completed from the record or by derivation. Every check is skipped for that pair — including the ones about a Project URL on its own — so what is recorded is exactly what you type. The pair is then honoured on every later read — `project get` reports it as forced rather than refusing it. It is deliberately a shell-only flag: the `project_set` tool does not take it, so no agent decides to waive a check.

The override belongs to the pair, not to the directory. Re-pointing the directory at a different project drops it and the checks apply again, while a write that leaves both halves untouched keeps it — an agent re-recording the project it already resolved must not undo your decision. That also means re-recording the same pair without `--force` changes nothing, so clearing the record is the way back:

```bash
npx -y @formio/mcp@0.14.0 project set --reset --cwd "$(pwd)"
```

`--reset` removes this directory's entry from `~/.formio/projects.json` — nothing else — and prints what the directory resolves to afterwards, which may still be a committed `formio.json` or the environment. It takes no URLs, exits `0` whenever the record was cleared (run `project get` to see whether the directory is serviceable), and is what every forced report names as the way to put the checks back.

## What you get

- **Agent plugin: `@formio/ai`.** One-command install wherever the agent has a marketplace — Claude Code, Cursor, GitHub Copilot CLI, VS Code, Codex. Bundles the MCP server and the skill library, and each client reads the manifest it understands.
- **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:** Coding agent 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.

### How it all works together

For the full picture — the skills architecture, how the orchestration skills dynamically load the other skills as an agent works through your prompt, how each flow reaches the Form.io Enterprise Server through the MCP server, and Mermaid diagrams of every process flow (building an application, extending one, building a form, embedding a form, changing a project, configuring auth) — read [PROCESS.md](./PROCESS.md).

#