feat(mcp)!: freeze the 1.0 tool surface

[travist]

Why

1.0.0 makes the @formio/mcp tool surface a contract. Before this change it was inconsistent in ways an agent paid for on every call, and parts of it were wrong:

• Tool names mixed singular and plural, and hello reported nothing a caller needed.
• form_update folded four operations behind flags. Publish and revert ignored the required form body, and draft mode refused fields form_get returns.
• Every list stopped at Form.io's default page of 10 without saying so. Revisions came back oldest first, count was the page length, and the multi-tag filter matched nothing.
• Every output schema was closed at the top level, so a client that validates output rejected real Form.io responses (_vid, pdfComponents, esign, settings: null).
• Form writes could stop mid-call for an out-of-band consent prompt (elicitation, or a local browser page).
• Errors were prose only, and Form.io's response body was dropped.
• tools/list cost ~68.5k characters.

What changes — BREAKING for any client calling the tools directly

• Renames: action_types_list → action_type_list, form_revisions_list → form_revision_list, hello → server_status. server_status returns the server name and version plus the cwd's project resolution, without making a Form.io request. The old names are not registered.
• form_publish / form_revert are now separate tools. form_update keeps the full update and draft: true. Draft mode saves the draft fields of the body it is given, so form_get's output can be passed back.
• Form addressing: formId is always a 24-character ObjectId. formIdOrPath accepts either form and is used by form_get, form_revision_list and form_revision_get. These follow the routes Form.io resolves by path: the action-type catalog route does not resolve a path.
• role_create takes a nested role object, like role_update.
• List contract:
  • Arguments: limit (default 100), skip, sort, select.
  • Results: total and hasMore, read from Content-Range. A full page with an unknown total reports hasMore: true.
  • Behaviour: count is removed; a skip past the end returns an empty page; tags match all of the given tags; form_revision_list is newest first and excludes the unpublished draft row.
• acceptNoHistory replaces the consent prompts. A write that would save without revision history needs acceptNoHistory: true, otherwise it is refused with HISTORY_NOT_ACCEPTED so the agent can ask the user. That covers three cases: an unlicensed deployment, a form with revisions off, or an explicit revisions: "". The elicitation path, the local browser consent pages and the persisted consent file are removed. The licence probe has three states. Only a definite answer is cached, and an undetermined licence never strips history.
• Errors: every tool error's text starts with [CODE] from a fixed set, and the result carries { code, status?, body? } in _meta["io.form/error"]. Error results carry no structuredContent, because clients validate it against the tool's success schema even when isError is set. Text after the prefix is unchanged, so the error part is additive.
• Output schemas are open at every level, and Mixed Form.io fields accept null.
• Description budget: tools/list is ~37.6k characters (from ~68.5k), under a tested 42,000 budget. The cwd description is 82 characters; output schemas describe only the fields callers branch on (status, total, hasMore, remedy, ok) and declare only the document fields callers act on — they stay open, so every other Form.io field passes through; nested Form.io body fields are documented by the skills; project_set states only the rules it enforces.
• cwd comes from the client. A call without cwd resolves its project for the client's workspace root (MCP roots/list; one root as is, several narrowed to the one holding a project record, ambiguous ones refused with INVALID_ARGUMENT), then CLAUDE_PROJECT_DIR, then the server's own directory — all through the one resolver project get uses. project_get / server_status report cwdSource; only a guessed directory tells the agent to pass cwd. Roots are cached, re-read on roots/list_changed, keep the last good list on a failed re-read, and time out after 2s. cwd stays optional; the skills' preflight calls project_get without it.
• FORMIO_INSECURE_TLS and FORMIO_FORCE_BROWSER share one boolean parser.
• @formio/mcp exports only ./package.json; the package is its formio-mcp binary.
• The CLI's flags and exit codes are documented as the 1.0 reference, unchanged.
• Skills and READMEs follow the surface: the preflight paragraph in all 14 gated skills, the formio-actions and formio-api references, and the role_create examples. The server README gains a conventions section and a CLI reference.

~/.formio/projects.json keeps its current format. That was decided during the proposal, because renaming its keys would need a migration or break existing mappings.

Verification

• pnpm test: @formio/mcp 1543, @formio/skill-tests 1273. pnpm lint, pnpm format, pnpm check:releases and openspec validate --strict also pass.
• New guards:
  • every registered tool is driven into an error, and the result must carry a [CODE];
  • every output schema is open;
  • realistic Form.io documents replay through a validating client;
  • the tools/list size budget;
  • skill text must not name retired tools, flat role_create fields, list count, or the consent prompt;
  • the preflight list of writing tools is complete.
• Checked live against a Form.io Enterprise deployment: sort=-_vid puts the draft revision first, _vid__ne=draft removes it, and Content-Range reports the reduced total, including on a 206 partial page.
• Independent code reviews were run on the branch (10 findings, resolved in b82b707), on this PR (10 findings, resolved in bdd5804), and on the cwd change (9 resolved in 54076dc, 1 declined).

Release note

This carries a major changeset for @formio/mcp and @formio/ai. Merging it does not publish anything. Hold the Version Packages PR until the remaining 1.0 changes land (auth and error hardening, local state and release, skill corrections, routing, planner delta mode, drift guards). Merging the Version Packages PR before then would release 1.0.0 early.

Known follow-ups, not in this PR:

• the MCP Inspector screenshot in the server README still shows hello;
• the .mcpb bundle reports version 0.0.0 (this predates the branch);
• plugin/README.md's environment-fallback sentence.

OpenSpec change: openspec/changes/freeze-1-0-tool-surface/.

🤖 Generated with Claude Code