Beautiful Open-Source Form Builder
fix: keep MCP form creation guest-first (#1267)
Julien Nahum519c097f305d
diff --git a/api/app/Mcp/Servers/OpnFormServer.php b/api/app/Mcp/Servers/OpnFormServer.phpindex 2ea1e330e..aa6a4ee4c 100644--- a/api/app/Mcp/Servers/OpnFormServer.php+++ b/api/app/Mcp/Servers/OpnFormServer.php@@ -33,7 +33,7 @@ use Laravel\Mcp\Server\Attributes\Version;#[Name('OpnForm')]#[Version('1.0.0')]-#[Instructions('Use OpnForm MCP tools directly. Never invoke Codex or ChatGPT recursively, run `codex exec`, use shell or raw HTTP, inspect repositories or caches, or switch connectors. If the tools required for the active workflow are unexpectedly missing, stop and ask the user to start a new conversation with OpnForm selected before the first message. All account, form, and submission tools require OAuth. Enabling the plugin is not OAuth authentication. In local Codex, start a new conversation after OAuth so the MCP client loads the stored credential. When guest draft tools are available, they need no login. When they are unavailable, authenticate and use create_form to save an unpublished draft in a writable workspace. If an account tool challenges, ask the user to authenticate the OpnForm MCP server in the host; do not repeatedly retry from the guest conversation. Read the schema and field catalog before generating a form or changing its presentation, fields, layout, or media, then validate before saving. Focused presentation creates one step per block automatically: use full-width blocks, no page breaks or standalone media blocks, and attach optional media through the block image property. Use only durable public HTTPS asset URLs, never localhost or temporary tunnel URLs.')]+#[Instructions('Default every request to create a new form to the guest draft workflow unless the user explicitly asks to save it in their connected OpnForm account or a workspace. A natural request such as "create a contact form" needs no login: read the schema and field catalog, validate the definition, call create_form_draft, then call preview_form_draft. Never ask the user to connect, call get_account_context, or call create_form_in_account when guest draft tools can satisfy the request. OAuth is required only for connected-account operations: saving directly to a workspace, managing existing account forms, publishing, trashing, and reading or exporting submissions. Enabling or selecting the plugin is not OAuth authentication. If an account-scoped tool challenges, ask the user to authenticate the OpnForm MCP server in the host; do not repeatedly retry from the guest workflow. In local Codex, start a new conversation after OAuth so the MCP client loads the stored credential. If guest draft tools are unexpectedly missing, do not substitute an authenticated tool unless the user requested account persistence; ask the user to start a new conversation with OpnForm selected before the first message. Use OpnForm MCP tools directly. Never invoke Codex or ChatGPT recursively, run `codex exec`, use shell or raw HTTP, inspect repositories or caches, or switch connectors. Read the schema and field catalog again before changing presentation, fields, layout, or media, then validate before saving. Focused presentation creates one step per block automatically: use full-width blocks, no page breaks or standalone media blocks, and attach optional media through the block image property. Use only durable public HTTPS asset URLs, never localhost or temporary tunnel URLs.')]class OpnFormServer extends Server{public int $maxPaginationLength = 100;diff --git a/api/app/Mcp/Tools/CreateFormDraftTool.php b/api/app/Mcp/Tools/CreateFormDraftTool.phpindex 57cce40ad..92a5a6262 100644--- a/api/app/Mcp/Tools/CreateFormDraftTool.php+++ b/api/app/Mcp/Tools/CreateFormDraftTool.php@@ -10,12 +10,14 @@ use Laravel\Mcp\Response;use Laravel\Mcp\ResponseFactory;use Laravel\Mcp\Server\Attributes\Description;use Laravel\Mcp\Server\Attributes\Name;+use Laravel\Mcp\Server\Attributes\Title;use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('create_form_draft')]-#[Description('Create a private server-side OpnForm draft that expires after seven days. Works without login. Returns a capability token once; keep it private and use it with get_form_draft and patch_form_draft. The form remains an unpublished draft.')]+#[Title('Create a Guest Form Draft')]+#[Description('Use this as the default creation tool whenever the user asks to create, build, or preview a new form without explicitly asking to save it in an OpnForm account or workspace. It works immediately without login; never request authentication or use create_form_in_account instead for this guest-first workflow. Creates a private unpublished draft that expires after seven days and returns a capability token once; keep it private and use it with get_form_draft, patch_form_draft, and preview_form_draft.')]#[IsReadOnly(false)]#[IsDestructive(false)]#[IsOpenWorld(false)]diff --git a/api/app/Mcp/Tools/CreateFormTool.php b/api/app/Mcp/Tools/CreateFormTool.phpindex 32e5f23ea..ca233ae52 100644--- a/api/app/Mcp/Tools/CreateFormTool.php+++ b/api/app/Mcp/Tools/CreateFormTool.php@@ -9,12 +9,14 @@ use Laravel\Mcp\Response;use Laravel\Mcp\ResponseFactory;use Laravel\Mcp\Server\Attributes\Description;use Laravel\Mcp\Server\Attributes\Name;+use Laravel\Mcp\Server\Attributes\Title;use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;-#[Name('create_form')]-#[Description('Create a form in an accessible writable workspace from the canonical definition. It is always saved as an unpublished draft. If the account has exactly one workspace, workspace_id may be omitted.')]+#[Name('create_form_in_account')]+#[Title('Save a Form to an OpnForm Account')]+#[Description('Use this authenticated tool only when the user explicitly asks to save a new form in their connected OpnForm account or a workspace. Do not use it for a generic request to create or preview a new form; use create_form_draft without login instead. Saves the canonical definition as an unpublished draft in an accessible writable workspace. If the account has exactly one workspace, workspace_id may be omitted.')]#[IsReadOnly(false)]#[IsDestructive(false)]#[IsOpenWorld(false)]diff --git a/api/app/Mcp/Tools/PatchFormDraftTool.php b/api/app/Mcp/Tools/PatchFormDraftTool.phpindex 6d2445375..5aa3df635 100644--- a/api/app/Mcp/Tools/PatchFormDraftTool.php+++ b/api/app/Mcp/Tools/PatchFormDraftTool.php@@ -14,9 +14,9 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('patch_form_draft')]-#[Description('Apply validated semantic operations to a private draft. Requires expected_version, so concurrent agent or editor changes cannot be silently overwritten. Supported ops: set_form_values, add_block, update_block, remove_block, move_block. Before changing presentation_style, fields, layout, or media, read opnform://reference/form-fields/v1; focused mode derives one step per block and media belongs in the block image property.')]+#[Description('Apply validated semantic operations to a private draft. Operations can replace or remove draft content. Requires expected_version, so concurrent agent or editor changes cannot be silently overwritten. Supported ops: set_form_values, add_block, update_block, remove_block, move_block. Before changing presentation_style, fields, layout, or media, read opnform://reference/form-fields/v1; focused mode derives one step per block and media belongs in the block image property.')]#[IsReadOnly(false)]-#[IsDestructive(false)]+#[IsDestructive]#[IsOpenWorld(false)]class PatchFormDraftTool extends GuestDraftMcpTool{diff --git a/api/app/Mcp/Tools/TrashFormTool.php b/api/app/Mcp/Tools/TrashFormTool.phpindex e73babb04..be69154e2 100644--- a/api/app/Mcp/Tools/TrashFormTool.php+++ b/api/app/Mcp/Tools/TrashFormTool.php@@ -14,10 +14,10 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('trash_form')]-#[Description('Move an accessible writable form at its current revision to soft-delete trash. Call only after explicit user confirmation. Restore and permanent deletion are intentionally not exposed.')]+#[Description('Move an accessible writable form at its current revision to soft-delete trash. A public form becomes unavailable. Call only after explicit user confirmation. Restore and permanent deletion are intentionally not exposed.')]#[IsReadOnly(false)]#[IsDestructive]-#[IsOpenWorld(false)]+#[IsOpenWorld]class TrashFormTool extends AuthenticatedMcpTool{public function handle(Request $request, McpFormManagementService $forms): ResponseFactorydiff --git a/api/app/Mcp/Tools/UpdateFormTool.php b/api/app/Mcp/Tools/UpdateFormTool.phpindex 15e3df4c9..00a6ff461 100644--- a/api/app/Mcp/Tools/UpdateFormTool.php+++ b/api/app/Mcp/Tools/UpdateFormTool.php@@ -14,10 +14,10 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;#[Name('update_form')]-#[Description('Replace the editable definition of an accessible form. Requires the revision value returned by get_form to prevent silent concurrent overwrites. This tool cannot publish or trash a form.')]+#[Description('Replace the editable definition of an accessible form. This can remove existing fields, and changes to an already-public form are immediately public. Requires the revision value returned by get_form to prevent silent concurrent overwrites. This tool cannot change visibility or trash a form.')]#[IsReadOnly(false)]-#[IsDestructive(false)]-#[IsOpenWorld(false)]+#[IsDestructive]+#[IsOpenWorld]class UpdateFormTool extends AuthenticatedMcpTool{public function handle(Request $request, McpFormManagementService $forms): ResponseFactorydiff --git a/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php b/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.phpindex 48f41f1ab..57d1d5378 100644--- a/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php+++ b/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php@@ -101,10 +101,23 @@ it('advertises guest and account tools with explicit per-tool auth policies', fu$response = $this->postJson('/mcp', $payload, $headers)->assertOk();$tools = collect($response->json('result.tools'))->keyBy('name');- expect($tools)->toHaveKeys(['create_form_draft', 'list_forms', 'trash_form'])+ expect($tools)->toHaveKeys(['create_form_draft', 'create_form_in_account', 'list_forms', 'trash_form'])+ ->not->toHaveKey('create_form')+ ->and($tools['create_form_draft']['title'])->toBe('Create a Guest Form Draft')+ ->and($tools['create_form_draft']['description'])+ ->toContain('default creation tool', 'works immediately without login', 'never request authentication')->and($tools['create_form_draft']['securitySchemes'])->toBe([['type' => 'noauth'],])+ ->and($tools['create_form_in_account']['title'])->toBe('Save a Form to an OpnForm Account')+ ->and($tools['create_form_in_account']['description'])+ ->toContain('only when the user explicitly asks', 'use create_form_draft without login instead')+ ->and($tools['create_form_in_account']['securitySchemes'])->toBe([+ [+ 'type' => 'oauth2',+ 'scopes' => ['mcp:use'],+ ],+ ])->and($tools['list_forms']['securitySchemes'])->toBe([['type' => 'oauth2',@@ -136,7 +149,7 @@ it('hides guest draft capabilities but keeps validation and OAuth tools on self-$toolNames = collect($toolsResponse->json('result.tools'))->pluck('name');expect($toolNames)- ->toContain('validate_form_definition', 'create_form', 'list_forms', 'list_submissions')+ ->toContain('validate_form_definition', 'create_form_in_account', 'list_forms', 'list_submissions')->not->toContain('create_form_draft','get_form_draft',diff --git a/api/tests/Feature/Mcp/McpFoundationTest.php b/api/tests/Feature/Mcp/McpFoundationTest.phpindex 369c1253f..7e6495f43 100644--- a/api/tests/Feature/Mcp/McpFoundationTest.php+++ b/api/tests/Feature/Mcp/McpFoundationTest.php@@ -30,13 +30,13 @@ it('exposes the OpnForm MCP endpoint and initializes the protocol', function ()->assertJsonPath('result.serverInfo.version', '1.0.0')->assertJsonPath('result.protocolVersion', '2025-06-18')->assertJsonPath('result.instructions', function (string $instructions): bool {- $discoveryInstructions = substr($instructions, 0, 512);+ $discoveryInstructions = substr($instructions, 0, 1024);- return str_contains($discoveryInstructions, 'Never invoke Codex or ChatGPT recursively')- && str_contains($discoveryInstructions, 'OpnForm selected before the first message')- && str_contains($discoveryInstructions, 'account, form, and submission tools require OAuth')- && str_contains($discoveryInstructions, 'Enabling the plugin is not OAuth authentication')- && str_contains($discoveryInstructions, 'start a new conversation after OAuth');+ return str_contains($discoveryInstructions, 'Default every request to create a new form to the guest draft workflow')+ && str_contains($discoveryInstructions, 'A natural request such as "create a contact form" needs no login')+ && str_contains($discoveryInstructions, 'Never ask the user to connect')+ && str_contains($discoveryInstructions, 'OAuth is required only for connected-account operations')+ && str_contains($discoveryInstructions, 'Enabling or selecting the plugin is not OAuth authentication');});});@@ -75,12 +75,17 @@ it('advertises explicit safety annotations for every MCP tool', function () {'validate_form_definition',];$writes = [- 'create_form','create_form_draft',+ 'create_form_in_account','export_submissions','open_form_draft_in_editor',- 'patch_form_draft','preview_form_draft',+ ];+ $destructivePrivateWrites = [+ 'patch_form_draft',+ ];+ $destructiveOpenWorldWrites = [+ 'trash_form','update_form',];@@ -95,16 +100,21 @@ it('advertises explicit safety annotations for every MCP tool', function () {'destructiveHint' => false,'openWorldHint' => false,]]))+ ->merge(collect($destructivePrivateWrites)->mapWithKeys(fn (string $name): array => [$name => [+ 'readOnlyHint' => false,+ 'destructiveHint' => true,+ 'openWorldHint' => false,+ ]]))+ ->merge(collect($destructiveOpenWorldWrites)->mapWithKeys(fn (string $name): array => [$name => [+ 'readOnlyHint' => false,+ 'destructiveHint' => true,+ 'openWorldHint' => true,+ ]]))->put('publish_form', ['readOnlyHint' => false,'destructiveHint' => false,'openWorldHint' => true,])- ->put('trash_form', [- 'readOnlyHint' => false,- 'destructiveHint' => true,- 'openWorldHint' => false,- ])->sortKeys()->all();diff --git a/plugins/opnform/skills/opnform/SKILL.md b/plugins/opnform/skills/opnform/SKILL.mdindex 73ab52e8b..4482c941c 100644--- a/plugins/opnform/skills/opnform/SKILL.md+++ b/plugins/opnform/skills/opnform/SKILL.md@@ -7,6 +7,8 @@ description: Use this when a user asks to create, preview, revise, claim, or manUse the OpnForm MCP server for OpnForm operations. Start as a guest when the user only needs a new form and an interactive preview. Connect an account only when account or workspace data is required.+Treat an unqualified request such as “create a contact form”, “build a survey”, or “make me a registration form” as a guest draft request. Do not infer that the user wants account persistence merely because the plugin offers OAuth or the host displays a Connect button. Do not ask the user to sign in, call `get_account_context`, or call `create_form_in_account` unless the user explicitly asks to save the new form in their OpnForm account or a workspace.+## Require native MCP access- Use only the OpnForm MCP tools and resources exposed by the current host session.@@ -18,6 +20,8 @@ Use the OpnForm MCP server for OpnForm operations. Start as a guest when the use## Build and revise a guest draft+This is the default workflow for new-form requests, including when the user does not mention “guest”, “draft”, “preview”, or “without login”. The presence of OAuth-protected account tools does not make authentication a prerequisite for these steps.+1. Read `opnform://schemas/agent-form-definition/v1` and `opnform://reference/form-fields/v1` before generating a definition. Re-read the field reference before changing presentation style, fields, layout, or media later in the conversation. Do not inspect the OpnForm source tree or guess product behavior when the MCP resources describe it.2. Call `validate_form_definition`. Resolve every validation error before creating or saving a draft.3. Call `create_form_draft` with the validated definition.@@ -41,10 +45,12 @@ The browser editor keeps the guest draft available through an HttpOnly session.Authenticated tools remain discoverable before the account is connected. When the user asks for account, form, or submission data, call `get_account_context`; if the host returns an OAuth challenge, ask the user to complete the connection. In local Codex, continue from a new conversation after OAuth instead of repeatedly retrying from the guest conversation. Do not report that account tools are unavailable merely because the current session started as a guest.+For new forms, enter this authenticated workflow only when the user explicitly asks to save directly to their account or names an account/workspace destination. A request to create, build, or preview a form by itself remains in the guest workflow even when an account connection is available.+After authentication, use the account context to choose a workspace. If exactly one writable workspace is available, select it without asking. If several are available, call `list_workspaces` and ask the user which one to use. Workspace access is read-only through MCP; do not attempt workspace administration.- Use form listing and lookup tools to identify the target before changing it.-- `create_form` creates a draft. After creation, ask whether the user wants it published.+- `create_form_in_account` creates an account-owned draft. After creation, ask whether the user wants it published.- Before `update_form`, `publish_form`, or `trash_form`, fetch the form and pass its current `revision` as `expected_revision`. On conflict, fetch, reconcile, and retry instead of overwriting newer changes.- Call `publish_form` only after the user explicitly confirms publication, then pass the confirmed form's `expected_revision` and `confirm_publish: true`.- Call `trash_form` only after the user explicitly confirms moving the form to trash, then pass the confirmed form's `expected_revision` and `confirm_trash: true`. MCP does not expose form restoration or permanent deletion.